xref: /illumos-gate/usr/src/man/man3c/priv_set.3c (revision 0a4ff7c0)
1.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
2.\" The contents of this file are subject to the terms of the Common
3.\" Development and Distribution License (the "License").  You may not use
4.\" this file except in compliance with the License.
5.\"
6.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or
7.\" http://www.opensolaris.org/os/licensing.  See the License for the
8.\" specific language governing permissions and limitations under the
9.\" License.
10.\"
11.\" When distributing Covered Code, include this CDDL HEADER in each file
12.\" and include the License file at usr/src/OPENSOLARIS.LICENSE.  If
13.\" applicable, add the following below this CDDL HEADER, with the fields
14.\" enclosed by brackets "[]" replaced with your own identifying
15.\" information: Portions Copyright [yyyy] [name of copyright owner]
16.\"
17.\" Copyright 2022 OmniOS Community Edition (OmniOSce) Association.
18.\"
19.Dd June 3, 2022
20.Dt PRIV_SET 3C
21.Os
22.Sh NAME
23.Nm priv_set ,
24.Nm priv_ineffect
25.Nd change privilege sets and check whether privileges are set
26.Sh SYNOPSIS
27.In priv.h
28.Ft int
29.Fo priv_set
30.Fa "priv_op_t op"
31.Fa "priv_ptype_t which"
32.Fa "..."
33.Fc
34.Ft boolean_t
35.Fo priv_ineffect
36.Fa "const char *priv"
37.Fc
38.Sh DESCRIPTION
39.Fn priv_set
40is a convenient wrapper for the
41.Xr setppriv 2
42function.
43It takes three or more arguments.
44The operation argument,
45.Ar op ,
46can be one of
47.Dv PRIV_OFF , PRIV_ON
48or
49.Dv PRIV_SET .
50The
51.Ar which
52argument is the name of the privilege set to change, one of
53.Dv PRIV_EFFECTIVE , PRIV_INHERITABLE , PRIV_PERMITTED , PRIV_LIMIT
54or the special pseudo set
55.Dv PRIV_ALLSETS
56if the operation should be applied to all privilege sets.
57Subsequent arguments provide zero or more privilege names, terminated with a
58.Dv NULL
59pointer.
60See
61.Sx EXAMPLES .
62.Pp
63The specified privileges are converted to a binary privilege set and
64.Xr setppriv 2
65is called with the same
66.Ar op
67and
68.Ar which
69arguments.
70When called with
71.Dv PRIV_ALLSETS
72as the value for the
73.Ar which
74argument,
75.Xr setppriv 2
76is called for each set in turn, aborting on the first failed call.
77.Pp
78.Fn priv_ineffect
79is a convenient wrapper for the
80.Xr getppriv 2
81function.
82The
83.Ar priv
84argument specifies the name of a privilege, and this function checks for its
85presence in the effective set.
86.Sh RETURN VALUES
87Upon successful completion,
88.Fn priv_set
89return 0.
90Otherwise, -1  is returned and
91.Dv errno
92is set to indicate the error.
93.Pp
94If
95.Ar priv
96is a valid privilege that is a member of the effective set,
97.Fn priv_ineffect
98returns
99.Dv B_TRUE .
100Otherwise, it returns
101.Dv B_FALSE
102and sets
103.Dv errno
104to indicate the error.
105.Sh EXAMPLES
106.Sy Example 1
107Using
108.Fn priv_set
109.Bd -literal -offset 6n
110#include <priv.h>
111\&...
112/* Remove basic privileges we don't need */
113(void) priv_set(PRIV_OFF, PRIV_PERMITTED, PRIV_PROC_EXEC,
114    PRIV_PROC_INFO, PRIV_FILE_LINK_ANY, PRIV_PROC_SESSION,
115    NULL);
116.Ed
117.Sh ERRORS
118The
119.Fn priv_set
120function will fail if:
121.Bl -tag -width Ds
122.It Er EINVAL
123The value of
124.Ar op
125or
126.Ar which
127is out of range.
128.It Er ENOMEM
129Insufficient memory was allocated.
130.It Er EPERM
131The application attempted to add privileges to
132.Dv PRIV_LIMIT
133or
134.Dv PRIV_PERMITTED ,
135or the application attempted to add privileges to
136.Dv PRIV_INHERITABLE
137or
138.Dv PRIV_EFFECTIVE
139that were not in
140.Dv PRIV_PERMITTED .
141.El
142.Pp
143The
144.Fn priv_ineffect
145function will fail if:
146.Bl -tag -width Ds
147.It Er EINVAL
148The privilege specified by
149.Ar priv
150is invalid.
151.It Er ENOMEM
152Insufficient memory was allocated.
153.El
154.Sh INTERFACE STABILITY
155.Sy Uncommitted
156.Sh MT-LEVEL
157.Sy MT-Safe
158.Sh SEE ALSO
159.Xr setppriv 2 ,
160.Xr priv_str_to_set 3C ,
161.Xr attributes 7 ,
162.Xr privileges 7
163