head	1.2;
access;
symbols;
locks; strict;
comment	@# @;


1.2
date	97.05.24.19.45.28;	author morgan;	state Exp;
branches;
next	1.1;

1.1
date	97.04.28.00.54.52;	author morgan;	state Exp;
branches;
next	;


desc
@zefram's manual
@


1.2
log
@corrections from Aleph1
@
text
@.\"
.\" $Id: cap_init.3,v 1.1 1997/04/28 00:54:52 morgan Exp morgan $
.\" written by Andrew Main <zefram@@dcs.warwick.ac.uk>
.\"
.TH CAP_INIT 3 "26th May 1997" "" "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 );
.SH USAGE
.br
.B cc ... -lcap
.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
.B cap_init
creates a capability state in working storage and return 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
.B cap_free
with the 
.I cap_t
as an argument.
.PP
.B 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
.B cap_to_text
function.
.PP
.B 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.
.SH "RETURN VALUE"
.B cap_init
and
.B cap_dup
return a non-NULL value on success, and NULL on failure.
.PP
.B cap_free
returns zero on success, and \-1 on failure.
.PP
On failure,
.BR errno (3)
is set to
.BR EINVAL ,
or
.BR ENOMEM .
.SH "CONFORMING TO"
These functions are specified by POSIX.1e.
.SH "SEE ALSO"
.IR cap_clear (3),
.IR cap_copy_ext (3),
.IR cap_from_text (3),
.IR cap_get_file (3),
.IR cap_get_proc (3)
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" $Id$
d5 1
a5 1
.TH CAP_INIT 3 "26th April 1997" "" "Linux Programmer's Manual"
d7 1
a7 1
cap_init, cap_free, cap_dup \- manipulate capability sets
d13 1
a13 1
.BI "int cap_free(cap_t *" caps_p );
d15 1
a15 1
.BI "cap_t cap_dup(cap_t " caps );
d20 6
a25 6
POSIX.1e capability sets are manipulated abstractly via these interfaces.  A
.B cap_t
is a pointer to allocated memory, containing data maintained by the
capability library, that should not be modified directly.
The object represents a group of three sets of capability bits; the three
sets are the Effective, Inheritable and Permitted sets.
d28 8
a35 5
returns a newly-allocated empty capability set.  It is the caller's
responsibility to eventually dispose of the capability set with
.BR cap_free ,
as it is with all the other functions that return a
.BR cap_t .
d38 12
a49 5
frees the resources associated with the capability set
.IR *caps_p ,
and sets
.I *caps_p
to NULL.
d52 6
a57 1
returns a newly-allocated duplicate of the provided capability set.
@
