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

          --- old/usr/src/man/man3proc/Pstopstatus.3proc.man.txt
          +++ new/usr/src/man/man3proc/Pstopstatus.3proc.man.txt
   1    1  PSTOPSTATUS(3PROC)     Process Control Library Functions    PSTOPSTATUS(3PROC)
   2    2  
   3    3  NAME
   4    4       Pdstop, Pstopstatus, Pstop, Pwait, Ldstop, Lstop, Lwait - process and
   5    5       thread stop operations
   6    6  
   7      -SYNOPSIS
        7 +LIBRARY
   8    8       Process Control Library (libproc, -lproc)
        9 +
       10 +SYNOPSIS
   9   11       #include <libproc.h>
  10   12  
  11   13       int
  12   14       Pdstop(struct ps_prochandle *P);
  13   15  
  14   16       int
  15   17       Pstopstatus(struct ps_prochandle *P, long request, uint_t msec);
  16   18  
  17   19       int
  18   20       Pstop(struct ps_prochandle *P);

  19   21  
  20   22       int
  21   23       Pwait(struct ps_prochandle *P);
  22   24  
  23   25       int
  24   26       Ldstop(struct ps_lwphandle *L);
  25   27  
  26   28       int
  27   29       Lstop(struct ps_lwphandle *L);
  28   30  
  29   31       int
  30   32       Lwait(struct ps_lwphandle *L);
  31   33  
  32   34  DESCRIPTION
  33   35       The Pstopstatus() function allows the caller to stop and optionally wait
  34   36       for the process handle referred to by P to be stopped.  Stopping a
  35   37       process causes all of its threads to stop execution.  Where in their
  36   38       execution the threads will halt is not defined.  Threads may be resumed
  37   39       with Psetrun(3PROC) and prun(1).
  38   40  
  39   41       The request argument should be one of the following symbols:
  40   42  
  41   43             PCSTOP        Stop the process; wait for completion before
  42   44                           returning.
  43   45  
  44   46             PCDSTOP       Stop the process; do not wait for completion before
  45   47                           returning.  That is, the stopping of the process is
  46   48                           performed asynchronously in relation to the caller.
  47   49  
  48   50             PCWSTOP       Do not direct the process to stop; simply wait for it
  49   51                           to stop.
  50   52  
  51   53             PCNULL        Do not direct the process to stop; simply refreshes
  52   54                           the state of the process.
  53   55  
  54   56       Both the PCSTOP and PCWSTOP requests allow an upper bound on the amount
  55   57       of time to wait for the process to stop.  The msec argument indicates the
  56   58       number of milliseconds to wait for the stop to complete.  If the value of
  57   59       msec is 0, then it will wait forever.  Callers should pass 0 for msec
  58   60       when the request is PCDSTOP or PCNULL.
  59   61  
  60   62       When a non-zero timeout is specified, the process may or may not be
  61   63       stopped upon return.  The return value does not reflect the current state
  62   64       of the process.  For example, if the timeout expires during a PCWSTOP
  63   65       request, the return value will be 0 regardless of the actual state of the
  64   66       process.
  65   67  
  66   68       Only active processes may be stopped.  Handles that refer to core files,
  67   69       zombie processes, or files cannot be used; unless the value of request is
  68   70       set to PCNULL.
  69   71  
  70   72       The Pstop() function is is equivalent to calling the Pstopstatus()
  71   73       function with the request set to PCSTOP and an infinite timeout.
  72   74  
  73   75       The Pwait() function is is equivalent to calling the Pstopstatus()
  74   76       function with the request set to PCWSTOP and an infinite timeout.
  75   77  
  76   78       The Pdstop() function is is equivalent to calling the Pstopstatus()
  77   79       function with the request set to PCDSTOP.
  78   80  
  79   81       The Ldstop(), Lstop(), and Lwait() functions are equivalent to the
  80   82       Pdstop(), Pstop(), and Pwait() functions, respectively.  Except, rather
  81   83       than operating on a process, they operate on the thread handle L.  A call
  82   84       to Lstop() stops only a single thread; whereas Pstop() stops every thread
  83   85       in the process.
  84   86  
  85   87  RETURN VALUES
  86   88       Upon successful completion, the Pdstop(), Pstopstatus(), Pstop(),
  87   89       Pwait(), Ldstop(), Lstop(), and Lwait() functions return 0.  Otherwise,
  88   90       -1 is returned and errno is set to indicate the error that occurred.
  89   91  
  90   92  ERRORS
  91   93       For a full list of possible errors see the DIAGNOSTICS section in
  92   94       proc(4).
  93   95  
  94   96       The Pdstop(), Pstopstatus(), Pstop(), Pwait(), Ldstop(), Lstop(), and
  95   97       Lwait() functions will fail if:
  96   98  
  97   99       EAGAIN             Control over the handle P was lost.  Callers should
  98  100                          call Preopen(3PROC).  For more information on losing
  99  101                          control, see PROGRAMMING NOTES in proc(4).
 100  102  
 101  103       ENOENT             The request was not PCNULL and the process handle P
 102  104                          does not refer to an active process, but refers to a
 103  105                          core file, a zombie process, or a file.
 104  106  
 105  107       EINVAL             request is not valid or the process is in an unknown
 106  108                          state.
 107  109  
 108  110       EPROTO             A fatal protocol error occurred and the process could
 109  111                          not be stopped.
 110  112  
 111  113  INTERFACE STABILITY
 112  114       Uncommitted
 113  115  
 114  116  MT-LEVEL
 115  117       See LOCKING in libproc(3LIB).
 116  118  
 117  119  SEE ALSO
 118  120       libproc(3LIB), Lgrab(3PROC), Pcreate(3PROC), Pgrab(3PROC),
 119  121       Pgrab_core(3PROC), Pgrab_file(3PROC), proc(4)
 120  122  
 121  123  illumos                          May 11, 2016                          illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX