share/man/man3proc/Pstopstatus.3proc

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