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