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