87 lines
2.3 KiB
Groff
87 lines
2.3 KiB
Groff
.\"
|
|
.\" 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)
|