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 PSTOPSTATUS 3PROC 16.Os 17.Sh NAME 18.Nm Pdstop , 19.Nm Pstopstatus , 20.Nm Pstop , 21.Nm Pwait , 22.Nm Ldstop 23.Nm Lstop , 24.Nm Lwait 25.Nd process and thread stop operations 26.Sh SYNOPSIS 27.Lb libproc 28.In libproc.h 29.Ft int 30.Fo Pdstop 31.Fa "struct ps_prochandle *P" 32.Fc 33.Ft int 34.Fo Pstopstatus 35.Fa "struct ps_prochandle *P" 36.Fa "long request" 37.Fa "uint_t msec" 38.Fc 39.Ft int 40.Fo Pstop 41.Fa "struct ps_prochandle *P" 42.Fc 43.Ft int 44.Fo Pwait 45.Fa "struct ps_prochandle *P" 46.Fc 47.Ft int 48.Fo Ldstop 49.Fa "struct ps_lwphandle *L" 50.Fc 51.Ft int 52.Fo Lstop 53.Fa "struct ps_lwphandle *L" 54.Fc 55.Ft int 56.Fo Lwait 57.Fa "struct ps_lwphandle *L" 58.Fc 59.Sh DESCRIPTION 60The 61.Fn Pstopstatus 62function allows the caller to stop and optionally wait for the process 63handle referred to by 64.Fa P 65to be stopped. Stopping a process causes all of its threads to stop 66execution. Where in their execution the threads will halt is not 67defined. Threads may be resumed with 68.Xr Psetrun 3PROC 69and 70.Xr prun 1 . 71.Pp 72The 73.Fa request 74argument should be one of the following symbols: 75.Bl -tag -width Dv -offset indent 76.It Dv PCSTOP 77Stop the process; wait for completion before returning. 78.It Dv PCDSTOP 79Stop the process; do not wait for completion before returning. That 80is, the stopping of the process is performed asynchronously in 81relation to the caller. 82.It Dv PCWSTOP 83Do not direct the process to stop; simply wait for it to stop. 84.It Dv PCNULL 85Do not direct the process to stop; simply refreshes the state of the 86process. 87.El 88.Pp 89Both the 90.Dv PCSTOP 91and 92.Dv PCWSTOP 93requests allow an upper bound on the amount of time to wait for the 94process to stop. The 95.Fa msec 96argument indicates the number of milliseconds to wait for the stop to 97complete. If the value of 98.Fa msec 99is 100.Sy 0 , 101then it will wait forever. Callers should pass 102.Sy 0 103for 104.Fa msec 105when the request is 106.Dv PCDSTOP 107or 108.Dv PCNULL . 109.Pp 110When a non-zero timeout is specified, the process may or may not be 111stopped upon return. The return value does not reflect the current 112state of the process. For example, if the timeout expires during a 113.Fa PCWSTOP 114request, the return value will be 115.Sy 0 116regardless of the actual state of the process. 117.Pp 118Only active processes may be stopped. Handles that refer to core 119files, zombie processes, or files cannot be used; unless the value of 120.Fa request 121is set to 122.Dv PCNULL . 123.Pp 124The 125.Fn Pstop 126function is is equivalent to calling the 127.Fn Pstopstatus 128function with the request set to 129.Dv PCSTOP 130and an infinite timeout. 131.Pp 132The 133.Fn Pwait 134function is is equivalent to calling the 135.Fn Pstopstatus 136function with the request set to 137.Dv PCWSTOP 138and an infinite timeout. 139.Pp 140The 141.Fn Pdstop 142function is is equivalent to calling the 143.Fn Pstopstatus 144function with the request set to 145.Dv PCDSTOP . 146.Pp 147The 148.Fn Ldstop , 149.Fn Lstop , 150and 151.Fn Lwait 152functions are equivalent to the 153.Fn Pdstop , 154.Fn Pstop , 155and 156.Fn Pwait 157functions, respectively. Except, rather than operating on a process, 158they operate on the thread handle 159.Fa L . 160A call to 161.Fn Lstop 162stops only a single thread; whereas 163.Fn Pstop 164stops every thread in the process. 165.Sh RETURN VALUES 166Upon successful completion, the 167.Fn Pdstop , 168.Fn Pstopstatus , 169.Fn Pstop , 170.Fn Pwait , 171.Fn Ldstop , 172.Fn Lstop , 173and 174.Fn Lwait 175functions return 176.Sy 0 . 177Otherwise, 178.Sy -1 179is returned and 180.Dv errno 181is set to indicate the error that occurred. 182.Sh ERRORS 183For a full list of possible errors see the 184.Sy DIAGNOSTICS 185section in 186.Xr proc 4 . 187.Pp 188The 189.Fn Pdstop , 190.Fn Pstopstatus , 191.Fn Pstop , 192.Fn Pwait , 193.Fn Ldstop , 194.Fn Lstop , 195and 196.Fn Lwait 197functions will fail if: 198.Bl -tag -width Er 199.It Er EAGAIN 200Control over the handle 201.Fa P 202was lost. Callers should call 203.Xr Preopen 3PROC . 204For more information on losing control, see 205.Sy PROGRAMMING NOTES 206in 207.Xr proc 4 . 208.It Er ENOENT 209The request was not 210.Dv PCNULL 211and the process handle 212.Fa P 213does not refer to an active process, but refers to a core file, a zombie 214process, or a file. 215.It Er EINVAL 216.Fa request 217is not valid or the process is in an unknown state. 218.It Er EPROTO 219A fatal protocol error occurred and the process could not be stopped. 220.El 221.Sh INTERFACE STABILITY 222.Sy Uncommitted 223.Sh MT-LEVEL 224See 225.Sy LOCKING 226in 227.Xr libproc 3LIB . 228.Sh SEE ALSO 229.Xr libproc 3LIB , 230.Xr Lgrab 3PROC , 231.Xr Pcreate 3PROC , 232.Xr Pgrab 3PROC , 233.Xr Pgrab_core 3PROC , 234.Xr Pgrab_file 3PROC , 235.Xr proc 4 236