You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
105 lines
3.5 KiB
105 lines
3.5 KiB
.TH CAP_COPY_EXT 3 "2008-05-11" "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
cap_copy_ext, cap_size, cap_copy_int \- capability state
|
|
external representation translation
|
|
.SH SYNOPSIS
|
|
.B #include <sys/capability.h>
|
|
.sp
|
|
.BI "ssize_t cap_size(cap_t " cap_p );
|
|
.sp
|
|
.BI "ssize_t cap_copy_ext(void *" ext_p ", cap_t " cap_p ", ssize_t " size );
|
|
.sp
|
|
.BI "cap_t cap_copy_int(const void *" ext_p );
|
|
.sp
|
|
Link with \fI\-lcap\fP.
|
|
.SH DESCRIPTION
|
|
These functions translate between internal and external
|
|
representations of a capability state. The external representation is
|
|
an exportable, contiguous, persistent representation of a capability
|
|
state in user-managed space. The internal representation is managed
|
|
by the capability functions in working storage.
|
|
.PP
|
|
.BR cap_size ()
|
|
returns the total length (in bytes) that the capability state in working
|
|
storage identified by
|
|
.I cap_p
|
|
would require when converted by
|
|
.BR cap_copy_ext ().
|
|
This function is used primarily to determine the amount of buffer space that
|
|
must be provided to the
|
|
.BR cap_copy_ext ()
|
|
function in order to hold the capability data record created from
|
|
.IR cap_p .
|
|
.PP
|
|
.BR cap_copy_ext ()
|
|
copies a capability state in working storage, identified by
|
|
.IR cap_p ,
|
|
from system-managed space to user-managed space (pointed to by
|
|
.IR ext_p )
|
|
and returns the length of the resulting data record. The size parameter
|
|
represents the maximum size, in bytes, of the resulting data record. The
|
|
.BR cap_copy_ext ()
|
|
function will do any conversions necessary to convert the capability
|
|
state from the undefined internal format to an exportable, contiguous,
|
|
persistent data record. It is the responsibility of the user to
|
|
allocate a buffer large enough to hold the copied data. The buffer
|
|
length required to hold the copied data may be obtained by a call to
|
|
the
|
|
.BR cap_size ()
|
|
function.
|
|
.PP
|
|
.BR cap_copy_int ()
|
|
copies a capability state from a capability data record in user-managed
|
|
space to a new capability state in working storage, allocating any
|
|
memory necessary, and returning a pointer to the newly created capability
|
|
state. The function initializes the capability state and then copies
|
|
the capability state from the record pointed to by
|
|
.I ext_p
|
|
into the capability state, converting, if necessary, the data from a
|
|
contiguous, persistent format to an undefined, internal format. Once
|
|
copied into internal format, the object can be manipulated by the capability
|
|
state manipulation functions (see
|
|
.BR cap_clear (3)).
|
|
Note that the record pointed to by
|
|
.I ext_p
|
|
must have been obtained from a previous, successful call to
|
|
.BR cap_copy_ext ()
|
|
for this function to work successfully. The caller should free any
|
|
releasable memory, when the capability state in working storage is no
|
|
longer required, by calling
|
|
.BR cap_free ()
|
|
with the
|
|
.I cap_t
|
|
as an argument.
|
|
.SH "RETURN VALUE"
|
|
.BR cap_size ()
|
|
returns the length required to hold a capability data record on success,
|
|
and \-1 on failure.
|
|
.PP
|
|
.BR cap_copy_ext ()
|
|
returns the number of bytes placed in the user managed space pointed to by
|
|
.I ext_p
|
|
on success, and \-1 on failure.
|
|
.PP
|
|
.BR cap_copy_int ()
|
|
returns a pointer to the newly created capability state in working storage
|
|
on success, and NULL on failure.
|
|
.PP
|
|
On failure,
|
|
.BR errno
|
|
is set to
|
|
.BR EINVAL ,
|
|
.BR ENOMEM ,
|
|
or
|
|
.BR ERANGE .
|
|
.SH "CONFORMING TO"
|
|
These functions are specified in the withdrawn POSIX.1e draft specification.
|
|
.SH "SEE ALSO"
|
|
.BR libcap (3),
|
|
.BR cap_clear (3),
|
|
.BR cap_from_text (3),
|
|
.BR cap_get_file (3),
|
|
.BR cap_get_proc (3),
|
|
.BR cap_init (3),
|
|
.BR capabilities (7)
|