svn commit: r306298 - in stable: 10/lib/libc/sys 11/lib/libc/sys

[Eric Badger]

Author: badger
Date: Sat Sep 24 16:46:37 2016
New Revision: 306298
URL: https://svnweb.freebsd.org/changeset/base/306298

Log:
  MFC r305956: Add manpage for rctl_* system calls
  
  Approved by:	kib (mentor)
  Sponsored by:	Dell Technologies

Added:
  stable/10/lib/libc/sys/rctl_add_rule.2
     - copied unchanged from r305956, head/lib/libc/sys/rctl_add_rule.2
Modified:
  stable/10/lib/libc/sys/Makefile.inc
Directory Properties:
  stable/10/   (props changed)

Changes in other areas also in this revision:
Added:
  stable/11/lib/libc/sys/rctl_add_rule.2
     - copied unchanged from r305956, head/lib/libc/sys/rctl_add_rule.2
Modified:
  stable/11/lib/libc/sys/Makefile.inc
Directory Properties:
  stable/11/   (props changed)

Modified: stable/10/lib/libc/sys/Makefile.inc
==============================================================================
--- stable/10/lib/libc/sys/Makefile.inc	Sat Sep 24 15:11:27 2016	(r306297)
+++ stable/10/lib/libc/sys/Makefile.inc	Sat Sep 24 16:46:37 2016	(r306298)
@@ -259,6 +259,7 @@ MAN+=	abort2.2 \
 	pselect.2 \
 	ptrace.2 \
 	quotactl.2 \
+	rctl_add_rule.2 \
 	read.2 \
 	readlink.2 \
 	reboot.2 \
@@ -414,6 +415,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

Copied: stable/10/lib/libc/sys/rctl_add_rule.2 (from r305956, head/lib/libc/sys/rctl_add_rule.2)
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ stable/10/lib/libc/sys/rctl_add_rule.2	Sat Sep 24 16:46:37 2016	(r306298, copy of r305956, head/lib/libc/sys/rctl_add_rule.2)
@@ -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 at FreeBSD.org
+under sponsorship from the FreeBSD Foundation.
+This manual page was written by
+.An Eric Badger Aq Mt badger at FreeBSD.org .