1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\"
  14 .Dd May 11, 2016
  15 .Dt PSETRUN 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Psetrun ,
  19 .Nm Lsetrun
  20 .Nd run a stopped process or thread
  21 .Sh LIBRARY
  22 .Lb libproc
  23 .Sh SYNOPSIS
  24 .In libproc.h
  25 .Ft int
  26 .Fo Psetrun
  27 .Fa "struct ps_prochandle *P"
  28 .Fa "int sig"
  29 .Fa "int flags"
  30 .Fc
  31 .Ft int
  32 .Fo Lsetrun
  33 .Fa "struct ps_lwphandle *L"
  34 .Fa "int sig"
  35 .Fa "int flags"
  36 .Fc
  37 .Sh DESCRIPTION
  38 The
  39 .Fn Psetrun
  40 function resumes the stopped process handle
  41 .Fa P
  42 and transitions the process to running.
  43 If
  44 .Fa sig
  45 is non-zero, then the
  46 .Fn Psetrun
  47 function causes the signal to be delivered.
  48 See
  49 .Xr signal.h 3HEAD
  50 for a list of valid signal identifiers.
  51 .Pp
  52 The
  53 .Fa flags
  54 member modifies the behavior of the resumed handle.
  55 The following values may be combined by a bitwise-inclusive-OR:
  56 .Bl -tag -width Dv -offset indent
  57 .It Dv PRCSIG
  58 Clears the current signal, if any.
  59 .It Dv PRCFAULT
  60 Clears the current fault, if any.
  61 .It Dv PRSTEP
  62 Indicates that the thread should single-step over the next machine
  63 instruction and upon completion, inject a trap.
  64 For the specific mechanics of single-stepping and what traps or signals will be
  65 injected, see the
  66 .Sy PRSTEP
  67 section of
  68 .Xr proc 4 .
  69 .It Dv PRSABORT
  70 Indicates that the thread should abort the system call that it is
  71 currently executing.
  72 This is only valid if the thread is stopped because it is asleep or right before
  73 a system call.
  74 This will cause the system call to return
  75 .Er EINTR .
  76 .El
  77 .Pp
  78 If
  79 both
  80 .Dv PRCSIG
  81 is specified and
  82 .Fa sig
  83 is non-zero, then the
  84 .Dv PRCSIG
  85 request takes priority, and it will be treated as though
  86 .Fa sig
  87 was passed the argument
  88 .Sy 0 .
  89 .Pp
  90 When the process is resumed all extent tracing flags and register
  91 changes will be synchronized with the process.
  92 For more information on resuming a thread see the
  93 .Sy PCRUN
  94 section in
  95 .Xr proc 4 .
  96 .Pp
  97 Note, the
  98 .Fn Psetrun
  99 function is only valid for active processes.
 100 It will fail on process handles that refer to core files, zombie processes, and
 101 ELF objects.
 102 .Pp
 103 The
 104 .Fn Lsetrun
 105 function is equivalent to the
 106 .Fn Psetrun
 107 function, except rather than operating on a process it operates on a
 108 thread.
 109 .Fn Lsetrun
 110 causes the specified thread,
 111 .Fa L ,
 112 to resume execution.
 113 Whereas
 114 .Fn Psetrun
 115 causes all threads in the process to resume.
 116 .Sh RETURN VALUES
 117 Upon successful completion, the
 118 .Fn Psetrun
 119 and
 120 .Fn Lsetrun
 121 functions return
 122 .Sy 0 .
 123 Otherwise,
 124 .Sy -1
 125 is returned and
 126 .Sy errno
 127 is set to indicate the error.
 128 .Sh ERRORS
 129 For a full list of possible errors see the
 130 .Sy DIAGNOSTICS
 131 section in
 132 .Xr proc 4 .
 133 .Pp
 134 The
 135 .Fn Psetrun
 136 and
 137 .Fn Lsetrun
 138 functions will fail if:
 139 .Bl -tag -width Er
 140 .It Er EBUSY
 141 The process handle
 142 .Fa P
 143 is not currently stopped or it is not stopped due to an event of
 144 interest, a directed stop, or it is asleep in a system call.
 145 .El
 146 .Sh INTERFACE STABILITY
 147 .Sy Uncommitted
 148 .Sh MT-LEVEL
 149 See
 150 .Sy LOCKING
 151 in
 152 .Xr libproc 3LIB .
 153 .Sh SEE ALSO
 154 .Xr signal.h 3HEAD ,
 155 .Xr libproc 3LIB ,
 156 .Xr Pstatus 3PROC ,
 157 .Xr proc 4