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