xref: /freebsd/lib/libcapsicum/capsicum_helpers.3 (revision db70ff37a051dfa19f6f3f0f0c5e3571aba91982)
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 November 4, 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.Nm caph_enter ,
39.Nm caph_enter_casper ,
40.Nm caph_rights_limit ,
41.Nm caph_ioctls_limit ,
42.Nm caph_fcntls_limit
43.Nd "set of the capsicum helpers, part of the libcapsicum"
44.Sh LIBRARY
45.Lb libcapsicum
46.Sh SYNOPSIS
47.In capsicum_helpers.h
48.Ft int
49.Fn caph_enter "void"
50.Ft int
51.Fn caph_enter_casper "void"
52.Ft int
53.Fn caph_rights_limit "inf fd" "const cap_righst_t *rights"
54.Ft int
55.Fn caph_ioctls_limit "inf fd" "const unsigned long *cmds" "size_t ncmds"
56.Ft int
57.Fn caph_fcntls_limit "inf fd" "uint32_t fcntlrights"
58.Ft int
59.Fn caph_limit_stdin "void"
60.Ft int
61.Fn caph_limit_stderr "void"
62.Ft int
63.Fn caph_limit_stdout "void"
64.Ft int
65.Fn caph_limit_stdio "void"
66.Ft void
67.Fn caph_cache_tzdata "void"
68.Ft void
69.Fn caph_cache_catpages "void"
70.Sh DESCRIPTION
71The
72.Nm caph_enter ,
73.Nm caph_rights_limit ,
74.Nm caph_ioctls_limit
75and
76.Nm caph_fcntls_limit
77are respectively equivalent to
78.Xr cap_enter 2 ,
79.Xr cap_rights_limit 2 ,
80.Xr cap_ioctls_limit 2
81and
82.Xr cap_fcntls_limit 2 ,
83it returns success when the kernel is built without support of the capability
84mode.
85.Pp
86The
87.Nm caph_enter_casper
88is equivalent to the
89.Nm caph_enter
90it returns success when the system is built without Casper support.
91.Pp
92The
93.Nm capsicum helpers
94are a set of a inline functions which simplify modifying programs to use
95Capsicum.
96The goal is to reduce duplicated code patterns.
97The
98.Nm capsicum helpers
99are part of
100.Nm libcapsicum
101but there is no need to link to the library.
102.Pp
103.Fn caph_limit_stream
104restricts capabilities on
105.Fa fd
106to only those needed by POSIX stream objects (that is, FILEs).
107.Pp
108These flags can be provided:
109.Pp
110.Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent
111.It Dv CAPH_IGNORE_EBADF
112Do not return an error if file descriptor is invalid.
113.It Dv CAPH_READ
114Set CAP_READ on limited descriptor.
115.It Dv CAPH_WRITE
116Set CAP_WRITE on limited descriptor.
117.El
118.Pp
119.Fn caph_limit_stdin ,
120.Fn caph_limit_stderr
121and
122.Fn caph_limit_stdout
123limit standard descriptors using the
124.Nm caph_limit_stream
125function.
126.Pp
127.Fn caph_limit_stdio
128limits stdin, stderr and stdout.
129.Pp
130.Fn caph_cache_tzdata
131precaches all timezone data needed to use
132.Li libc
133local time functions.
134.Pp
135.Fn caph_cache_catpages
136caches Native Language Support (NLS) data.
137NLS data is used for localized error printing by
138.Xr strerror 3
139and
140.Xr err 3 ,
141among others.
142.Ed
143.Sh SEE ALSO
144.Xr cap_enter 2 ,
145.Xr cap_rights_limit 2 ,
146.Xr rights 4
147