8158 Want named threads API
9857 proc manpages should have LIBRARY section

          --- old/usr/src/man/man3proc/Pgrab.3proc.man.txt
          +++ new/usr/src/man/man3proc/Pgrab.3proc.man.txt
   1    1  PGRAB(3PROC)           Process Control Library Functions          PGRAB(3PROC)
   2    2  
   3    3  NAME
   4    4       Pgrab - grab and control a process
   5    5  
   6      -SYNOPSIS
        6 +LIBRARY
   7    7       Process Control Library (libproc, -lproc)
        8 +
        9 +SYNOPSIS
   8   10       #include <libproc.h>
   9   11  
  10   12       struct ps_prochandle *
  11   13       Pgrab(pid_t pid, int flags, int *perr);
  12   14  
  13   15  DESCRIPTION
  14   16       The Pgrab() function attempts to grab the process identified by pid and
  15   17       returns a handle to it that allows the process to be controlled,
  16   18       interrogated, and manipulated.  This interface only works with processes
  17   19       that already exist.  Use Pgrab_core(3PROC) for core files and

  18   20       Pcreate(3PROC) to create processes.
  19   21  
  20   22       A grabbed process undergoes the following changes unless flags is set to
  21   23       the contrary:
  22   24  
  23   25             o   The process is stopped
  24   26  
  25   27             o   All other tracing flags are cleared
  26   28  
  27   29             o   The grab is exclusive.  If any existing handles to this process
  28   30                 exist or anyone else is using the underlying facilities of the
  29   31                 /proc file system to control this process, it will fail.
  30   32  
  31   33             o   Unless the process is already stopped, the PR_RLC flag is set
  32   34                 indicating the process should run-on-last-close.  Allowing the
  33   35                 process to resume running if its controlling process dies.
  34   36  
  35   37       Grabbing a process is a destructive action.  Stopping a process stops
  36   38       execution of all its threads.  The impact of stopping a process depends
  37   39       on the purpose of that process.  For example, if one stops a process
  38   40       that's primarily doing computation, then its computation is delayed the
  39   41       entire time that it is stopped.  However, if instead this is an active
  40   42       TCP server, then the accept backlog may fill causing connection errors
  41   43       and potentially connection time out errors.
  42   44  
  43   45       Special care must be taken to ensure that a stopped process continues,
  44   46       even if the controlling process terminates.  If the controlling process
  45   47       disables the PR_RLC flag or the process was already stopped, then the
  46   48       process remains stopped after the controlling process terminates.
  47   49       Exercise caution when changing this behavior.
  48   50  
  49   51       Many of these default behaviors can be controlled by passing values to
  50   52       the flags argument.  Values for flags are constructed by a bitwise-
  51   53       inclusive-OR of flags from the following list:
  52   54  
  53   55             PGRAB_RETAIN  Indicates that any existing tracing flags on pid
  54   56                           should be retained.  If this flag is not specified,
  55   57                           they will be cleared as part of creating the libproc
  56   58                           handle for this process.
  57   59  
  58   60                           Normally extant tracing flags are cleared when a
  59   61                           process is grabbed.
  60   62  
  61   63             PGRAB_FORCE   Indicates that the process should not be grabbed
  62   64                           exclusively.  Care should be taken with this option.
  63   65                           If other consumers are manipulating the process, then
  64   66                           this may result in surprising behavior as the process
  65   67                           is being manipulated from multiple points of control
  66   68                           at the same time.
  67   69  
  68   70                           Normally an attempt will be made to grab the process
  69   71                           exclusively and fail if it is already in use.
  70   72  
  71   73             PGRAB_RDONLY  Indicates that the process should be grabbed in a
  72   74                           read-only fashion.  This implies that both the
  73   75                           PGRAB_RETAIN and PGRAB_NOSTOP flags should be set.
  74   76                           If a process is opened read-only, then a caller can
  75   77                           only read information about a process and cannot
  76   78                           manipulate it, change its current state, or inject
  77   79                           systems calls into it.
  78   80  
  79   81                           Normally when a process is grabbed, it does so for
  80   82                           both reading and writing.
  81   83  
  82   84             PGRAB_NOSTOP  Do not stop a process as it is grabbed.  Note, any
  83   85                           extant tracing flags on the process will still be
  84   86                           cleared unless the PGRAB_RETAIN flag has been set.
  85   87  
  86   88                           Normally a process is stopped as a result of grabbing
  87   89                           the process.
  88   90  
  89   91       The perr argument must be a non-NULL pointer which will store a more
  90   92       detailed error in the event that the Pgrab() function fails.  A human-
  91   93       readable form of the error can be obtained with Pgrab_error(3PROC).
  92   94  
  93   95       Once a caller is done with the library handle it should call
  94   96       Prelease(3PROC) to release the grabbed process.  Failure to properly
  95   97       release the handle may leave a process stopped and interfere with the
  96   98       ability of other software to obtain a handle.
  97   99  
  98  100     Permissions
  99  101       Unprivileged users may grab and control their own processes only if both
 100  102       the user and group IDs of the target process match those of the calling
 101  103       process.  In addition, the caller must have a super set of the target's
 102  104       privileges.  Processes with the PRIV_PROC_OWNER privilege may manipulate
 103  105       any process on the system, as long as it has an equal privilege set.  For
 104  106       more details on the security and programming considerations, please see
 105  107       the section PROGRAMMING NOTES in proc(4).
 106  108  
 107  109  RETURN VALUES
 108  110       Upon successful completion, the Pgrab() function returns a control handle
 109  111       to the process.  Otherwise, NULL is returned with perr containing the
 110  112       error code.
 111  113  
 112  114  ERRORS
 113  115       The Pgrab() function will fail if:
 114  116  
 115  117       G_BUSY             The process pid is already being traced and the
 116  118                          PGRAB_FORCE flag was not passed in flags.
 117  119  
 118  120       G_LP64             The calling process is a 32-bit process and process
 119  121                          pid is 64-bit.
 120  122  
 121  123       G_NOFD             Too many files are open.  This is logically equivalent
 122  124                          to receiving EMFILE.
 123  125  
 124  126       G_NOPROC           The process referred to by pid does not exist.
 125  127  
 126  128       G_PERM             The calling process has insufficient permissions or
 127  129                          privileges to open the specified process.  See
 128  130                          Permissions for more information.
 129  131  
 130  132       G_SYS              The process referred to by pid is a system process and
 131  133                          cannot be grabbed.
 132  134  
 133  135       G_SELF             The process referred to by pid is the process ID of
 134  136                          the caller and the PGRAB_RDONLY was not passed.  A
 135  137                          process may only grab itself if it's read-only.
 136  138  
 137  139       G_STRANGE          An unanticipated system error occurred while trying to
 138  140                          grab the process file and create the handle.  The
 139  141                          value of errno indicates the system failure.
 140  142  
 141  143       G_ZOMB             The process referred to by pid is a zombie and cannot
 142  144                          be grabbed.
 143  145  
 144  146  INTERFACE STABILITY
 145  147       Uncommitted
 146  148  
 147  149  MT-LEVEL
 148  150       MT-Safe
 149  151  
 150  152  SEE ALSO
 151  153       errno(3C), libproc(3LIB), Pfree(3PROC), Pgrab_core(3PROC),
 152  154       Pgrab_error(3PROC), Pgrab_file(3PROC), Prelease(3PROC)
 153  155  
 154  156  illumos                          May 11, 2016                          illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX