1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2015 Joyent, Inc.
13.\"
14.Dd November 27, 2023
15.Dt PR_WAITID 3PROC
16.Os
17.Sh NAME
18.Nm pr_waitid
19.Nd inject waitid system call into victim process
20.Sh LIBRARY
21.Lb libproc
22.Sh SYNOPSIS
23.In libproc.h
24.Ft int
25.Fo pr_waitid
26.Fa "struct ps_prochandle *P"
27.Fa "idtype_t idtype"
28.Fa "id_t id"
29.Fa "siginfo_t *infop"
30.Fa "int options"
31.Fc
32.Sh DESCRIPTION
33The
34.Fn pr_waitid
35function injects the
36.Xr waitid 2
37system call into the target process
38.Fa P
39by means of the agent LWP.
40If the process handle
41.Fa P
42is the value
43.Dv NULL
44then this will be equivalent to calling
45.Xr waitid 2
46on the currently running process.
47.Pp
48The arguments
49.Fa idtype ,
50.Fa id ,
51.Fa infop ,
52and
53.Fa options
54have the same meaning as in
55.Xr waitid 2 .
56See
57.Xr waitid 2
58for the full description and purpose of the
59.Sy waitid
60system call and its arguments.
61.Pp
62The
63.Fn pr_waitid
64function only works on active processes.
65Process handles that correspond to core files, zombie processes, or ELF objects
66do not support system call injection.
67.Sh RETURN VALUES
68Upon successful completion, the
69.Fn pr_waitid
70function's return value is that described in
71.Xr waitid 2 .
72Otherwise,
73.Sy -1
74is returned and
75.Sy errno
76is set to
77.Er ENOSYS
78to indicate that the system call could not be injected.
79.Sh ERRORS
80For the full list of errors see the
81.Sy ERRORS
82section in
83.Xr waitid 2 .
84.Pp
85The
86.Fn pr_waitid
87function will fail if:
88.Bl -tag -width Er
89.It Er ENOSYS
90An error occurred while trying to invoke the agent LWP and inject a
91system call in the process handle
92.Fa P
93or the process handle
94.Fa P
95does not support system call injection.
96.El
97.Sh INTERFACE STABILITY
98.Sy Uncommitted
99.Sh MT-LEVEL
100See
101.Sy LOCKING
102in
103.Xr libproc 3LIB .
104.Sh SEE ALSO
105.Xr waitid 2 ,
106.Xr libproc 3LIB ,
107.Xr proc 5
108