xref: /illumos-gate/usr/src/man/man3proc/proc_arg_grab.3proc (revision c21bd51d7acbaf77116c4cc3a23dfc6d16c637c2)
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 May 22, 2020
15.Dt PROC_ARG_GRAB 3PROC
16.Os
17.Sh NAME
18.Nm proc_arg_grab ,
19.Nm proc_arg_xgrab
20.Nd process grabbing utility function
21.Sh SYNOPSIS
22.Lb libproc
23.In libproc.h
24.Ft "struct ps_prochandle"
25.Fo proc_arg_grab
26.Fa "const char *arg"
27.Fa "int oflag"
28.Fa "int gflag"
29.Fa "int *perr"
30.Fc
31.Ft "struct ps_prochandle"
32.Fo proc_arg_xgrab
33.Fa "const char *arg"
34.Fa "const char *path"
35.Fa "int oflag"
36.Fa "int gflag"
37.Fa "int *perr"
38.Fa "const char **lwps"
39.Fc
40.Sh DESCRIPTION
41The
42.Fn proc_arg_grab
43and
44.Fn proc_arg_xgrab
45functions are utility functions which process arguments pointing to a
46currently active process or a core file and returns a process handle to
47it.
48.Pp
49The string
50.Fa arg
51contains the name of something to try and open.
52How it is interpreted depends on the value of
53.Fa oflag .
54The following values may be passed in as a bitwise-exclusive-OR for
55.Fa oflag :
56.Bl -tag -width Dv -offset indent
57.It Dv PR_ARG_PIDS
58Allows
59.Fa arg
60to specify process IDs and /proc arguments.
61.It Dv PR_ARG_CORES
62Allows
63.Fa arg
64to specify core files.
65.It PR_ARG_ANY
66Encompasses all of the previous flags.
67.El
68.Pp
69The argument
70.Fa gflag
71controls the behavior when the corresponding process grabbing function
72is called by the underlying system.
73For a list of flags that may be passed in here, see
74.Xr Pgrab 3PROC
75and
76.Xr Pgrab_core 3PROC .
77.Pp
78The argument
79.Fa perr
80must be a
81.Pf non- Dv NULL
82pointer and in the event that the
83.Fn proc_arg_grab
84or
85.Fn proc_arg_xgrab
86functions fail, then
87.Fa perr
88will be updated with a more detailed error number.
89.Pp
90The
91.Fa path
92argument allows a search path for its binaries to be specified in case a
93core file is found and opened.
94.Pp
95If the
96.Fa lwps
97argument is
98.Pf non- Dv NULL ,
99then the functions will treat any portion of
100.Fa arg
101after a
102.Sq /
103character as a thread range.
104The thread range will be validated as though a call to the
105.Xr proc_lwp_range_valid 3PROC
106function had been made, and a pointer to the start of the range will be
107stored in
108.Fa lwps .
109For a discussion of what constitutes a valid thread range, please see
110.Xr proc_lwp_range_valid 3PROC .
111.Sh RETURN VALUES
112Upon successful completion, the
113.Fn proc_arg_grab
114and
115.Fn proc_arg_xgrab
116functions return a pointer to the process handle.
117Otherwise,
118.Dv NULL
119is returned and
120.Fa perr
121is set to include a more specific error.
122.Sh ERRORS
123For a full list of additional errors, see the
124.Sy ERRORS
125section in
126.Xr Pgrab 3PROC
127and
128.Xr Pgrab_core 3PROC .
129.Pp
130The
131.Fn proc_arg_grab
132and
133.Fn proc_arg_xgrab
134function will fail if:
135.Bl -tag -width Er
136.It Er G_BADLWPS
137.Fa arg
138contains an invalid thread specification.
139.It Er G_NOCORE
140.Dv PR_ARG_CORES
141was set and no core file could be found corresponding to
142.Fa arg .
143.It Er G_NOPROC
144.Dv PR_ARG_PIDS
145was set and no process could be found corresponding to
146.Fa arg .
147.It Er G_NOPROCORCORE
148Both
149.Dv PR_ARG_CORES
150and
151.Dv PR_ARG_NOPROC
152were set and no process or core file could be found corresponding to
153.Fa arg .
154.El
155.Sh INTERFACE STABILITY
156.Sy Uncommitted
157.Sh MT-LEVEL
158.Sy MT-Safe
159.Sh SEE ALSO
160.Xr libproc 3LIB ,
161.Xr Pgrab 3PROC ,
162.Xr Pgrab_core 3PROC ,
163.Xr Prelease 3PROC ,
164.Xr proc_lwp_range_valid 3PROC ,
165.Xr proc 4
166