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