Date: Mon, 19 Sep 2016 02:25:30 +0000 (UTC) From: Eric Badger <badger@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r305956 - head/lib/libc/sys Message-ID: <201609190225.u8J2PUvH022948@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: badger Date: Mon Sep 19 02:25:30 2016 New Revision: 305956 URL: https://svnweb.freebsd.org/changeset/base/305956 Log: Add manpage for rctl_* system calls Reviewed by: trasz, wblock Approved by: kib (mentor) MFC after: 3 days Sponsored by: Dell Technologies Differential Revision: https://reviews.freebsd.org/D7877 Added: head/lib/libc/sys/rctl_add_rule.2 (contents, props changed) Modified: head/lib/libc/sys/Makefile.inc Modified: head/lib/libc/sys/Makefile.inc ============================================================================== --- head/lib/libc/sys/Makefile.inc Sun Sep 18 22:03:26 2016 (r305955) +++ head/lib/libc/sys/Makefile.inc Mon Sep 19 02:25:30 2016 (r305956) @@ -260,6 +260,7 @@ MAN+= abort2.2 \ pselect.2 \ ptrace.2 \ quotactl.2 \ + rctl_add_rule.2 \ read.2 \ readlink.2 \ reboot.2 \ @@ -423,6 +424,10 @@ MLINKS+=pdfork.2 pdgetpid.2\ pdfork.2 pdwait4.2 MLINKS+=pipe.2 pipe2.2 MLINKS+=poll.2 ppoll.2 +MLINKS+=rctl_add_rule.2 rctl_get_limits.2 \ + rctl_add_rule.2 rctl_get_racct.2 \ + rctl_add_rule.2 rctl_get_rules.2 \ + rctl_add_rule.2 rctl_remove_rule.2 MLINKS+=read.2 pread.2 \ read.2 preadv.2 \ read.2 readv.2 Added: head/lib/libc/sys/rctl_add_rule.2 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/lib/libc/sys/rctl_add_rule.2 Mon Sep 19 02:25:30 2016 (r305956) @@ -0,0 +1,220 @@ +.\" Copyright (c) 2016 Eric Badger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 14, 2016 +.Dt RCTL_ADD_RULE 2 +.Os +.Sh NAME +.Nm rctl_add_rule, +.Nm rctl_get_limits +.Nm rctl_get_racct, +.Nm rctl_get_rules, +.Nm rctl_remove_rule +.Nd manipulate and query the resource limits database +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/rctl.h +.Ft int +.Fo rctl_add_rule +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_limits +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_racct +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_rules +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_remove_rule +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Sh DESCRIPTION +These system calls are used to manipulate and query the resource limits +database. +For all functions, +.Fa inbuflen +refers to the length of the buffer pointed to by +.Fa inbufp +and +.Fa outbuflen +refers to the length of the buffer pointed to by +.Fa outbufp . +.Pp +The +.Fn rctl_add_rule +function adds the rule pointed to by +.Fa inbufp +to the resource limits database. +The +.Fa outbufp +and +.Fa outbuflen +arguments are unused. +Rule format is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +.Pp +The +.Fn rctl_get_limits +function returns in +.Fa outbufp +a comma-separated list of rules that apply to the process that +matches the filter specified in +.Fa inbufp . +This includes rules with a subject of the process itself as well as rules +with a different subject (such as user or loginclass) that apply to the +process. +.Pp +The +.Fn rctl_get_racct +function returns resource usage information for a given subject. +The subject is specified by passing a filter in +.Fa inbufp . +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +A comma-separated list of resources and the amount used of each by the +specified subject is returned in +.Fa outbufp . +The resource and amount is formatted as +.Qq resource=amount . +.Pp +The +.Fn rctl_get_rules +function returns in +.Fa outbufp +a comma-separated list of rules from the resource limits database that +match the filter passed in +.Fa inbufp . +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +A filter of +.Va :: +may be passed to return all rules. +.Pp +The +.Fn rctl_remove_rule +function removes all rules matching the filter passed in +.Fa inbufp +from the resource limits database. +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +.Fa outbufp +and +.Fa outbuflen +are unused. +.Sh RULES AND FILTERS +This section explains how the rule and filter format described in +.Xr rctl 8 +differs from the format passed to the system calls themselves. +The rctl tool provides several conveniences that the system calls do not. +When using the system call: +.Bl -dash -offset indent +.It +The subject must be fully specified. +For example, abbreviating +.Ql user +to +.Ql u +is not acceptable. +.It +User and group IDs must be numeric. +For example, +.Ql root +must be expressed as +.Ql 0 . +.It +Units are not permitted on resource amounts. +For example, a quantity of 1024 bytes must be expressed as +.Ql 1024 +and not +.Ql 1k . +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The rctl system calls may fail if: +.Bl -tag -width Er +.It Bq Er ENOSYS +RACCT/RCTL support is not present in the kernel or the +.Va kern.racct.enable +sysctl is 0. +.It Bq Er EINVAL +The rule or filter passed in +.Fa inbufp +is invalid. +.It Bq Er EPERM +User has insufficient privileges to carry out the requested operation. +.It Bq Er E2BIG +.Fa inbufp +or +.Fa outbufp +are too large. +.It Bq Er ESRCH +No process matched the provided rule or filter. +.It Bq Er ENAMETOOLONG +The loginclass or jail name specified is too long. +.It Bq Er ERANGE +The rule amount is outside of the allowable range or +.Fa outbufp +is too small. +.It Bq Er EOPNOTSUPP +The requested operation is not supported for the given rule or filter. +.It Bq Er EFAULT +.Fa inbufp +or +.Fa outbufp +refer to invalid addresses. +.El +.Sh SEE ALSO +.Xr rctl 8 +.Sh HISTORY +The rctl family of system calls appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +The rctl system calls were developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. +This manual page was written by +.An Eric Badger Aq Mt badger@FreeBSD.org .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201609190225.u8J2PUvH022948>