| 1 |
.TH CAP_CLEAR 3 "2022-10-16" "" "Linux Programmer's Manual" |
| 2 |
.SH NAME |
| 3 |
cap_clear, cap_clear_flag, cap_get_flag, cap_set_flag, cap_fill_flag, cap_fill, cap_compare, cap_max_bits \- capability data object manipulation |
| 4 |
.SH SYNOPSIS |
| 5 |
.nf |
| 6 |
#include <sys/capability.h> |
| 7 |
|
| 8 |
int cap_clear(cap_t cap_p); |
| 9 |
int cap_clear_flag(cap_t cap_p, cap_flag_t flag); |
| 10 |
int cap_get_flag(cap_t cap_p, cap_value_t cap, |
| 11 |
cap_flag_t flag, cap_flag_value_t *value_p); |
| 12 |
int cap_set_flag(cap_t cap_p, cap_flag_t flag, int ncap, |
| 13 |
const cap_value_t *caps, cap_flag_value_t value); |
| 14 |
int cap_fill_flag(cap_t cap_p, cap_flag_t to, |
| 15 |
const cap_t ref, cap_flag_t from); |
| 16 |
int cap_fill(cap_t cap_p, cap_flag_t to, cap_flag_t from); |
| 17 |
int cap_compare(cap_t cap_a, cap_t cap_b); |
| 18 |
cap_value_t cap_max_bits(); |
| 19 |
.fi |
| 20 |
.sp |
| 21 |
Link with \fI\-lcap\fP. |
| 22 |
.SH DESCRIPTION |
| 23 |
These functions work on a capability state held in working storage. |
| 24 |
A |
| 25 |
.I cap_t |
| 26 |
holds information about the capabilities in each of the three flags, |
| 27 |
Permitted, Inheritable, and Effective. |
| 28 |
Each capability in a set may be clear (disabled, 0) or set (enabled, 1). |
| 29 |
.PP |
| 30 |
These functions work with the following data types: |
| 31 |
.TP 18 |
| 32 |
.I cap_value_t |
| 33 |
identifies a capability, such as |
| 34 |
.BR CAP_CHOWN . |
| 35 |
.TP |
| 36 |
.I cap_flag_t |
| 37 |
identifies one of the three flags associated with a capability |
| 38 |
(i.e., it identifies one of the three capability dimensions). |
| 39 |
Valid values for this type are |
| 40 |
.BR CAP_EFFECTIVE , |
| 41 |
.B CAP_INHERITABLE |
| 42 |
or |
| 43 |
.BR CAP_PERMITTED . |
| 44 |
.TP |
| 45 |
.I cap_flag_value_t |
| 46 |
identifies the setting of a particular capability flag |
| 47 |
(i.e, the value of a capability in a set). |
| 48 |
Valid values for this type are |
| 49 |
.B CAP_CLEAR |
| 50 |
(0) or |
| 51 |
.B CAP_SET |
| 52 |
(1). |
| 53 |
.PP |
| 54 |
.BR cap_clear () |
| 55 |
initializes the capability state in working storage identified by |
| 56 |
.I cap_p |
| 57 |
so that all capability flags are cleared. |
| 58 |
.PP |
| 59 |
.BR cap_clear_flag () |
| 60 |
clears all of the capabilities of the specified capability flag, |
| 61 |
.IR flag . |
| 62 |
.PP |
| 63 |
.BR cap_get_flag () |
| 64 |
obtains the current value of the capability flag, |
| 65 |
.IR flag , |
| 66 |
of the capability, |
| 67 |
.IR cap , |
| 68 |
from the capability state identified by |
| 69 |
.I cap_p |
| 70 |
and places it in the location pointed to by |
| 71 |
.IR value_p . |
| 72 |
.PP |
| 73 |
.BR cap_set_flag () |
| 74 |
sets the flag, |
| 75 |
.IR flag , |
| 76 |
of each capability in the array |
| 77 |
.I caps |
| 78 |
in the capability state identified by |
| 79 |
.I cap_p |
| 80 |
to |
| 81 |
.IR value . |
| 82 |
The argument, |
| 83 |
.IR ncap , |
| 84 |
is used to specify the number of capabilities in the array, |
| 85 |
.IR caps . |
| 86 |
.PP |
| 87 |
.BR cap_fill_flag () |
| 88 |
fills the to flag of one capability set, with the values in the from |
| 89 |
flag of a reference capability set. |
| 90 |
.PP |
| 91 |
.BR cap_fill () |
| 92 |
fills the to flag values by copying all of the from flag values. |
| 93 |
.PP |
| 94 |
.BR cap_compare () |
| 95 |
compares two full capability sets and, in the spirit of |
| 96 |
.BR memcmp (), |
| 97 |
returns zero if the two capability sets are identical. A positive |
| 98 |
return |
| 99 |
.I value |
| 100 |
indicates there is a difference between them. The returned |
| 101 |
.I value |
| 102 |
carries further information about the |
| 103 |
.BI "cap_flag_t " flag |
| 104 |
differences. Specifically, the macro |
| 105 |
.B CAP_DIFFERS |
| 106 |
.RI ( value ", " flag ) |
| 107 |
evaluates to non-zero if the returned |
| 108 |
.I value |
| 109 |
differs in its |
| 110 |
.I flag |
| 111 |
components. |
| 112 |
.PP |
| 113 |
.BR cap_max_bits () |
| 114 |
returns the number of capability values known to the running |
| 115 |
kernel. This may differ from libcap's list known at compilation |
| 116 |
time. Unnamed, at compilation time, capabilites can be referred to |
| 117 |
numerically and libcap will handle them appropriately. Note, the |
| 118 |
running kernel wins and it gets to define what "all" capabilities |
| 119 |
means. |
| 120 |
.SH "RETURN VALUE" |
| 121 |
.BR cap_clear (), |
| 122 |
.BR cap_clear_flag (), |
| 123 |
.BR cap_get_flag () |
| 124 |
.BR cap_set_flag () |
| 125 |
and |
| 126 |
.BR cap_compare () |
| 127 |
return zero on success, and \-1 on failure. Other return values for |
| 128 |
.BR cap_compare () |
| 129 |
are described above. The function |
| 130 |
.BR cap_max_bits () |
| 131 |
returns a numeric value of type |
| 132 |
.B cap_value_t |
| 133 |
that is one larger than the largest actual value known to the running |
| 134 |
kernel. |
| 135 |
.PP |
| 136 |
On failure, |
| 137 |
.I errno |
| 138 |
is set to |
| 139 |
.BR EINVAL , |
| 140 |
indicating that one of the arguments is invalid. |
| 141 |
.SH "CONFORMING TO" |
| 142 |
These functions are mostly as per specified in the withdrawn POSIX.1e |
| 143 |
draft specification. The following are Linux extensions: |
| 144 |
.BR cap_fill (), |
| 145 |
.BR cap_fill_flag (), |
| 146 |
.BR cap_clear_flag (), |
| 147 |
.BR cap_compare () |
| 148 |
and |
| 149 |
.BR cap_max_bits (). |
| 150 |
.SH "SEE ALSO" |
| 151 |
.BR libcap (3), |
| 152 |
.BR cap_copy_ext (3), |
| 153 |
.BR cap_from_text (3), |
| 154 |
.BR cap_get_file (3), |
| 155 |
.BR cap_get_proc (3), |
| 156 |
.BR cap_init (3), |
| 157 |
.BR capabilities (7) |