| 1 |
.\" |
| 2 |
.\" written by Andrew Main <[email protected]> |
| 3 |
.\" |
| 4 |
.TH CAP_INIT 3 "2021-03-06" "" "Linux Programmer's Manual" |
| 5 |
.SH NAME |
| 6 |
cap_init, cap_free, cap_dup \- capability data object storage management |
| 7 |
.SH SYNOPSIS |
| 8 |
.nf |
| 9 |
#include <sys/capability.h> |
| 10 |
|
| 11 |
cap_t cap_init(void); |
| 12 |
int cap_free(void *obj_d); |
| 13 |
cap_t cap_dup(cap_t cap_p); |
| 14 |
.fi |
| 15 |
.sp |
| 16 |
Link with \fI\-lcap\fP. |
| 17 |
.SH DESCRIPTION |
| 18 |
The capabilities associated with a file or process are never edited |
| 19 |
directly. Instead, working storage is allocated to contain a |
| 20 |
representation of the capability state. Capabilities are edited and |
| 21 |
manipulated only within this working storage area. Once editing of |
| 22 |
the capability state is complete, the updated capability state is used |
| 23 |
to replace the capability state associated with the file or process. |
| 24 |
.PP |
| 25 |
.BR cap_init () |
| 26 |
creates a capability state in working storage and returns a pointer to |
| 27 |
the capability state. The initial value of all flags are cleared. The |
| 28 |
caller should free any releasable memory, when the capability state in |
| 29 |
working storage is no longer required, by calling |
| 30 |
.BR cap_free () |
| 31 |
with the |
| 32 |
.I cap_t |
| 33 |
as an argument. |
| 34 |
.PP |
| 35 |
.BR cap_free () |
| 36 |
liberates any releasable memory that has been allocated to the |
| 37 |
capability state identified by |
| 38 |
.IR obj_d . |
| 39 |
The |
| 40 |
.I obj_d |
| 41 |
argument may identify either a |
| 42 |
.I cap_t |
| 43 |
entity, or a |
| 44 |
.I "char\ *" |
| 45 |
entity allocated by the |
| 46 |
.BR cap_to_text () |
| 47 |
function. |
| 48 |
.PP |
| 49 |
.BR cap_dup () |
| 50 |
returns a duplicate capability state in working storage given by the |
| 51 |
source object |
| 52 |
.IR cap_p , |
| 53 |
allocating any memory necessary, and returning a |
| 54 |
pointer to the newly created capability state. Once duplicated, no |
| 55 |
operation on either capability state affects the other in any way. |
| 56 |
When the duplicated capability state in working storage is no longer required, |
| 57 |
the caller should free any releasable memory by calling |
| 58 |
.BR cap_free () |
| 59 |
with the |
| 60 |
.I cap_t |
| 61 |
as an argument. |
| 62 |
.SH "RETURN VALUE" |
| 63 |
.BR cap_init () |
| 64 |
and |
| 65 |
.BR cap_dup () |
| 66 |
return a non-NULL value on success, and NULL on failure. |
| 67 |
.PP |
| 68 |
.BR cap_free () |
| 69 |
returns zero on success, and \-1 on failure. |
| 70 |
.PP |
| 71 |
On failure, |
| 72 |
.I errno |
| 73 |
is set to |
| 74 |
.BR EINVAL |
| 75 |
or |
| 76 |
.BR ENOMEM . |
| 77 |
.SH "CONFORMING TO" |
| 78 |
These functions are specified in the withdrawn POSIX.1e draft specification. |
| 79 |
.SH "SEE ALSO" |
| 80 |
.BR libcap (3), |
| 81 |
.BR cap_clear (3), |
| 82 |
.BR cap_copy_ext (3), |
| 83 |
.BR cap_from_text (3), |
| 84 |
.BR cap_get_file (3), |
| 85 |
.BR cap_get_proc (3), |
| 86 |
.BR capabilities (7) |