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