svn commit: r306726 - head/lib/libcapsicum

[Mariusz Zaborski]

Author: oshogbo
Date: Wed Oct  5 20:02:34 2016
New Revision: 306726
URL: https://svnweb.freebsd.org/changeset/base/306726

Log:
  Add man pages for Capsicum helpers.
  
  Reviewed by:	cem
  Differential Revision:	https://reviews.freebsd.org/D8154

Added:
  head/lib/libcapsicum/capsicum_helpers.3   (contents, props changed)
Modified:
  head/lib/libcapsicum/Makefile

Modified: head/lib/libcapsicum/Makefile
==============================================================================
--- head/lib/libcapsicum/Makefile	Wed Oct  5 20:01:09 2016	(r306725)
+++ head/lib/libcapsicum/Makefile	Wed Oct  5 20:02:34 2016	(r306726)
@@ -4,4 +4,14 @@ PACKAGE=lib${LIB}
 
 INCS=	capsicum_helpers.h
 
+MAN+=	capsicum_helpers.3
+
+MLINKS+=capsicum_helpers.3 caph_limit_stream.3
+MLINKS+=capsicum_helpers.3 caph_limit_stdin.3
+MLINKS+=capsicum_helpers.3 caph_limit_stderr.3
+MLINKS+=capsicum_helpers.3 caph_limit_stdout.3
+MLINKS+=capsicum_helpers.3 caph_limit_stdio.3
+MLINKS+=capsicum_helpers.3 caph_cache_tzdata.3
+MLINKS+=capsicum_helpers.3 caph_cache_catpages.3
+
 .include <bsd.lib.mk>

Added: head/lib/libcapsicum/capsicum_helpers.3
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/lib/libcapsicum/capsicum_helpers.3	Wed Oct  5 20:02:34 2016	(r306726)
@@ -0,0 +1,110 @@
+.\" Copyright (c) 2016 Mariusz Zaborski <oshogbo at FreeBSD.org>
+.\" 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 AUTHORS 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 AUTHORS 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 October 5, 2016
+.Dt CAPSICUM_HELPERS 3
+.Os
+.Sh NAME
+.Nm caph_limit_stream ,
+.Nm caph_limit_stdin ,
+.Nm caph_limit_stderr ,
+.Nm caph_limit_stdout ,
+.Nm caph_limit_stdio ,
+.Nm caph_cache_tzdata ,
+.Nm caph_cache_catpages
+.Nd "set of the functions , part of the libcapsicum"
+.Sh LIBRARY
+.Lb libcapsicum
+.Sh SYNOPSIS
+.In capsicum_helpers.h
+.Ft int
+.Fn caph_limit_stream "int fd, int flags"
+.Ft int
+.Fn caph_limit_stdin "void"
+.Ft int
+.Fn caph_limit_stderr "void"
+.Ft int
+.Fn caph_limit_stdout "void"
+.Ft int
+.Fn caph_limit_stdio "void"
+.Ft void
+.Fn caph_cache_tzdata "void"
+.Ft void
+.Fn caph_cache_catpages "void"
+.Sh DESCRIPTION
+The
+.Nm capsicum helpers
+are a set of a inline functions which simplify Capsicumizing programs.
+The goal is to reduce duplicated code patterns.
+The
+.Nm capsicum helpers
+are part of
+.Nm libcapsicum
+but there is no need to link to the library.
+.Pp
+.Fn caph_limit_stream
+restricts capabilities on
+.Fa fd
+to only those needed by POSIX stream objects (that is, FILEs).
+.Pp
+The following flags can be provided:
+.Pp
+.Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent
+.It Dv CAPH_IGNORE_EBADF
+Do not return an error if file descriptor is invalid.
+.It Dv CAPH_READ
+Set CAP_READ on limited descriptor.
+.It Dv CAPH_WRITE
+Set CAP_WRITE on limited descriptor.
+.El
+.Pp
+.Fn caph_limit_stdin ,
+.Fn caph_limit_stderr
+and
+.Fn caph_limit_stdout
+limit standard descriptors using the
+.Nm caph_limit_stream
+function.
+.Pp
+.Fn caph_limit_stdio
+limits stdin, stderr and stdout.
+.Pp
+.Fn caph_cache_tzdata
+precaches all timezone data needed to use
+.Li libc
+local time functions.
+.Pp
+.Fn caph_cache_catpages
+caches Native Language Support (NLS) data.
+NLS data is used for localized error printing by
+.Xr strerror 3
+and
+.Xr err 3 ,
+among others.
+.Ed
+.Sh SEE ALSO
+.Xr cap_enter 2 ,
+.Xr rights 4