| 1 |
.TH CAP_COPY_EXT 3 "2021-03-06" "" "Linux Programmer's Manual" |
| 2 |
.SH NAME |
| 3 |
cap_copy_ext, cap_size, cap_copy_int \- capability state |
| 4 |
external representation translation |
| 5 |
.SH SYNOPSIS |
| 6 |
.nf |
| 7 |
#include <sys/capability.h> |
| 8 |
|
| 9 |
ssize_t cap_size(cap_t cap_p); |
| 10 |
ssize_t cap_copy_ext(void *ext_p, cap_t cap_p, ssize_t size); |
| 11 |
cap_t cap_copy_int(const void * ext_p); |
| 12 |
cap_t cap_copy_int_check(const void *cap_ext, ssize_t length); |
| 13 |
.fi |
| 14 |
.sp |
| 15 |
Link with \fI\-lcap\fP. |
| 16 |
.SH DESCRIPTION |
| 17 |
These functions translate between internal and external |
| 18 |
representations of a capability state. The external representation is |
| 19 |
an exportable, contiguous, persistent representation of a capability |
| 20 |
state in user-managed space. The internal representation is managed |
| 21 |
by the capability functions in working storage. |
| 22 |
.PP |
| 23 |
.BR cap_size () |
| 24 |
returns the total length (in bytes) that the capability state in working |
| 25 |
storage identified by |
| 26 |
.I cap_p |
| 27 |
would require when converted by |
| 28 |
.BR cap_copy_ext (). |
| 29 |
This function is used primarily to determine the amount of buffer space that |
| 30 |
must be provided to the |
| 31 |
.BR cap_copy_ext () |
| 32 |
function in order to hold the capability data record created from |
| 33 |
.IR cap_p . |
| 34 |
.PP |
| 35 |
.BR cap_copy_ext () |
| 36 |
copies a capability state in working storage, identified by |
| 37 |
.IR cap_p , |
| 38 |
from system-managed space to user-managed space (pointed to by |
| 39 |
.IR ext_p ) |
| 40 |
and returns the length of the resulting data record. The size parameter |
| 41 |
represents the maximum size, in bytes, of the resulting data record. The |
| 42 |
.BR cap_copy_ext () |
| 43 |
function will do any conversions necessary to convert the capability |
| 44 |
state from the undefined internal format to an exportable, contiguous, |
| 45 |
persistent data record. It is the responsibility of the user to |
| 46 |
allocate a buffer large enough to hold the copied data. The buffer |
| 47 |
length required to hold the copied data may be obtained by a call to |
| 48 |
the |
| 49 |
.BR cap_size () |
| 50 |
function. |
| 51 |
.PP |
| 52 |
.BR cap_copy_int () |
| 53 |
copies a capability state from a capability data record in user-managed |
| 54 |
space to a new capability state in working storage, allocating any |
| 55 |
memory necessary, and returning a pointer to the newly created capability |
| 56 |
state. The function initializes the capability state and then copies |
| 57 |
the capability state from the record pointed to by |
| 58 |
.I ext_p |
| 59 |
into the capability state, converting, if necessary, the data from a |
| 60 |
contiguous, persistent format to an opaque, internal format. Once |
| 61 |
copied into internal format, the object can be manipulated by the |
| 62 |
capability state manipulation functions (see |
| 63 |
.BR cap_clear (3)). |
| 64 |
Note that the record pointed to by |
| 65 |
.I ext_p |
| 66 |
must have been obtained from a previous, successful call to |
| 67 |
.BR cap_copy_ext () |
| 68 |
for this function to work successfully. The caller should free any |
| 69 |
releasable memory, when the capability state in working storage is no |
| 70 |
longer required, by calling |
| 71 |
.BR cap_free () |
| 72 |
with the |
| 73 |
.I cap_t |
| 74 |
as an argument. |
| 75 |
.PP |
| 76 |
.BR cap_copy_int_check () |
| 77 |
performs the same operation as |
| 78 |
.BR cap_copy_int () |
| 79 |
but additionally checks that the provided external data's size is not |
| 80 |
larger than the noted length. |
| 81 |
.SH "RETURN VALUE" |
| 82 |
.BR cap_size () |
| 83 |
returns the length required to hold a capability data record on success, |
| 84 |
and \-1 on failure. |
| 85 |
.PP |
| 86 |
.BR cap_copy_ext () |
| 87 |
returns the number of bytes placed in the user managed space pointed to by |
| 88 |
.I ext_p |
| 89 |
on success, and \-1 on failure. |
| 90 |
.PP |
| 91 |
.BR cap_copy_int () |
| 92 |
and |
| 93 |
.BR cap_copy_int_check () |
| 94 |
return a pointer to the newly created capability state in working |
| 95 |
storage on success, and NULL on failure. |
| 96 |
.PP |
| 97 |
On failure, |
| 98 |
.BR errno |
| 99 |
is set to |
| 100 |
.BR EINVAL , |
| 101 |
.BR ENOMEM , |
| 102 |
or |
| 103 |
.BR ERANGE . |
| 104 |
.SH "CONFORMING TO" |
| 105 |
These functions are specified in the withdrawn POSIX.1e draft specification. |
| 106 |
.SH "SEE ALSO" |
| 107 |
.BR libcap (3), |
| 108 |
.BR cap_clear (3), |
| 109 |
.BR cap_from_text (3), |
| 110 |
.BR cap_get_file (3), |
| 111 |
.BR cap_get_proc (3), |
| 112 |
.BR cap_init (3), |
| 113 |
.BR capabilities (7) |