This file and its contents are supplied under the terms of the
Common Development and Distribution License ("CDDL"), version 1.0.
You may only use this file in accordance with the terms of version
1.0 of the CDDL.

A full copy of the text of the CDDL should have accompanied this
source. A copy of the CDDL is also available via the Internet at
http://www.illumos.org/license/CDDL.


Copyright 2015 Joyent, Inc.

.Dd May 11, 2016 .Dt PROC_ARG_GRAB 3PROC .Os .Sh NAME .Nm proc_arg_grab , .Nm proc_arg_xrgab .Nd process grabbing utility function .Sh SYNOPSIS .Lb libproc n libproc.h .Ft "struct ps_prochandle" .Fo proc_arg_grag .Fa "const char *arg" .Fa "int oflag" .Fa "int gflag" .Fa "int *perr" .Fc .Ft "struct ps_prochandle" .Fo proc_arg_xgrab .Fa "const char *arg" .Fa "const char *path" .Fa "int oflag" .Fa "int gflag" .Fa "int *perr" .Fa "const char **lwps" .Fc .Sh DESCRIPTION The .Fn proc_arg_grab and .Fn proc_arg_xgrab functions are utility functions which process arguments pointing to a currently active process or a core file and returns a process handle to it.

p The string .Fa arg contains the name of something to try and open. How it is interpreted depends on the value of .Fa oflag . The following values may be passed in as a bitwise-exclusive-OR for .Fa oflag : l -tag -width Dv -offset indent t Dv PR_ARG_PIDS Allows .Fa arg to specify process IDs and /proc arguments. t Dv PR_ARG_CORES Allows .Fa arg to specify core files. t PR_ARG_ANY Encompasses all of the previous opens. .El

p The argument .Fa gflag controls the behavior when the corresponding process grabbing function is called by the underlying system. For a list of flags that may be passed in here, see .Xr Pgrab 3PROC and .Xr Pgrab_core 3PROC .

p The argument .Fa perr must be a

f non- Dv NULL pointer and in the event that the .Fn proc_arg_grab or .Fn proc_arg_xgrab functions fail, then .Fa perr will be updated with a more detailed error number.

p The .Fa path argument allows a search path for its binaries to be specified in case a core file is found and opened.

p If the .Fa lwps argument is

f non- Dv NULL , then if there is a thread specification present in .Fa arg , it will be validated to see if it is a valid range and then a pointer to the start of the thread specification will be stored in .Fa lwps . For more information on determining process range validity, see .Xr proc_lwp_range_valid 3PROC for more information on valid and invalid tread specifications. .Sh RETURN VALUES Upon successful completion, the .Fn proc_arg_grab and .Fn proc_arg_xgrab functions return a pointer to the process handle is returned. Otherwise, .Dv NULL is returned and .Fa perr is set to include a more specific error. .Sh ERRORS For a full list of additional errors, see the .Sy ERRORS section in .Xr Pgrab 3PROC and .Xr Pgrab_core 3PROC .

p The .Fn proc_arg_grab and .Fn proc_arg_xgrab function will fail if: l -tag -width Er t Er G_BADLWPS .Fa arg contains an invalid thread specification. t Er G_NOCORE .Dv PR_ARG_CORES was set and no core file could be found corresponding to .Fa arg . t Er G_NOPROC .Dv PR_ARG_PIDS was set and no process could be found corresponding to .Fa arg . t Er G_NOPROCORCORE Both .Dv PR_ARG_CORES and .Dv PR_ARG_NOPROC were set and no process or core file could be found corresponding to .Fa arg . .El .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL .Sy MT-Safe .Sh SEE ALSO .Xr libproc 3LIB , .Xr Pgrab 3PROC , .Xr Pgrab_core 3PROC , .Xr Prelease 3PROC , .Xr proc_lwp_range_valid 3PROC , .Xr proc 4