From c3eed03d15dbb5e1038dc39dc50c9f5a5fb7f9ec Mon Sep 17 00:00:00 2001
From: Mariusz Zaborski <oshogbo@FreeBSD.org>
Date: Wed, 5 Oct 2016 20:02:34 +0000
Subject: [PATCH] Add man pages for Capsicum helpers.

Reviewed by:	cem
Differential Revision:	https://reviews.freebsd.org/D8154
---
 lib/libcapsicum/Makefile           |  10 +++
 lib/libcapsicum/capsicum_helpers.3 | 110 +++++++++++++++++++++++++++++
 2 files changed, 120 insertions(+)
 create mode 100644 lib/libcapsicum/capsicum_helpers.3

diff --git a/lib/libcapsicum/Makefile b/lib/libcapsicum/Makefile
index 652729e16993..9dd3b80483b1 100644
--- a/lib/libcapsicum/Makefile
+++ b/lib/libcapsicum/Makefile
@@ -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>
diff --git a/lib/libcapsicum/capsicum_helpers.3 b/lib/libcapsicum/capsicum_helpers.3
new file mode 100644
index 000000000000..fe2e0e7d0876
--- /dev/null
+++ b/lib/libcapsicum/capsicum_helpers.3
@@ -0,0 +1,110 @@
+.\" Copyright (c) 2016 Mariusz Zaborski <oshogbo@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