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