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