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 11, 2016 15.Dt PROC_ARG_GRAB 3PROC 16.Os 17.Sh NAME 18.Nm proc_arg_grab , 19.Nm proc_arg_xrgab 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_grag 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 opens. 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 if there is a thread specification present in 100.Fa arg , 101it will be validated to see if it is a valid range and then a pointer to 102the start of the thread specification will be stored in 103.Fa lwps . 104For more information on determining process range validity, see 105.Xr proc_lwp_range_valid 3PROC 106for more information on valid and invalid tread specifications. 107.Sh RETURN VALUES 108Upon successful completion, the 109.Fn proc_arg_grab 110and 111.Fn proc_arg_xgrab 112functions return a pointer to the process handle is returned. 113Otherwise, 114.Dv NULL 115is returned and 116.Fa perr 117is set to include a more specific error. 118.Sh ERRORS 119For a full list of additional errors, see the 120.Sy ERRORS 121section in 122.Xr Pgrab 3PROC 123and 124.Xr Pgrab_core 3PROC . 125.Pp 126The 127.Fn proc_arg_grab 128and 129.Fn proc_arg_xgrab 130function will fail if: 131.Bl -tag -width Er 132.It Er G_BADLWPS 133.Fa arg 134contains an invalid thread specification. 135.It Er G_NOCORE 136.Dv PR_ARG_CORES 137was set and no core file could be found corresponding to 138.Fa arg . 139.It Er G_NOPROC 140.Dv PR_ARG_PIDS 141was set and no process could be found corresponding to 142.Fa arg . 143.It Er G_NOPROCORCORE 144Both 145.Dv PR_ARG_CORES 146and 147.Dv PR_ARG_NOPROC 148were set and no process or core file could be found corresponding to 149.Fa arg . 150.El 151.Sh INTERFACE STABILITY 152.Sy Uncommitted 153.Sh MT-LEVEL 154.Sy MT-Safe 155.Sh SEE ALSO 156.Xr libproc 3LIB , 157.Xr Pgrab 3PROC , 158.Xr Pgrab_core 3PROC , 159.Xr Prelease 3PROC , 160.Xr proc_lwp_range_valid 3PROC , 161.Xr proc 4 162