xref: /freebsd/lib/libcapsicum/capsicum_helpers.3 (revision d3d381b2b194b4d24853e92eecef55f262688d1a)
1.\" Copyright (c) 2016 Mariusz Zaborski <oshogbo@FreeBSD.org>
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 AUTHORS 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 AUTHORS 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 July 18, 2018
28.Dt CAPSICUM_HELPERS 3
29.Os
30.Sh NAME
31.Nm caph_limit_stream ,
32.Nm caph_limit_stdin ,
33.Nm caph_limit_stderr ,
34.Nm caph_limit_stdout ,
35.Nm caph_limit_stdio ,
36.Nm caph_cache_tzdata ,
37.Nm caph_cache_catpages
38.Nd "set of the capsicum helpers, part of the libcapsicum"
39.Sh LIBRARY
40.Lb libcapsicum
41.Sh SYNOPSIS
42.In capsicum_helpers.h
43.Ft int
44.Fn caph_enter "void"
45.Ft int
46.Fn caph_enter_casper "void"
47.Ft int
48.Fn caph_limit_stream "int fd" "int flags"
49.Ft int
50.Fn caph_limit_stdin "void"
51.Ft int
52.Fn caph_limit_stderr "void"
53.Ft int
54.Fn caph_limit_stdout "void"
55.Ft int
56.Fn caph_limit_stdio "void"
57.Ft void
58.Fn caph_cache_tzdata "void"
59.Ft void
60.Fn caph_cache_catpages "void"
61.Sh DESCRIPTION
62The
63.Nm caph_enter
64is equivalent to the
65.Xr cap_enter 2
66it returns success when the kernel is built without support of the capability
67mode.
68.Pp
69The
70.Nm caph_enter_casper
71is equivalent to the
72.Nm caph_enter
73it returns success when the system is built without Casper support.
74.Pp
75The
76.Nm capsicum helpers
77are a set of a inline functions which simplify modifying programs to use
78Capsicum.
79The goal is to reduce duplicated code patterns.
80The
81.Nm capsicum helpers
82are part of
83.Nm libcapsicum
84but there is no need to link to the library.
85.Pp
86.Fn caph_limit_stream
87restricts capabilities on
88.Fa fd
89to only those needed by POSIX stream objects (that is, FILEs).
90.Pp
91These flags can be provided:
92.Pp
93.Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent
94.It Dv CAPH_IGNORE_EBADF
95Do not return an error if file descriptor is invalid.
96.It Dv CAPH_READ
97Set CAP_READ on limited descriptor.
98.It Dv CAPH_WRITE
99Set CAP_WRITE on limited descriptor.
100.El
101.Pp
102.Fn caph_limit_stdin ,
103.Fn caph_limit_stderr
104and
105.Fn caph_limit_stdout
106limit standard descriptors using the
107.Nm caph_limit_stream
108function.
109.Pp
110.Fn caph_limit_stdio
111limits stdin, stderr and stdout.
112.Pp
113.Fn caph_cache_tzdata
114precaches all timezone data needed to use
115.Li libc
116local time functions.
117.Pp
118.Fn caph_cache_catpages
119caches Native Language Support (NLS) data.
120NLS data is used for localized error printing by
121.Xr strerror 3
122and
123.Xr err 3 ,
124among others.
125.Ed
126.Sh SEE ALSO
127.Xr cap_enter 2 ,
128.Xr rights 4
129