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 .Dd September 14, 2016
  26 .Dt RCTL_ADD_RULE 2
  27 .Os
  28 .Sh NAME
  29 .Nm rctl_add_rule ,
  30 .Nm rctl_get_limits ,
  31 .Nm rctl_get_racct ,
  32 .Nm rctl_get_rules ,
  33 .Nm rctl_remove_rule
  34 .Nd manipulate and query the resource limits database
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In sys/rctl.h
  39 .Ft int
  40 .Fo rctl_add_rule
  41 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  42 .Fc
  43 .Ft int
  44 .Fo rctl_get_limits
  45 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  46 .Fc
  47 .Ft int
  48 .Fo rctl_get_racct
  49 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  50 .Fc
  51 .Ft int
  52 .Fo rctl_get_rules
  53 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  54 .Fc
  55 .Ft int
  56 .Fo rctl_remove_rule
  57 .Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen"
  58 .Fc
  59 .Sh DESCRIPTION
  60 These system calls are used to manipulate and query the resource limits
  61 database.
  62 For all functions,
  63 .Fa inbuflen
  64 refers to the length of the buffer pointed to by
  65 .Fa inbufp
  66 and
  67 .Fa outbuflen
  68 refers to the length of the buffer pointed to by
  69 .Fa outbufp .
  70 .Pp
  71 The
  72 .Fn rctl_add_rule
  73 function adds the rule pointed to by
  74 .Fa inbufp
  75 to the resource limits database.
  76 The
  77 .Fa outbufp
  78 and
  79 .Fa outbuflen
  80 arguments are unused.
  81 Rule format is as described in
  82 .Xr rctl 8 ,
  83 with exceptions noted in the
  84 .Sx RULES AND FILTERS
  85 section.
  86 .Pp
  87 The
  88 .Fn rctl_get_limits
  89 function returns in
  90 .Fa outbufp
  91 a comma-separated list of rules that apply to the process that
  92 matches the filter specified in
  93 .Fa inbufp .
  94 This includes rules with a subject of the process itself as well as rules
  95 with a different subject (such as user or loginclass) that apply to the
  96 process.
  97 .Pp
  98 The
  99 .Fn rctl_get_racct
 100 function returns resource usage information for a given subject.
 101 The subject is specified by passing a filter in
 102 .Fa inbufp .
 103 Filter syntax is as described in
 104 .Xr rctl 8 ,
 105 with exceptions noted in the
 106 .Sx RULES AND FILTERS
 107 section.
 108 A comma-separated list of resources and the amount used of each by the
 109 specified subject is returned in
 110 .Fa outbufp .
 111 The resource and amount is formatted as
 112 .Qq resource=amount .
 113 .Pp
 114 The
 115 .Fn rctl_get_rules
 116 function returns in
 117 .Fa outbufp
 118 a comma-separated list of rules from the resource limits database that
 119 match the filter passed in
 120 .Fa inbufp .
 121 Filter syntax is as described in
 122 .Xr rctl 8 ,
 123 with exceptions noted in the
 124 .Sx RULES AND FILTERS
 125 section.
 126 A filter of
 127 .Va ::
 128 may be passed to return all rules.
 129 .Pp
 130 The
 131 .Fn rctl_remove_rule
 132 function removes all rules matching the filter passed in
 133 .Fa inbufp
 134 from the resource limits database.
 135 Filter syntax is as described in
 136 .Xr rctl 8 ,
 137 with exceptions noted in the
 138 .Sx RULES AND FILTERS
 139 section.
 140 .Fa outbufp
 141 and
 142 .Fa outbuflen
 143 are unused.
 144 .Sh RULES AND FILTERS
 145 This section explains how the rule and filter format described in
 146 .Xr rctl 8
 147 differs from the format passed to the system calls themselves.
 148 The rctl tool provides several conveniences that the system calls do not.
 149 When using the system call:
 150 .Bl -dash -offset indent
 151 .It
 152 The subject must be fully specified.
 153 For example, abbreviating
 154 .Ql user
 155 to
 156 .Ql u
 157 is not acceptable.
 158 .It
 159 User and group IDs must be numeric.
 160 For example,
 161 .Ql root
 162 must be expressed as
 163 .Ql 0 .
 164 .It
 165 Units are not permitted on resource amounts.
 166 For example, a quantity of 1024 bytes must be expressed as
 167 .Ql 1024
 168 and not
 169 .Ql 1k .
 170 .El
 171 .Sh RETURN VALUES
 172 .Rv -std
 173 .Sh ERRORS
 174 The rctl system calls may fail if:
 175 .Bl -tag -width Er
 176 .It Bq Er ENOSYS
 177 RACCT/RCTL support is not present in the kernel or the
 178 .Va kern.racct.enable
 179 sysctl is 0.
 180 .It Bq Er EINVAL
 181 The rule or filter passed in
 182 .Fa inbufp
 183 is invalid.
 184 .It Bq Er EPERM
 185 User has insufficient privileges to carry out the requested operation.
 186 .It Bq Er E2BIG
 187 .Fa inbufp
 188 or
 189 .Fa outbufp
 190 are too large.
 191 .It Bq Er ESRCH
 192 No process matched the provided rule or filter.
 193 .It Bq Er ENAMETOOLONG
 194 The loginclass or jail name specified is too long.
 195 .It Bq Er ERANGE
 196 The rule amount is outside of the allowable range or
 197 .Fa outbufp
 198 is too small.
 199 .It Bq Er EOPNOTSUPP
 200 The requested operation is not supported for the given rule or filter.
 201 .It Bq Er EFAULT
 202 .Fa inbufp
 203 or
 204 .Fa outbufp
 205 refer to invalid addresses.
 206 .El
 207 .Sh SEE ALSO
 208 .Xr rctl 8
 209 .Sh HISTORY
 210 The rctl family of system calls appeared in
 211 .Fx 9.0 .
 212 .Sh AUTHORS
 213 .An -nosplit
 214 The rctl system calls were developed by
 215 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 216 under sponsorship from the FreeBSD Foundation.
 217 This manual page was written by
 218 .An Eric Badger Aq Mt badger@FreeBSD.org .