diff options
Diffstat (limited to 'doc/cap_init.3')
-rw-r--r-- | doc/cap_init.3 | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/doc/cap_init.3 b/doc/cap_init.3 new file mode 100644 index 0000000..f198f63 --- /dev/null +++ b/doc/cap_init.3 @@ -0,0 +1,86 @@ +.\" +.\" written by Andrew Main <zefram@dcs.warwick.ac.uk> +.\" +.TH CAP_INIT 3 "2008-05-11" "" "Linux Programmer's Manual" +.SH NAME +cap_init, cap_free, cap_dup \- capability data object storage management +.SH SYNOPSIS +.B #include <sys/capability.h> +.sp +.B cap_t cap_init(void); +.sp +.BI "int cap_free(void *" obj_d ); +.sp +.BI "cap_t cap_dup(cap_t " cap_p ); +.sp +Link with \fI-lcap\fP. +.SH DESCRIPTION +The capabilities associated with a file or process are never edited +directly. Instead, working storage is allocated to contain a +representation of the capability state. Capabilities are edited and +manipulated only within this working storage area. Once editing of +the capability state is complete, the updated capability state is used +to replace the capability state associated with the file or process. +.PP +.BR cap_init () +creates a capability state in working storage and returns a pointer to +the capability state. The initial value of all flags are cleared. 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. +.PP +.BR cap_free () +liberates any releasable memory that has been allocated to the +capability state identified by +.IR obj_d . +The +.I obj_d +argument may identify either a +.I cap_t +entity, or a +.I char * +entity allocated by the +.BR cap_to_text () +function. +.PP +.BR cap_dup () +returns a duplicate capability state in working storage given by the +source object +.IR cap_p , +allocating any memory necessary, and returning a +pointer to the newly created capability state. Once duplicated, no +operation on either capability state affects the other in any way. +When the duplicated capability state in working storage is no longer required, +the caller should free any releasable memory by calling +.BR cap_free () +with the +.I cap_t +as an argument. +.SH "RETURN VALUE" +.BR cap_init () +and +.BR cap_dup () +return a non-NULL value on success, and NULL on failure. +.PP +.BR cap_free () +returns zero on success, and \-1 on failure. +.PP +On failure, +.I errno +is set to +.BR EINVAL +or +.BR ENOMEM . +.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_copy_ext (3), +.BR cap_from_text (3), +.BR cap_get_file (3), +.BR cap_get_proc (3), +.BR capabilities (7) |