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