lib/libc/sys/rctl_add_rule.2

   1 .\" Copyright (c) 2016 Eric Badger
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd September 14, 2016
  28 .Dt RCTL_ADD_RULE 2
  29 .Os
  30 .Sh NAME
  31 .Nm rctl_add_rule ,
  32 .Nm rctl_get_limits ,
  33 .Nm rctl_get_racct ,
  34 .Nm rctl_get_rules ,
  35 .Nm rctl_remove_rule
  36 .Nd manipulate and query the resource limits database
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/rctl.h
  41 .Ft int
  42 .Fo rctl_add_rule
  43 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  44 .Fc
  45 .Ft int
  46 .Fo rctl_get_limits
  47 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  48 .Fc
  49 .Ft int
  50 .Fo rctl_get_racct
  51 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  52 .Fc
  53 .Ft int
  54 .Fo rctl_get_rules
  55 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  56 .Fc
  57 .Ft int
  58 .Fo rctl_remove_rule
  59 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  60 .Fc
  61 .Sh DESCRIPTION
  62 These system calls are used to manipulate and query the resource limits
  63 database.
  64 For all functions,
  65 .Fa inbuflen
  66 refers to the length of the buffer pointed to by
  67 .Fa inbufp
  68 and
  69 .Fa outbuflen
  70 refers to the length of the buffer pointed to by
  71 .Fa outbufp .
  72 .Pp
  73 The
  74 .Fn rctl_add_rule
  75 function adds the rule pointed to by
  76 .Fa inbufp
  77 to the resource limits database.
  78 The
  79 .Fa outbufp
  80 and
  81 .Fa outbuflen
  82 arguments are unused.
  83 Rule format is as described in
  84 .Xr rctl 8 ,
  85 with exceptions noted in the
  86 .Sx RULES AND FILTERS
  87 section.
  88 .Pp
  89 The
  90 .Fn rctl_get_limits
  91 function returns in
  92 .Fa outbufp
  93 a comma-separated list of rules that apply to the process that
  94 matches the filter specified in
  95 .Fa inbufp .
  96 This includes rules with a subject of the process itself as well as rules
  97 with a different subject (such as user or loginclass) that apply to the
  98 process.
  99 .Pp
 100 The
 101 .Fn rctl_get_racct
 102 function returns resource usage information for a given subject.
 103 The subject is specified by passing a filter in
 104 .Fa inbufp .
 105 Filter syntax is as described in
 106 .Xr rctl 8 ,
 107 with exceptions noted in the
 108 .Sx RULES AND FILTERS
 109 section.
 110 A comma-separated list of resources and the amount used of each by the
 111 specified subject is returned in
 112 .Fa outbufp .
 113 The resource and amount is formatted as
 114 .Qq resource=amount .
 115 .Pp
 116 The
 117 .Fn rctl_get_rules
 118 function returns in
 119 .Fa outbufp
 120 a comma-separated list of rules from the resource limits database that
 121 match the filter passed in
 122 .Fa inbufp .
 123 Filter syntax is as described in
 124 .Xr rctl 8 ,
 125 with exceptions noted in the
 126 .Sx RULES AND FILTERS
 127 section.
 128 A filter of
 129 .Va ::
 130 may be passed to return all rules.
 131 .Pp
 132 The
 133 .Fn rctl_remove_rule
 134 function removes all rules matching the filter passed in
 135 .Fa inbufp
 136 from the resource limits database.
 137 Filter syntax is as described in
 138 .Xr rctl 8 ,
 139 with exceptions noted in the
 140 .Sx RULES AND FILTERS
 141 section.
 142 .Fa outbufp
 143 and
 144 .Fa outbuflen
 145 are unused.
 146 .Sh RULES AND FILTERS
 147 This section explains how the rule and filter format described in
 148 .Xr rctl 8
 149 differs from the format passed to the system calls themselves.
 150 The rctl tool provides several conveniences that the system calls do not.
 151 When using the system call:
 152 .Bl -dash -offset indent
 153 .It
 154 The subject must be fully specified.
 155 For example, abbreviating
 156 .Ql user
 157 to
 158 .Ql u
 159 is not acceptable.
 160 .It
 161 User and group IDs must be numeric.
 162 For example,
 163 .Ql root
 164 must be expressed as
 165 .Ql 0 .
 166 .It
 167 Units are not permitted on resource amounts.
 168 For example, a quantity of 1024 bytes must be expressed as
 169 .Ql 1024
 170 and not
 171 .Ql 1k .
 172 .El
 173 .Sh RETURN VALUES
 174 .Rv -std
 175 .Sh ERRORS
 176 The rctl system calls may fail if:
 177 .Bl -tag -width Er
 178 .It Bq Er ENOSYS
 179 RACCT/RCTL support is not present in the kernel or the
 180 .Va kern.racct.enable
 181 sysctl is 0.
 182 .It Bq Er EINVAL
 183 The rule or filter passed in
 184 .Fa inbufp
 185 is invalid.
 186 .It Bq Er EPERM
 187 User has insufficient privileges to carry out the requested operation.
 188 .It Bq Er E2BIG
 189 .Fa inbufp
 190 or
 191 .Fa outbufp
 192 are too large.
 193 .It Bq Er ESRCH
 194 No process matched the provided rule or filter.
 195 .It Bq Er ENAMETOOLONG
 196 The loginclass or jail name specified is too long.
 197 .It Bq Er ERANGE
 198 The rule amount is outside of the allowable range or
 199 .Fa outbufp
 200 is too small.
 201 .It Bq Er EOPNOTSUPP
 202 The requested operation is not supported for the given rule or filter.
 203 .It Bq Er EFAULT
 204 .Fa inbufp
 205 or
 206 .Fa outbufp
 207 refer to invalid addresses.
 208 .El
 209 .Sh SEE ALSO
 210 .Xr rctl 8
 211 .Sh HISTORY
 212 The rctl family of system calls appeared in
 213 .Fx 9.0 .
 214 .Sh AUTHORS
 215 .An -nosplit
 216 The rctl system calls were developed by
 217 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 218 under sponsorship from the FreeBSD Foundation.
 219 This manual page was written by
 220 .An Eric Badger Aq Mt badger@FreeBSD.org .