lib/libc/sys/procctl.2

   1 .\" Copyright (c) 2013 Hudson River Trading LLC
   2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Copyright (c) 2014 The FreeBSD Foundation
   6 .\" Portions of this documentation were written by Konstantin Belousov
   7 .\" under sponsorship from the FreeBSD Foundation.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd December 29, 2014
  33 .Dt PROCCTL 2
  34 .Os
  35 .Sh NAME
  36 .Nm procctl
  37 .Nd control processes
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/procctl.h
  42 .Ft int
  43 .Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *arg"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn procctl
  47 system call provides for control over processes.
  48 The
  49 .Fa idtype
  50 and
  51 .Fa id
  52 arguments specify the set of processes to control.
  53 If multiple processes match the identifier,
  54 .Nm
  55 will make a
  56 .Dq best effort
  57 to control as many of the selected processes as possible.
  58 An error is only returned if no selected processes successfully complete
  59 the request.
  60 The following identifier types are supported:
  61 .Bl -tag -width "Dv P_PGID"
  62 .It Dv P_PID
  63 Control the process with the process ID
  64 .Fa id .
  65 .It Dv P_PGID
  66 Control processes belonging to the process group with the ID
  67 .Fa id .
  68 .El
  69 .Pp
  70 The control request to perform is specified by the
  71 .Fa cmd
  72 argument.
  73 The following commands are supported:
  74 .Bl -tag -width "Dv PROC_REAP_GETPIDS"
  75 .It Dv PROC_SPROTECT
  76 Set process protection state.
  77 This is used to mark a process as protected from being killed if the system
  78 exhausts available memory and swap.
  79 The
  80 .Fa arg
  81 parameter must point to an integer containing an operation and zero or more
  82 optional flags.
  83 The following operations are supported:
  84 .Bl -tag -width "Dv PPROT_CLEAR"
  85 .It Dv PPROT_SET
  86 Mark the selected processes as protected.
  87 .It Dv PPROT_CLEAR
  88 Clear the protected state of selected processes.
  89 .El
  90 .Pp
  91 The following optional flags are supported:
  92 .Bl -tag -width "Dv PPROT_DESCE"
  93 .It Dv PPROT_DESCEND
  94 Apply the requested operation to all child processes of each selected process
  95 in addition to each selected process.
  96 .It Dv PPROT_INHERIT
  97 When used with
  98 .Dv PPROT_SET ,
  99 mark all future child processes of each selected process as protected.
 100 Future child processes will also mark all of their future child processes.
 101 .El
 102 .It Dv PROC_REAP_ACQUIRE
 103 Acquires the reaper status for the current process.
 104 The status means that children orphaned by the reaper's descendants
 105 that were forked after the acquisition of the status are reparented to the
 106 reaper.
 107 After the system initialization,
 108 .Xr init 8
 109 is the default reaper.
 110 .Pp
 111 .It Dv PROC_REAP_RELEASE
 112 Releases the reaper state for the current process.
 113 The reaper of the current process becomes the new reaper of the
 114 current process's descendants.
 115 .It Dv PROC_REAP_STATUS
 116 Provides the information about the reaper of the specified process,
 117 or the process itself when it is a reaper.
 118 The
 119 .Fa data
 120 argument must point to a
 121 .Vt procctl_reaper_status
 122 structure which is filled in by the syscall on successful return.
 123 .Bd -literal
 124 struct procctl_reaper_status {
 125         u_int   rs_flags;
 126         u_int   rs_children;
 127         u_int   rs_descendants;
 128         pid_t   rs_reaper;
 129         pid_t   rs_pid;
 130 };
 131 .Ed
 132 The
 133 .Fa rs_flags
 134 may have the following flags returned:
 135 .Bl -tag -width "Dv REAPER_STATUS_REALINIT"
 136 .It Dv REAPER_STATUS_OWNED
 137 The specified process has acquired the reaper status and has not
 138 released it.
 139 When the flag is returned, the specified process
 140 .Fa id ,
 141 pid, identifies the reaper, otherwise the
 142 .Fa rs_reaper
 143 field of the structure is set to the pid of the reaper
 144 for the specified process id.
 145 .It Dv REAPER_STATUS_REALINIT
 146 The specified process is the root of the reaper tree, i.e.
 147 .Xr init 8 .
 148 .El
 149 The
 150 .Fa rs_children
 151 field returns the number of children of the reaper.
 152 The
 153 .Fa rs_descendants
 154 field returns the total number of descendants of the reaper(s),
 155 not counting descendants of the reaper in the subtree.
 156 The
 157 .Fa rs_reaper
 158 field returns the reaper pid.
 159 The
 160 .Fa rs_pid
 161 returns the pid of one reaper child if there are any descendants.
 162 .It Dv PROC_REAP_GETPIDS
 163 Queries the list of descendants of the reaper of the specified process.
 164 The request takes a pointer to a
 165 .Vt procctl_reaper_pids
 166 structure in the
 167 .Fa data
 168 parameter.
 169 .Bd -literal
 170 struct procctl_reaper_pids {
 171         u_int   rp_count;
 172         struct procctl_reaper_pidinfo *rp_pids;
 173 };
 174 .Ed
 175 When called, the
 176 .Fa rp_pids
 177 field must point to an array of
 178 .Vt procctl_reaper_pidinfo
 179 structures, to be filled in on return,
 180 and the
 181 .Fa rp_count
 182 field must specify the size of the array,
 183 into which no more than
 184 .Fa rp_count
 185 elements will be filled in by the kernel.
 186 .Pp
 187 The
 188 .Vt "struct procctl_reaper_pidinfo"
 189 structure provides some information about one of the reaper's descendants.
 190 Note that for a descendant that is not a child, it may be incorrectly
 191 identified because of a race in which the original child process exited
 192 and the exited process's pid was reused for an unrelated process.
 193 .Bd -literal
 194 struct procctl_reaper_pidinfo {
 195         pid_t   pi_pid;
 196         pid_t   pi_subtree;
 197         u_int   pi_flags;
 198 };
 199 .Ed
 200 The
 201 .Fa pi_pid
 202 field is the process id of the descendant.
 203 The
 204 .Fa pi_subtree
 205 field provides the pid of the child of the reaper, which is the (grand-)parent
 206 of the process.
 207 The
 208 .Fa pi_flags
 209 field returns the following flags, further describing the descendant:
 210 .Bl -tag -width "Dv REAPER_PIDINFO_VALID"
 211 .It Dv REAPER_PIDINFO_VALID
 212 Set to indicate that the
 213 .Vt procctl_reaper_pidinfo
 214 structure was filled in by the kernel.
 215 Zero-filling the
 216 .Fa rp_pids
 217 array and testing the
 218 .Dv REAPER_PIDINFO_VALID
 219 flag allows the caller to detect the end
 220 of the returned array.
 221 .It Dv REAPER_PIDINFO_CHILD
 222 The
 223 .Fa pi_pid
 224 field identifies the direct child of the reaper.
 225 .El
 226 .It Dv PROC_REAP_KILL
 227 Request to deliver a signal to some subset of the descendants of the reaper.
 228 The
 229 .Fa data
 230 parameter must point to a
 231 .Vt procctl_reaper_kill
 232 structure, which is used both for parameters and status return.
 233 .Bd -literal
 234 struct procctl_reaper_kill {
 235         int     rk_sig;
 236         u_int   rk_flags;
 237         pid_t   rk_subtree;
 238         u_int   rk_killed;
 239         pid_t   rk_fpid;
 240 };
 241 .Ed
 242 The
 243 .Fa rk_sig
 244 field specifies the signal to be delivered.
 245 Zero is not a valid signal number, unlike
 246 .Xr kill 2 .
 247 The
 248 .Fa rk_flags
 249 field further directs the operation.
 250 It is or-ed from the following flags:
 251 .Bl -tag -width "Dv REAPER_KILL_CHILDREN"
 252 .It Dv REAPER_KILL_CHILDREN
 253 Deliver the specified signal only to direct children of the reaper.
 254 .It Dv REAPER_KILL_SUBTREE
 255 Deliver the specified signal only to descendants that were forked by
 256 the direct child with pid specified in the
 257 .Fa rk_subtree
 258 field.
 259 .El
 260 If neither the
 261 .Dv REAPER_KILL_CHILDREN
 262 nor the
 263 .Dv REAPER_KILL_SUBTREE
 264 flags are specified, all current descendants of the reaper are signalled.
 265 .Pp
 266 If a signal was delivered to any process, the return value from the request
 267 is zero.
 268 In this case, the
 269 .Fa rk_killed
 270 field identifies the number of processes signalled.
 271 The
 272 .Fa rk_fpid
 273 field is set to the pid of the first process for which signal
 274 delivery failed, e.g. due to the permission problems.
 275 If no such process exist, the
 276 .Fa rk_fpid
 277 field is set to -1.
 278 .It Dv PROC_TRACE_CTL
 279 Enable or disable tracing of the specified process(es), according to the
 280 value of the integer argument.
 281 Tracing includes attachment to the process using
 282 .Xr ptrace 2
 283 and
 284 .Xr ktrace 2 ,
 285 debugging sysctls,
 286 .Xr hwpmc 4 ,
 287 .Xr dtrace 1
 288 and core dumping.
 289 Possible values for the
 290 .Fa data
 291 argument are:
 292 .Bl -tag -width "Dv PROC_TRACE_CTL_DISABLE_EXEC"
 293 .It Dv PROC_TRACE_CTL_ENABLE
 294 Enable tracing, after it was disabled by
 295 .Dv PROC_TRACE_CTL_DISABLE .
 296 Only allowed for self.
 297 .It Dv PROC_TRACE_CTL_DISABLE
 298 Disable tracing for the specified process.
 299 Tracing is re-enabled when the process changes the executing
 300 program with
 301 .Xr execve 2
 302 syscall.
 303 A child inherits the trace settings from the parent on
 304 .Xr fork 2 .
 305 .It Dv PROC_TRACE_CTL_DISABLE_EXEC
 306 Same as
 307 .Dv PROC_TRACE_CTL_DISABLE ,
 308 but the setting persist for the process even after
 309 .Xr execve 2 .
 310 .El
 311 .It Dv PROC_TRACE_STATUS
 312 Returns the current tracing status for the specified process in
 313 the integer variable pointed to by
 314 .Fa data .
 315 If tracing is disabled,
 316 .Fa data
 317 is set to -1.
 318 If tracing is enabled, but no debugger is attached by
 319 .Xr ptrace 2
 320 syscall,
 321 .Fa data
 322 is set to 0.
 323 If a debugger is attached,
 324 .Fa data
 325 is set to the pid of the debugger process.
 326 .El
 327 .Sh NOTES
 328 Disabling tracing on a process should not be considered a security
 329 feature, as it is bypassable both by the kernel and privileged processes,
 330 and via other system mechanisms.
 331 As such, it should not be relied on to reliably protect cryptographic
 332 keying material or other confidential data.
 333 .Sh RETURN VALUES
 334 If an error occurs, a value of -1 is returned and
 335 .Va errno
 336 is set to indicate the error.
 337 .Sh ERRORS
 338 The
 339 .Fn procctl
 340 system call
 341 will fail if:
 342 .Bl -tag -width Er
 343 .It Bq Er EFAULT
 344 The
 345 .Fa arg
 346 parameter points outside the process's allocated address space.
 347 .It Bq Er EINVAL
 348 The
 349 .Fa cmd
 350 argument specifies an unsupported command.
 351 .Pp
 352 The
 353 .Fa idtype
 354 argument specifies an unsupported identifier type.
 355 .It Bq Er EPERM
 356 The calling process does not have permission to perform the requested
 357 operation on any of the selected processes.
 358 .It Bq Er ESRCH
 359 No processes matched the requested
 360 .Fa idtype
 361 and
 362 .Fa id .
 363 .It Bq Er EINVAL
 364 An invalid operation or flag was passed in
 365 .Fa arg
 366 for a
 367 .Dv PROC_SPROTECT
 368 command.
 369 .It Bq Er EPERM
 370 The
 371 .Fa idtype
 372 argument is not equal to
 373 .Dv P_PID ,
 374 or
 375 .Fa id
 376 is not equal to the pid of the calling process, for
 377 .Dv PROC_REAP_ACQUIRE
 378 or
 379 .Dv PROC_REAP_RELEASE
 380 requests.
 381 .It Bq Er EINVAL
 382 Invalid or undefined flags were passed to a
 383 .Dv PROC_REAP_KILL
 384 request.
 385 .It Bq Er EINVAL
 386 An invalid or zero signal number was requested for a
 387 .Dv PROC_REAP_KILL
 388 request.
 389 .It Bq Er EINVAL
 390 The
 391 .Dv PROC_REAP_RELEASE
 392 request was issued by the
 393 .Xr init 8
 394 process.
 395 .It Bq Er EBUSY
 396 The
 397 .Dv PROC_REAP_ACQUIRE
 398 request was issued by a process that had already acquired reaper status
 399 and has not yet released it.
 400 .It Bq Er EBUSY
 401 The
 402 .Dv PROC_TRACE_CTL
 403 request was issued for a process already being traced.
 404 .It Bq Er EPERM
 405 The
 406 .Dv PROC_TRACE_CTL
 407 request to re-enable tracing of the process (
 408 .Dv PROC_TRACE_CTL_ENABLE ) ,
 409 or to disable persistence of the
 410 .Dv PROC_TRACE_CTL_DISABLE
 411 on
 412 .Xr execve 2
 413 was issued for a non-current process.
 414 .It Bq Er EINVAL
 415 The value of the integer
 416 .Fa data
 417 parameter for the
 418 .Dv PROC_TRACE_CTL
 419 request is invalid.
 420 .El
 421 .Sh SEE ALSO
 422 .Xr dtrace 1 ,
 423 .Xr kill 2 ,
 424 .Xr ktrace 2 ,
 425 .Xr ptrace 2 ,
 426 .Xr wait 2 ,
 427 .Xr hwpmc 4 ,
 428 .Xr init 8
 429 .Sh HISTORY
 430 The
 431 .Fn procctl
 432 function appeared in
 433 .Fx 10.0 .
 434 The reaper facility is based on a similar feature of Linux and
 435 DragonflyBSD, and first appeared in
 436 .Fx 10.2 .