1 PSTOPSTATUS(3PROC) Process Control Library Functions PSTOPSTATUS(3PROC) 2 3 NAME 4 Pdstop, Pstopstatus, Pstop, Pwait, Ldstop, Lstop, Lwait - process and 5 thread stop operations 6 7 LIBRARY 8 Process Control Library (libproc, -lproc) 9 10 SYNOPSIS 11 #include <libproc.h> 12 13 int 14 Pdstop(struct ps_prochandle *P); 15 16 int 17 Pstopstatus(struct ps_prochandle *P, long request, uint_t msec); 18 19 int 20 Pstop(struct ps_prochandle *P); 21 22 int 23 Pwait(struct ps_prochandle *P); 24 25 int 26 Ldstop(struct ps_lwphandle *L); 27 28 int 29 Lstop(struct ps_lwphandle *L); 30 31 int 32 Lwait(struct ps_lwphandle *L); 33 34 DESCRIPTION 35 The Pstopstatus() function allows the caller to stop and optionally wait 36 for the process handle referred to by P to be stopped. Stopping a 37 process causes all of its threads to stop execution. Where in their 38 execution the threads will halt is not defined. Threads may be resumed 39 with Psetrun(3PROC) and prun(1). 40 41 The request argument should be one of the following symbols: 42 43 PCSTOP Stop the process; wait for completion before 44 returning. 45 46 PCDSTOP Stop the process; do not wait for completion before 47 returning. That is, the stopping of the process is 48 performed asynchronously in relation to the caller. 49 50 PCWSTOP Do not direct the process to stop; simply wait for it 51 to stop. 52 53 PCNULL Do not direct the process to stop; simply refreshes 54 the state of the process. 55 56 Both the PCSTOP and PCWSTOP requests allow an upper bound on the amount 57 of time to wait for the process to stop. The msec argument indicates the 58 number of milliseconds to wait for the stop to complete. If the value of 59 msec is 0, then it will wait forever. Callers should pass 0 for msec 60 when the request is PCDSTOP or PCNULL. 61 62 When a non-zero timeout is specified, the process may or may not be 63 stopped upon return. The return value does not reflect the current state 64 of the process. For example, if the timeout expires during a PCWSTOP 65 request, the return value will be 0 regardless of the actual state of the 66 process. 67 68 Only active processes may be stopped. Handles that refer to core files, 69 zombie processes, or files cannot be used; unless the value of request is 70 set to PCNULL. 71 72 The Pstop() function is is equivalent to calling the Pstopstatus() 73 function with the request set to PCSTOP and an infinite timeout. 74 75 The Pwait() function is is equivalent to calling the Pstopstatus() 76 function with the request set to PCWSTOP and an infinite timeout. 77 78 The Pdstop() function is is equivalent to calling the Pstopstatus() 79 function with the request set to PCDSTOP. 80 81 The Ldstop(), Lstop(), and Lwait() functions are equivalent to the 82 Pdstop(), Pstop(), and Pwait() functions, respectively. Except, rather 83 than operating on a process, they operate on the thread handle L. A call 84 to Lstop() stops only a single thread; whereas Pstop() stops every thread 85 in the process. 86 87 RETURN VALUES 88 Upon successful completion, the Pdstop(), Pstopstatus(), Pstop(), 89 Pwait(), Ldstop(), Lstop(), and Lwait() functions return 0. Otherwise, 90 -1 is returned and errno is set to indicate the error that occurred. 91 92 ERRORS 93 For a full list of possible errors see the DIAGNOSTICS section in 94 proc(4). 95 96 The Pdstop(), Pstopstatus(), Pstop(), Pwait(), Ldstop(), Lstop(), and 97 Lwait() functions will fail if: 98 99 EAGAIN Control over the handle P was lost. Callers should 100 call Preopen(3PROC). For more information on losing 101 control, see PROGRAMMING NOTES in proc(4). 102 103 ENOENT The request was not PCNULL and the process handle P 104 does not refer to an active process, but refers to a 105 core file, a zombie process, or a file. 106 107 EINVAL request is not valid or the process is in an unknown 108 state. 109 110 EPROTO A fatal protocol error occurred and the process could 111 not be stopped. 112 113 INTERFACE STABILITY 114 Uncommitted 115 116 MT-LEVEL 117 See LOCKING in libproc(3LIB). 118 119 SEE ALSO 120 libproc(3LIB), Lgrab(3PROC), Pcreate(3PROC), Pgrab(3PROC), 121 Pgrab_core(3PROC), Pgrab_file(3PROC), proc(4) 122 123 illumos May 11, 2016 illumos