PROC_ARG_GRAB(3PROC) Process Control Library Functions PROC_ARG_GRAB(3PROC)
NAME
proc_arg_grab,
proc_arg_xgrab - process grabbing utility function
LIBRARY
Process Control Library (libproc, -lproc)
SYNOPSIS
#include <libproc.h> struct ps_prochandle proc_arg_grab(
const char *arg,
int oflag,
int gflag,
int *perr);
struct ps_prochandle proc_arg_xgrab(
const char *arg,
const char *path,
int oflag,
int gflag,
int *perr,
const char **lwps);
DESCRIPTION
The
proc_arg_grab() and
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.
The string
arg contains the name of something to try and open. How it
is interpreted depends on the value of
oflag. The following values may
be passed in as a bitwise-exclusive-OR for
oflag:
PR_ARG_PIDS Allows
arg to specify process IDs and /proc
arguments.
PR_ARG_CORES Allows
arg to specify core files.
PR_ARG_ANY Encompasses all of the previous flags.
The argument
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
Pgrab(3PROC) and
Pgrab_core(3PROC).
The argument
perr must be a non-NULL pointer and in the event that the
proc_arg_grab() or
proc_arg_xgrab() functions fail, then
perr will be
updated with a more detailed error number.
The
path argument allows a search path for its binaries to be specified
in case a core file is found and opened.
If the
lwps argument is non-NULL, then the functions will treat any
portion of
arg after a `/' character as a thread range. The thread
range will be validated as though a call to the
proc_lwp_range_valid(3PROC) function had been made, and a pointer to
the start of the range will be stored in
lwps. For a discussion of
what constitutes a valid thread range, please see
proc_lwp_range_valid(3PROC).
RETURN VALUES
Upon successful completion, the
proc_arg_grab() and
proc_arg_xgrab()
functions return a pointer to the process handle. Otherwise, NULL is
returned and
perr is set to include a more specific error.
ERRORS
For a full list of additional errors, see the
ERRORS section in
Pgrab(3PROC) and
Pgrab_core(3PROC).
The
proc_arg_grab() and
proc_arg_xgrab() function will fail if:
G_BADLWPS
arg contains an invalid thread specification.
G_NOCORE PR_ARG_CORES was set and no core file could be found
corresponding to
arg.
G_NOPROC PR_ARG_PIDS was set and no process could be found
corresponding to
arg.
G_NOPROCORCORE Both PR_ARG_CORES and PR_ARG_NOPROC were set and no
process or core file could be found corresponding to
arg.
INTERFACE STABILITY
UncommittedMT-LEVEL MT-SafeSEE ALSO
libproc(3LIB),
Pgrab(3PROC),
Pgrab_core(3PROC),
Prelease(3PROC),
proc_lwp_range_valid(3PROC),
proc(5)illumos November 27, 2023 illumos
