1 PROC_ARG_GRAB(3PROC)   Process Control Library Functions  PROC_ARG_GRAB(3PROC)
   2 
   3 NAME
   4      proc_arg_grab, proc_arg_xgrab - process grabbing utility function
   5 
   6 SYNOPSIS
   7      Process Control Library (libproc, -lproc)
   8      #include <libproc.h>
   9 
  10      struct ps_prochandle
  11      proc_arg_grag(const char *arg, int oflag, int gflag, int *perr);
  12 
  13      struct ps_prochandle
  14      proc_arg_xgrab(const char *arg, const char *path, int oflag, int gflag,
  15          int *perr, const char **lwps);
  16 
  17 DESCRIPTION
  18      The proc_arg_grab() and proc_arg_xgrab() functions are utility functions
  19      which process arguments pointing to a currently active process or a core
  20      file and returns a process handle to it.
  21 
  22      The string arg contains the name of something to try and open.  How it is
  23      interpreted depends on the value of oflag.  The following values may be
  24      passed in as a bitwise-exclusive-OR for oflag:
  25 
  26            PR_ARG_PIDS   Allows arg to specify process IDs and /proc
  27                          arguments.
  28 
  29            PR_ARG_CORES  Allows arg to specify core files.
  30 
  31            PR_ARG_ANY    Encompasses all of the previous opens.
  32 
  33      The argument gflag controls the behavior when the corresponding process
  34      grabbing function is called by the underlying system.  For a list of
  35      flags that may be passed in here, see Pgrab(3PROC) and Pgrab_core(3PROC).
  36 
  37      The argument perr must be a non-NULL pointer and in the event that the
  38      proc_arg_grab() or proc_arg_xgrab() functions fail, then perr will be
  39      updated with a more detailed error number.
  40 
  41      The path argument allows a search path for its binaries to be specified
  42      in case a core file is found and opened.
  43 
  44      If the lwps argument is non-NULL, then if there is a thread specification
  45      present in arg, it will be validated to see if it is a valid range and
  46      then a pointer to the start of the thread specification will be stored in
  47      lwps.  For more information on determining process range validity, see
  48      proc_lwp_range_valid(3PROC) for more information on valid and invalid
  49      tread specifications.
  50 
  51 RETURN VALUES
  52      Upon successful completion, the proc_arg_grab() and proc_arg_xgrab()
  53      functions return a pointer to the process handle is returned.  Otherwise,
  54      NULL is returned and perr is set to include a more specific error.
  55 
  56 ERRORS
  57      For a full list of additional errors, see the ERRORS section in
  58      Pgrab(3PROC) and Pgrab_core(3PROC).
  59 
  60      The proc_arg_grab() and proc_arg_xgrab() function will fail if:
  61 
  62      G_BADLWPS          arg contains an invalid thread specification.
  63 
  64      G_NOCORE           PR_ARG_CORES was set and no core file could be found
  65                         corresponding to arg.
  66 
  67      G_NOPROC           PR_ARG_PIDS was set and no process could be found
  68                         corresponding to arg.
  69 
  70      G_NOPROCORCORE     Both PR_ARG_CORES and PR_ARG_NOPROC were set and no
  71                         process or core file could be found corresponding to
  72                         arg.
  73 
  74 INTERFACE STABILITY
  75      Uncommitted
  76 
  77 MT-LEVEL
  78      MT-Safe
  79 
  80 SEE ALSO
  81      libproc(3LIB), Pgrab(3PROC), Pgrab_core(3PROC), Prelease(3PROC),
  82      proc_lwp_range_valid(3PROC), proc(4)
  83 
  84 illumos                         August 20, 2019                        illumos