1.\"
2.\" Copyright (c) 2012 The FreeBSD Foundation
3.\" All rights reserved.
4.\"
5.\" This documentation was written by Pawel Jakub Dawidek under sponsorship
6.\" the FreeBSD Foundation.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
29.\" $FreeBSD$
30.\"
31.Dd May 5, 2020
32.Dt CAP_FCNTLS_LIMIT 2
33.Os
34.Sh NAME
35.Nm cap_fcntls_limit ,
36.Nm cap_fcntls_get
37.Nd manage allowed fcntl commands
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
41.In sys/capsicum.h
42.Ft int
43.Fn cap_fcntls_limit "int fd" "uint32_t fcntlrights"
44.Ft int
45.Fn cap_fcntls_get "int fd" "uint32_t *fcntlrightsp"
46.Sh DESCRIPTION
47If a file descriptor is granted the
48.Dv CAP_FCNTL
49capability right, the list of allowed
50.Xr fcntl 2
51commands can be selectively reduced (but never expanded) with the
52.Fn cap_fcntls_limit
53system call.
54.Pp
55A bitmask of allowed fcntls commands for a given file descriptor can be obtained
56with the
57.Fn cap_fcntls_get
58system call.
59.Sh FLAGS
60The following flags may be specified in the
61.Fa fcntlrights
62argument or returned in the
63.Fa fcntlrightsp
64argument:
65.Bl -tag -width CAP_FCNTL_GETOWN
66.It Dv CAP_FCNTL_GETFL
67Permit
68.Dv F_GETFL
69command.
70.It Dv CAP_FCNTL_SETFL
71Permit
72.Dv F_SETFL
73command.
74.It Dv CAP_FCNTL_GETOWN
75Permit
76.Dv F_GETOWN
77command.
78.It Dv CAP_FCNTL_SETOWN
79Permit
80.Dv F_SETOWN
81command.
82.El
83.Sh RETURN VALUES
84.Rv -std
85.Sh ERRORS
86.Fn cap_fcntls_limit
87succeeds unless:
88.Bl -tag -width Er
89.It Bq Er EBADF
90The
91.Fa fd
92argument is not a valid descriptor.
93.It Bq Er EINVAL
94An invalid flag has been passed in
95.Fa fcntlrights .
96.It Bq Er ENOTCAPABLE
97.Fa fcntlrights
98would expand the list of allowed
99.Xr fcntl 2
100commands.
101.El
102.Pp
103.Fn cap_fcntls_get
104succeeds unless:
105.Bl -tag -width Er
106.It Bq Er EBADF
107The
108.Fa fd
109argument is not a valid descriptor.
110.It Bq Er EFAULT
111The
112.Fa fcntlrightsp
113argument points at an invalid address.
114.El
115.Sh SEE ALSO
116.Xr cap_ioctls_limit 2 ,
117.Xr cap_rights_limit 2 ,
118.Xr fcntl 2
119.Sh HISTORY
120The
121.Fn cap_fcntls_get
122and
123.Fn cap_fcntls_limit
124system calls first appeared in
125.Fx 8.3 .
126Support for capabilities and capabilities mode was developed as part of the
127.Tn TrustedBSD
128Project.
129.Sh AUTHORS
130This function was created by
131.An Pawel Jakub Dawidek Aq Mt [email protected]
132under sponsorship of the FreeBSD Foundation.
133