xref: /illumos-gate/usr/src/man/man3proc/Pstopstatus.3proc (revision bbf215553c7233fbab8a0afdf1fac74c44781867)
143051d27SRobert Mustacchi.\"
243051d27SRobert Mustacchi.\" This file and its contents are supplied under the terms of the
343051d27SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0.
443051d27SRobert Mustacchi.\" You may only use this file in accordance with the terms of version
543051d27SRobert Mustacchi.\" 1.0 of the CDDL.
643051d27SRobert Mustacchi.\"
743051d27SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this
843051d27SRobert Mustacchi.\" source.  A copy of the CDDL is also available via the Internet at
943051d27SRobert Mustacchi.\" http://www.illumos.org/license/CDDL.
1043051d27SRobert Mustacchi.\"
1143051d27SRobert Mustacchi.\"
1243051d27SRobert Mustacchi.\" Copyright 2015 Joyent, Inc.
1343051d27SRobert Mustacchi.\"
14282d4a2dSRobert Mustacchi.Dd May 02, 2020
1543051d27SRobert Mustacchi.Dt PSTOPSTATUS 3PROC
1643051d27SRobert Mustacchi.Os
1743051d27SRobert Mustacchi.Sh NAME
1843051d27SRobert Mustacchi.Nm Pdstop ,
1943051d27SRobert Mustacchi.Nm Pstopstatus ,
2043051d27SRobert Mustacchi.Nm Pstop ,
2143051d27SRobert Mustacchi.Nm Pwait ,
2272d3dbb9SYuri Pankov.Nm Ldstop ,
2343051d27SRobert Mustacchi.Nm Lstop ,
2443051d27SRobert Mustacchi.Nm Lwait
2543051d27SRobert Mustacchi.Nd process and thread stop operations
26ab618543SJohn Levon.Sh LIBRARY
2743051d27SRobert Mustacchi.Lb libproc
28ab618543SJohn Levon.Sh SYNOPSIS
2943051d27SRobert Mustacchi.In libproc.h
3043051d27SRobert Mustacchi.Ft int
3143051d27SRobert Mustacchi.Fo Pdstop
3243051d27SRobert Mustacchi.Fa "struct ps_prochandle *P"
3343051d27SRobert Mustacchi.Fc
3443051d27SRobert Mustacchi.Ft int
3543051d27SRobert Mustacchi.Fo Pstopstatus
3643051d27SRobert Mustacchi.Fa "struct ps_prochandle *P"
3743051d27SRobert Mustacchi.Fa "long request"
3843051d27SRobert Mustacchi.Fa "uint_t msec"
3943051d27SRobert Mustacchi.Fc
4043051d27SRobert Mustacchi.Ft int
4143051d27SRobert Mustacchi.Fo Pstop
4243051d27SRobert Mustacchi.Fa "struct ps_prochandle *P"
43282d4a2dSRobert Mustacchi.Fa "uint_t msec"
4443051d27SRobert Mustacchi.Fc
4543051d27SRobert Mustacchi.Ft int
4643051d27SRobert Mustacchi.Fo Pwait
4743051d27SRobert Mustacchi.Fa "struct ps_prochandle *P"
48282d4a2dSRobert Mustacchi.Fa "uint_t msec"
4943051d27SRobert Mustacchi.Fc
5043051d27SRobert Mustacchi.Ft int
5143051d27SRobert Mustacchi.Fo Ldstop
5243051d27SRobert Mustacchi.Fa "struct ps_lwphandle *L"
5343051d27SRobert Mustacchi.Fc
5443051d27SRobert Mustacchi.Ft int
5543051d27SRobert Mustacchi.Fo Lstop
5643051d27SRobert Mustacchi.Fa "struct ps_lwphandle *L"
57282d4a2dSRobert Mustacchi.Fa "uint_t msec"
5843051d27SRobert Mustacchi.Fc
5943051d27SRobert Mustacchi.Ft int
6043051d27SRobert Mustacchi.Fo Lwait
6143051d27SRobert Mustacchi.Fa "struct ps_lwphandle *L"
62282d4a2dSRobert Mustacchi.Fa "uint_t msec"
6343051d27SRobert Mustacchi.Fc
6443051d27SRobert Mustacchi.Sh DESCRIPTION
6543051d27SRobert MustacchiThe
6643051d27SRobert Mustacchi.Fn Pstopstatus
6743051d27SRobert Mustacchifunction allows the caller to stop and optionally wait for the process
6843051d27SRobert Mustacchihandle referred to by
6943051d27SRobert Mustacchi.Fa P
7072d3dbb9SYuri Pankovto be stopped.
7172d3dbb9SYuri PankovStopping a process causes all of its threads to stop execution.
7272d3dbb9SYuri PankovWhere in their execution the threads will halt is not defined.
7372d3dbb9SYuri PankovThreads may be resumed with
7443051d27SRobert Mustacchi.Xr Psetrun 3PROC
7543051d27SRobert Mustacchiand
7643051d27SRobert Mustacchi.Xr prun 1 .
7743051d27SRobert Mustacchi.Pp
7843051d27SRobert MustacchiThe
7943051d27SRobert Mustacchi.Fa request
8043051d27SRobert Mustacchiargument should be one of the following symbols:
8143051d27SRobert Mustacchi.Bl -tag -width Dv -offset indent
8243051d27SRobert Mustacchi.It Dv PCSTOP
8343051d27SRobert MustacchiStop the process; wait for completion before returning.
8443051d27SRobert Mustacchi.It Dv PCDSTOP
8572d3dbb9SYuri PankovStop the process; do not wait for completion before returning.
8672d3dbb9SYuri PankovThat is, the stopping of the process is performed asynchronously in
8743051d27SRobert Mustacchirelation to the caller.
8843051d27SRobert Mustacchi.It Dv PCWSTOP
8943051d27SRobert MustacchiDo not direct the process to stop; simply wait for it to stop.
9043051d27SRobert Mustacchi.It Dv PCNULL
9143051d27SRobert MustacchiDo not direct the process to stop; simply refreshes the state of the
9243051d27SRobert Mustacchiprocess.
9343051d27SRobert Mustacchi.El
9443051d27SRobert Mustacchi.Pp
9543051d27SRobert MustacchiBoth the
9643051d27SRobert Mustacchi.Dv PCSTOP
9743051d27SRobert Mustacchiand
9843051d27SRobert Mustacchi.Dv PCWSTOP
9943051d27SRobert Mustacchirequests allow an upper bound on the amount of time to wait for the
10072d3dbb9SYuri Pankovprocess to stop.
10172d3dbb9SYuri PankovThe
10243051d27SRobert Mustacchi.Fa msec
10343051d27SRobert Mustacchiargument indicates the number of milliseconds to wait for the stop to
10472d3dbb9SYuri Pankovcomplete.
10572d3dbb9SYuri PankovIf the value of
10643051d27SRobert Mustacchi.Fa msec
10743051d27SRobert Mustacchiis
10843051d27SRobert Mustacchi.Sy 0 ,
10972d3dbb9SYuri Pankovthen it will wait forever.
11072d3dbb9SYuri PankovCallers should pass
11143051d27SRobert Mustacchi.Sy 0
11243051d27SRobert Mustacchifor
11343051d27SRobert Mustacchi.Fa msec
11443051d27SRobert Mustacchiwhen the request is
11543051d27SRobert Mustacchi.Dv PCDSTOP
11643051d27SRobert Mustacchior
11743051d27SRobert Mustacchi.Dv PCNULL .
11843051d27SRobert Mustacchi.Pp
11943051d27SRobert MustacchiWhen a non-zero timeout is specified, the process may or may not be
12072d3dbb9SYuri Pankovstopped upon return.
12172d3dbb9SYuri PankovThe return value does not reflect the current state of the process.
12272d3dbb9SYuri PankovFor example, if the timeout expires during a
12343051d27SRobert Mustacchi.Fa PCWSTOP
12443051d27SRobert Mustacchirequest, the return value will be
12543051d27SRobert Mustacchi.Sy 0
12643051d27SRobert Mustacchiregardless of the actual state of the process.
12743051d27SRobert Mustacchi.Pp
12872d3dbb9SYuri PankovOnly active processes may be stopped.
12972d3dbb9SYuri PankovHandles that refer to core files, zombie processes, or files cannot be used;
13072d3dbb9SYuri Pankovunless the value of
13143051d27SRobert Mustacchi.Fa request
13243051d27SRobert Mustacchiis set to
13343051d27SRobert Mustacchi.Dv PCNULL .
13443051d27SRobert Mustacchi.Pp
13543051d27SRobert MustacchiThe
13643051d27SRobert Mustacchi.Fn Pstop
13743051d27SRobert Mustacchifunction is is equivalent to calling the
13843051d27SRobert Mustacchi.Fn Pstopstatus
13943051d27SRobert Mustacchifunction with the request set to
140282d4a2dSRobert Mustacchi.Dv PCSTOP .
14143051d27SRobert Mustacchi.Pp
14243051d27SRobert MustacchiThe
14343051d27SRobert Mustacchi.Fn Pwait
14443051d27SRobert Mustacchifunction is is equivalent to calling the
14543051d27SRobert Mustacchi.Fn Pstopstatus
14643051d27SRobert Mustacchifunction with the request set to
147282d4a2dSRobert Mustacchi.Dv PCWSTOP .
14843051d27SRobert Mustacchi.Pp
14943051d27SRobert MustacchiThe
15043051d27SRobert Mustacchi.Fn Pdstop
15143051d27SRobert Mustacchifunction is is equivalent to calling the
15243051d27SRobert Mustacchi.Fn Pstopstatus
15343051d27SRobert Mustacchifunction with the request set to
15443051d27SRobert Mustacchi.Dv PCDSTOP .
15543051d27SRobert Mustacchi.Pp
15643051d27SRobert MustacchiThe
15743051d27SRobert Mustacchi.Fn Ldstop ,
15843051d27SRobert Mustacchi.Fn Lstop ,
15943051d27SRobert Mustacchiand
16043051d27SRobert Mustacchi.Fn Lwait
16143051d27SRobert Mustacchifunctions are equivalent to the
16243051d27SRobert Mustacchi.Fn Pdstop ,
16343051d27SRobert Mustacchi.Fn Pstop ,
16443051d27SRobert Mustacchiand
16543051d27SRobert Mustacchi.Fn Pwait
16672d3dbb9SYuri Pankovfunctions, respectively.
16772d3dbb9SYuri PankovExcept, rather than operating on a process, they operate on the thread handle
16843051d27SRobert Mustacchi.Fa L .
16943051d27SRobert MustacchiA call to
17043051d27SRobert Mustacchi.Fn Lstop
17143051d27SRobert Mustacchistops only a single thread; whereas
17243051d27SRobert Mustacchi.Fn Pstop
17343051d27SRobert Mustacchistops every thread in the process.
17443051d27SRobert Mustacchi.Sh RETURN VALUES
17543051d27SRobert MustacchiUpon successful completion, the
17643051d27SRobert Mustacchi.Fn Pdstop ,
17743051d27SRobert Mustacchi.Fn Pstopstatus ,
17843051d27SRobert Mustacchi.Fn Pstop ,
17943051d27SRobert Mustacchi.Fn Pwait ,
18043051d27SRobert Mustacchi.Fn Ldstop ,
18143051d27SRobert Mustacchi.Fn Lstop ,
18243051d27SRobert Mustacchiand
18343051d27SRobert Mustacchi.Fn Lwait
18443051d27SRobert Mustacchifunctions return
18543051d27SRobert Mustacchi.Sy 0 .
18643051d27SRobert MustacchiOtherwise,
18743051d27SRobert Mustacchi.Sy -1
18843051d27SRobert Mustacchiis returned and
18943051d27SRobert Mustacchi.Dv errno
19043051d27SRobert Mustacchiis set to indicate the error that occurred.
19143051d27SRobert Mustacchi.Sh ERRORS
19243051d27SRobert MustacchiFor a full list of possible errors see the
19343051d27SRobert Mustacchi.Sy DIAGNOSTICS
19443051d27SRobert Mustacchisection in
195*bbf21555SRichard Lowe.Xr proc 5 .
19643051d27SRobert Mustacchi.Pp
19743051d27SRobert MustacchiThe
19843051d27SRobert Mustacchi.Fn Pdstop ,
19943051d27SRobert Mustacchi.Fn Pstopstatus ,
20043051d27SRobert Mustacchi.Fn Pstop ,
20143051d27SRobert Mustacchi.Fn Pwait ,
20243051d27SRobert Mustacchi.Fn Ldstop ,
20343051d27SRobert Mustacchi.Fn Lstop ,
20443051d27SRobert Mustacchiand
20543051d27SRobert Mustacchi.Fn Lwait
20643051d27SRobert Mustacchifunctions will fail if:
20743051d27SRobert Mustacchi.Bl -tag -width Er
20843051d27SRobert Mustacchi.It Er EAGAIN
20943051d27SRobert MustacchiControl over the handle
21043051d27SRobert Mustacchi.Fa P
21172d3dbb9SYuri Pankovwas lost.
21272d3dbb9SYuri PankovCallers should call
21343051d27SRobert Mustacchi.Xr Preopen 3PROC .
21443051d27SRobert MustacchiFor more information on losing control, see
21543051d27SRobert Mustacchi.Sy PROGRAMMING NOTES
21643051d27SRobert Mustacchiin
217*bbf21555SRichard Lowe.Xr proc 5 .
21843051d27SRobert Mustacchi.It Er ENOENT
21943051d27SRobert MustacchiThe request was not
22043051d27SRobert Mustacchi.Dv PCNULL
22143051d27SRobert Mustacchiand the process handle
22243051d27SRobert Mustacchi.Fa P
22343051d27SRobert Mustacchidoes not refer to an active process, but refers to a core file, a zombie
22443051d27SRobert Mustacchiprocess, or a file.
22543051d27SRobert Mustacchi.It Er EINVAL
22643051d27SRobert Mustacchi.Fa request
22743051d27SRobert Mustacchiis not valid or the process is in an unknown state.
22843051d27SRobert Mustacchi.It Er EPROTO
22943051d27SRobert MustacchiA fatal protocol error occurred and the process could not be stopped.
23043051d27SRobert Mustacchi.El
23143051d27SRobert Mustacchi.Sh INTERFACE STABILITY
23243051d27SRobert Mustacchi.Sy Uncommitted
23343051d27SRobert Mustacchi.Sh MT-LEVEL
23443051d27SRobert MustacchiSee
23543051d27SRobert Mustacchi.Sy LOCKING
23643051d27SRobert Mustacchiin
23743051d27SRobert Mustacchi.Xr libproc 3LIB .
23843051d27SRobert Mustacchi.Sh SEE ALSO
23943051d27SRobert Mustacchi.Xr libproc 3LIB ,
24043051d27SRobert Mustacchi.Xr Lgrab 3PROC ,
24143051d27SRobert Mustacchi.Xr Pcreate 3PROC ,
24243051d27SRobert Mustacchi.Xr Pgrab 3PROC ,
24343051d27SRobert Mustacchi.Xr Pgrab_core 3PROC ,
24443051d27SRobert Mustacchi.Xr Pgrab_file 3PROC ,
245*bbf21555SRichard Lowe.Xr proc 5
246