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