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