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