lib/libc/sys/procctl.2

   1 .\" Copyright (c) 2013 Advanced Computing Technologies LLC
   2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 19, 2013
  29 .Dt PROCCTL 2
  30 .Os
  31 .Sh NAME
  32 .Nm procctl
  33 .Nd control processes
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/procctl.h
  38 .Ft int
  39 .Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *arg"
  40 .Sh DESCRIPTION
  41 The
  42 .Fn procctl
  43 system call provides for control over processes.
  44 The
  45 .Fa idtype
  46 and
  47 .Fa id
  48 arguments specify the set of processes to control.
  49 If multiple processes match the identifier,
  50 .Nm
  51 will make a
  52 .Dq best effort
  53 to control as many of the selected possibles as possible.
  54 An error is only returned if no selected processes successfully complete
  55 the request.
  56 The following identifier types are supported:
  57 .Bl -tag -width "Dv P_PGID"
  58 .It Dv P_PID
  59 Control the process with the process ID
  60 .Fa id .
  61 .It Dv P_PGID
  62 Control processes belonging to the process group with the ID
  63 .Fa id .
  64 .El
  65 .Pp
  66 The control request to perform is specified by the
  67 .Fa cmd
  68 argument.
  69 The following commands are supported:
  70 .Bl -tag -width "Dv PROC_SPROTECT"
  71 .It Dv PROC_SPROTECT
  72 Set process protection state.
  73 This is used to mark a process as protected from being killed if the system
  74 exhausts available memory and swap.
  75 The
  76 .Fa arg
  77 parameter must point to an integer containing an operation and zero or more
  78 optional flags.
  79 The following operations are supported:
  80 .Bl -tag -width "Dv PPROT_CLEAR"
  81 .It Dv PPROT_SET
  82 Mark the selected processes as protected.
  83 .It Dv PPROT_CLEAR
  84 Clear the protected state of selected processes.
  85 .El
  86 .Pp
  87 The following optional flags are supported:
  88 .Bl -tag -width "Dv PPROT_DESCE"
  89 .It Dv PPROT_DESCEND
  90 Apply the requested operation to all child processes of each selected process
  91 in addition to each selected process.
  92 .It Dv PPROT_INHERIT
  93 When used with
  94 .Dv PPROT_SET ,
  95 mark all future child processes of each selected process as protected.
  96 Future child processes will also mark all of their future child processes.
  97 .El
  98 .El
  99 .Sh RETURN VALUES
 100 If an error occurs, a value of -1 is returned and
 101 .Va errno
 102 is set to indicate the error.
 103 .Sh ERRORS
 104 The
 105 .Fn procctl
 106 system call
 107 will fail if:
 108 .Bl -tag -width Er
 109 .It Bq Er EFAULT
 110 The
 111 .Fa arg
 112 points outside the process's allocated address space.
 113 .It Bq Er EINVAL
 114 The
 115 .Fa cmd
 116 argument specifies an unsupported command.
 117 .Pp
 118 The
 119 .Fa idtype
 120 argument specifies an unsupported identifier type.
 121 .It Bq Er EPERM
 122 The calling process does not have permission to perform the requested
 123 operation on any of the selected processes.
 124 .It Bq Er ESRCH
 125 No processes matched the requested
 126 .Fa idtype
 127 and
 128 .Fa id .
 129 .It Bq Er EINVAL
 130 An invalid operation or flag was passed in
 131 .Fa arg
 132 for a
 133 .Dv PROC_SPROTECT
 134 command.
 135 .El
 136 .Sh SEE ALSO
 137 .Xr ptrace 2
 138 .Sh HISTORY
 139 The
 140 .Fn procctl
 141 function appeared in
 142 .Fx 10 .