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

          --- old/usr/src/man/man3proc/Psetrun.3proc
          +++ new/usr/src/man/man3proc/Psetrun.3proc

   1    1  .\"
   2    2  .\" This file and its contents are supplied under the terms of the
   3    3  .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4    4  .\" You may only use this file in accordance with the terms of version
   5    5  .\" 1.0 of the CDDL.
   6    6  .\"
   7    7  .\" A full copy of the text of the CDDL should have accompanied this
   8    8  .\" source.  A copy of the CDDL is also available via the Internet at
   9    9  .\" http://www.illumos.org/license/CDDL.
  10   10  .\"

  11   11  .\"
  12   12  .\" Copyright 2015 Joyent, Inc.
  13   13  .\"
  14   14  .Dd May 11, 2016
  15   15  .Dt PSETRUN 3PROC
  16   16  .Os
  17   17  .Sh NAME
  18   18  .Nm Psetrun ,
  19   19  .Nm Lsetrun
  20   20  .Nd run a stopped process or thread
  21      -.Sh SYNOPSIS
       21 +.Sh LIBRARY
  22   22  .Lb libproc
       23 +.Sh SYNOPSIS
  23   24  .In libproc.h
  24   25  .Ft int
  25   26  .Fo Psetrun
  26   27  .Fa "struct ps_prochandle *P"
  27   28  .Fa "int sig"
  28   29  .Fa "int flags"
  29   30  .Fc
  30   31  .Ft int
  31   32  .Fo Lsetrun
  32   33  .Fa "struct ps_lwphandle *L"

  33   34  .Fa "int sig"
  34   35  .Fa "int flags"
  35   36  .Fc
  36   37  .Sh DESCRIPTION
  37   38  The
  38   39  .Fn Psetrun
  39   40  function resumes the stopped process handle
  40   41  .Fa P
  41   42  and transitions the process to running.
  42   43  If
  43   44  .Fa sig
  44   45  is non-zero, then the
  45   46  .Fn Psetrun
  46   47  function causes the signal to be delivered.
  47   48  See
  48   49  .Xr signal.h 3HEAD
  49   50  for a list of valid signal identifiers.
  50   51  .Pp
  51   52  The
  52   53  .Fa flags
  53   54  member modifies the behavior of the resumed handle.
  54   55  The following values may be combined by a bitwise-inclusive-OR:
  55   56  .Bl -tag -width Dv -offset indent
  56   57  .It Dv PRCSIG
  57   58  Clears the current signal, if any.
  58   59  .It Dv PRCFAULT
  59   60  Clears the current fault, if any.
  60   61  .It Dv PRSTEP
  61   62  Indicates that the thread should single-step over the next machine
  62   63  instruction and upon completion, inject a trap.
  63   64  For the specific mechanics of single-stepping and what traps or signals will be
  64   65  injected, see the
  65   66  .Sy PRSTEP
  66   67  section of
  67   68  .Xr proc 4 .
  68   69  .It Dv PRSABORT
  69   70  Indicates that the thread should abort the system call that it is
  70   71  currently executing.
  71   72  This is only valid if the thread is stopped because it is asleep or right before
  72   73  a system call.
  73   74  This will cause the system call to return
  74   75  .Er EINTR .
  75   76  .El
  76   77  .Pp
  77   78  If
  78   79  both
  79   80  .Dv PRCSIG
  80   81  is specified and
  81   82  .Fa sig
  82   83  is non-zero, then the
  83   84  .Dv PRCSIG
  84   85  request takes priority, and it will be treated as though
  85   86  .Fa sig
  86   87  was passed the argument
  87   88  .Sy 0 .
  88   89  .Pp
  89   90  When the process is resumed all extent tracing flags and register
  90   91  changes will be synchronized with the process.
  91   92  For more information on resuming a thread see the
  92   93  .Sy PCRUN
  93   94  section in
  94   95  .Xr proc 4 .
  95   96  .Pp
  96   97  Note, the
  97   98  .Fn Psetrun
  98   99  function is only valid for active processes.
  99  100  It will fail on process handles that refer to core files, zombie processes, and
 100  101  ELF objects.
 101  102  .Pp
 102  103  The
 103  104  .Fn Lsetrun
 104  105  function is equivalent to the
 105  106  .Fn Psetrun
 106  107  function, except rather than operating on a process it operates on a
 107  108  thread.
 108  109  .Fn Lsetrun
 109  110  causes the specified thread,
 110  111  .Fa L ,
 111  112  to resume execution.
 112  113  Whereas
 113  114  .Fn Psetrun
 114  115  causes all threads in the process to resume.
 115  116  .Sh RETURN VALUES
 116  117  Upon successful completion, the
 117  118  .Fn Psetrun
 118  119  and
 119  120  .Fn Lsetrun
 120  121  functions return
 121  122  .Sy 0 .
 122  123  Otherwise,
 123  124  .Sy -1
 124  125  is returned and
 125  126  .Sy errno
 126  127  is set to indicate the error.
 127  128  .Sh ERRORS
 128  129  For a full list of possible errors see the
 129  130  .Sy DIAGNOSTICS
 130  131  section in
 131  132  .Xr proc 4 .
 132  133  .Pp
 133  134  The
 134  135  .Fn Psetrun
 135  136  and
 136  137  .Fn Lsetrun
 137  138  functions will fail if:
 138  139  .Bl -tag -width Er
 139  140  .It Er EBUSY
 140  141  The process handle
 141  142  .Fa P
 142  143  is not currently stopped or it is not stopped due to an event of
 143  144  interest, a directed stop, or it is asleep in a system call.
 144  145  .El
 145  146  .Sh INTERFACE STABILITY
 146  147  .Sy Uncommitted
 147  148  .Sh MT-LEVEL
 148  149  See
 149  150  .Sy LOCKING
 150  151  in
 151  152  .Xr libproc 3LIB .
 152  153  .Sh SEE ALSO
 153  154  .Xr signal.h 3HEAD ,
 154  155  .Xr libproc 3LIB ,
 155  156  .Xr Pstatus 3PROC ,
 156  157  .Xr proc 4

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX