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