| blob | 68b6f92ebd79105028a327ed63c36d5c9f121310 |
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