143051d27SRobert Mustacchi.\" 243051d27SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 343051d27SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 443051d27SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 543051d27SRobert Mustacchi.\" 1.0 of the CDDL. 643051d27SRobert Mustacchi.\" 743051d27SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 843051d27SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 943051d27SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1043051d27SRobert Mustacchi.\" 1143051d27SRobert Mustacchi.\" 1243051d27SRobert Mustacchi.\" Copyright 2015 Joyent, Inc. 1343051d27SRobert Mustacchi.\" 14*a7d7cafeSRobert Mustacchi.Dd November 27, 2023 1543051d27SRobert Mustacchi.Dt PROC_ARG_GRAB 3PROC 1643051d27SRobert Mustacchi.Os 1743051d27SRobert Mustacchi.Sh NAME 1843051d27SRobert Mustacchi.Nm proc_arg_grab , 1995adbecaSRobert Mustacchi.Nm proc_arg_xgrab 2043051d27SRobert Mustacchi.Nd process grabbing utility function 21*a7d7cafeSRobert Mustacchi.Sh LIBRARY 2243051d27SRobert Mustacchi.Lb libproc 23*a7d7cafeSRobert Mustacchi.Sh SYNOPSIS 2443051d27SRobert Mustacchi.In libproc.h 2543051d27SRobert Mustacchi.Ft "struct ps_prochandle" 2695adbecaSRobert Mustacchi.Fo proc_arg_grab 2743051d27SRobert Mustacchi.Fa "const char *arg" 2843051d27SRobert Mustacchi.Fa "int oflag" 2943051d27SRobert Mustacchi.Fa "int gflag" 3043051d27SRobert Mustacchi.Fa "int *perr" 3143051d27SRobert Mustacchi.Fc 3243051d27SRobert Mustacchi.Ft "struct ps_prochandle" 3343051d27SRobert Mustacchi.Fo proc_arg_xgrab 3443051d27SRobert Mustacchi.Fa "const char *arg" 3543051d27SRobert Mustacchi.Fa "const char *path" 3643051d27SRobert Mustacchi.Fa "int oflag" 3743051d27SRobert Mustacchi.Fa "int gflag" 3843051d27SRobert Mustacchi.Fa "int *perr" 3943051d27SRobert Mustacchi.Fa "const char **lwps" 4043051d27SRobert Mustacchi.Fc 4143051d27SRobert Mustacchi.Sh DESCRIPTION 4243051d27SRobert MustacchiThe 4343051d27SRobert Mustacchi.Fn proc_arg_grab 4443051d27SRobert Mustacchiand 4543051d27SRobert Mustacchi.Fn proc_arg_xgrab 4643051d27SRobert Mustacchifunctions are utility functions which process arguments pointing to a 4743051d27SRobert Mustacchicurrently active process or a core file and returns a process handle to 4843051d27SRobert Mustacchiit. 4943051d27SRobert Mustacchi.Pp 5043051d27SRobert MustacchiThe string 5143051d27SRobert Mustacchi.Fa arg 5272d3dbb9SYuri Pankovcontains the name of something to try and open. 5372d3dbb9SYuri PankovHow it is interpreted depends on the value of 5443051d27SRobert Mustacchi.Fa oflag . 5543051d27SRobert MustacchiThe following values may be passed in as a bitwise-exclusive-OR for 5643051d27SRobert Mustacchi.Fa oflag : 5743051d27SRobert Mustacchi.Bl -tag -width Dv -offset indent 5843051d27SRobert Mustacchi.It Dv PR_ARG_PIDS 5943051d27SRobert MustacchiAllows 6043051d27SRobert Mustacchi.Fa arg 6143051d27SRobert Mustacchito specify process IDs and /proc arguments. 6243051d27SRobert Mustacchi.It Dv PR_ARG_CORES 6343051d27SRobert MustacchiAllows 6443051d27SRobert Mustacchi.Fa arg 6543051d27SRobert Mustacchito specify core files. 6643051d27SRobert Mustacchi.It PR_ARG_ANY 6795adbecaSRobert MustacchiEncompasses all of the previous flags. 6843051d27SRobert Mustacchi.El 6943051d27SRobert Mustacchi.Pp 7043051d27SRobert MustacchiThe argument 7143051d27SRobert Mustacchi.Fa gflag 7243051d27SRobert Mustacchicontrols the behavior when the corresponding process grabbing function 7372d3dbb9SYuri Pankovis called by the underlying system. 7472d3dbb9SYuri PankovFor a list of flags that may be passed in here, see 7543051d27SRobert Mustacchi.Xr Pgrab 3PROC 7643051d27SRobert Mustacchiand 7743051d27SRobert Mustacchi.Xr Pgrab_core 3PROC . 7843051d27SRobert Mustacchi.Pp 7943051d27SRobert MustacchiThe argument 8043051d27SRobert Mustacchi.Fa perr 8143051d27SRobert Mustacchimust be a 8243051d27SRobert Mustacchi.Pf non- Dv NULL 8343051d27SRobert Mustacchipointer and in the event that the 8443051d27SRobert Mustacchi.Fn proc_arg_grab 8543051d27SRobert Mustacchior 8643051d27SRobert Mustacchi.Fn proc_arg_xgrab 8743051d27SRobert Mustacchifunctions fail, then 8843051d27SRobert Mustacchi.Fa perr 8943051d27SRobert Mustacchiwill be updated with a more detailed error number. 9043051d27SRobert Mustacchi.Pp 9143051d27SRobert MustacchiThe 9243051d27SRobert Mustacchi.Fa path 9343051d27SRobert Mustacchiargument allows a search path for its binaries to be specified in case a 9443051d27SRobert Mustacchicore file is found and opened. 9543051d27SRobert Mustacchi.Pp 9643051d27SRobert MustacchiIf the 9743051d27SRobert Mustacchi.Fa lwps 9843051d27SRobert Mustacchiargument is 9943051d27SRobert Mustacchi.Pf non- Dv NULL , 10095adbecaSRobert Mustacchithen the functions will treat any portion of 10195adbecaSRobert Mustacchi.Fa arg 10295adbecaSRobert Mustacchiafter a 10395adbecaSRobert Mustacchi.Sq / 10495adbecaSRobert Mustacchicharacter as a thread range. 10595adbecaSRobert MustacchiThe thread range will be validated as though a call to the 10643051d27SRobert Mustacchi.Xr proc_lwp_range_valid 3PROC 10795adbecaSRobert Mustacchifunction had been made, and a pointer to the start of the range will be 10895adbecaSRobert Mustacchistored in 10995adbecaSRobert Mustacchi.Fa lwps . 11095adbecaSRobert MustacchiFor a discussion of what constitutes a valid thread range, please see 11195adbecaSRobert Mustacchi.Xr proc_lwp_range_valid 3PROC . 11243051d27SRobert Mustacchi.Sh RETURN VALUES 11343051d27SRobert MustacchiUpon successful completion, the 11443051d27SRobert Mustacchi.Fn proc_arg_grab 11543051d27SRobert Mustacchiand 11643051d27SRobert Mustacchi.Fn proc_arg_xgrab 11795adbecaSRobert Mustacchifunctions return a pointer to the process handle. 11843051d27SRobert MustacchiOtherwise, 11943051d27SRobert Mustacchi.Dv NULL 12043051d27SRobert Mustacchiis returned and 12143051d27SRobert Mustacchi.Fa perr 12243051d27SRobert Mustacchiis set to include a more specific error. 12343051d27SRobert Mustacchi.Sh ERRORS 12443051d27SRobert MustacchiFor a full list of additional errors, see the 12543051d27SRobert Mustacchi.Sy ERRORS 12643051d27SRobert Mustacchisection in 12743051d27SRobert Mustacchi.Xr Pgrab 3PROC 12843051d27SRobert Mustacchiand 12943051d27SRobert Mustacchi.Xr Pgrab_core 3PROC . 13043051d27SRobert Mustacchi.Pp 13143051d27SRobert MustacchiThe 13243051d27SRobert Mustacchi.Fn proc_arg_grab 13343051d27SRobert Mustacchiand 13443051d27SRobert Mustacchi.Fn proc_arg_xgrab 13543051d27SRobert Mustacchifunction will fail if: 13643051d27SRobert Mustacchi.Bl -tag -width Er 13743051d27SRobert Mustacchi.It Er G_BADLWPS 13843051d27SRobert Mustacchi.Fa arg 13943051d27SRobert Mustacchicontains an invalid thread specification. 14043051d27SRobert Mustacchi.It Er G_NOCORE 14143051d27SRobert Mustacchi.Dv PR_ARG_CORES 14243051d27SRobert Mustacchiwas set and no core file could be found corresponding to 14343051d27SRobert Mustacchi.Fa arg . 14443051d27SRobert Mustacchi.It Er G_NOPROC 14543051d27SRobert Mustacchi.Dv PR_ARG_PIDS 14643051d27SRobert Mustacchiwas set and no process could be found corresponding to 14743051d27SRobert Mustacchi.Fa arg . 14843051d27SRobert Mustacchi.It Er G_NOPROCORCORE 14943051d27SRobert MustacchiBoth 15043051d27SRobert Mustacchi.Dv PR_ARG_CORES 15143051d27SRobert Mustacchiand 15243051d27SRobert Mustacchi.Dv PR_ARG_NOPROC 15343051d27SRobert Mustacchiwere set and no process or core file could be found corresponding to 15443051d27SRobert Mustacchi.Fa arg . 15543051d27SRobert Mustacchi.El 15643051d27SRobert Mustacchi.Sh INTERFACE STABILITY 15743051d27SRobert Mustacchi.Sy Uncommitted 15843051d27SRobert Mustacchi.Sh MT-LEVEL 15943051d27SRobert Mustacchi.Sy MT-Safe 16043051d27SRobert Mustacchi.Sh SEE ALSO 16143051d27SRobert Mustacchi.Xr libproc 3LIB , 16243051d27SRobert Mustacchi.Xr Pgrab 3PROC , 16343051d27SRobert Mustacchi.Xr Pgrab_core 3PROC , 16443051d27SRobert Mustacchi.Xr Prelease 3PROC , 16543051d27SRobert Mustacchi.Xr proc_lwp_range_valid 3PROC , 166bbf21555SRichard Lowe.Xr proc 5 167