diff options
Diffstat (limited to 'doc/cap_copy_ext.3')
-rw-r--r-- | doc/cap_copy_ext.3 | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/doc/cap_copy_ext.3 b/doc/cap_copy_ext.3 new file mode 100644 index 0000000..61d9381 --- /dev/null +++ b/doc/cap_copy_ext.3 @@ -0,0 +1,104 @@ +.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) |