PROC_ARG_GRAB(3PROC) Process Control Library Functions PROC_ARG_GRAB(3PROC)

proc_arg_grab, proc_arg_xgrab — process grabbing utility function

Process Control Library (libproc, -lproc)

#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);

The () and () 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:

Allows arg to specify process IDs and /proc arguments.
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 () or () 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).

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.

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:

arg contains an invalid thread specification.
was set and no core file could be found corresponding to arg.
was set and no process could be found corresponding to arg.
Both PR_ARG_CORES and PR_ARG_NOPROC were set and no process or core file could be found corresponding to arg.

libproc(3LIB), Pgrab(3PROC), Pgrab_core(3PROC), Prelease(3PROC), proc_lwp_range_valid(3PROC), proc(5)

November 27, 2023 OmniOS