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