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