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


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


desc
@zefram's manual
@


1.1
log
@Initial revision
@
text
@.\"
.\" $Id$
.\" written by Andrew Main <zefram@@dcs.warwick.ac.uk>
.\"
.TH CAP_INIT 3 "26th April 1997" "" "Linux Programmer's Manual"
.SH NAME
cap_init, cap_free, cap_dup \- manipulate capability sets
.SH SYNOPSIS
.B #include <sys/capability.h>
.sp
.B cap_t cap_init(void);
.sp
.BI "int cap_free(cap_t *" caps_p );
.sp
.BI "cap_t cap_dup(cap_t " caps );
.SH USAGE
.br
.B cc ... -lcap
.SH DESCRIPTION
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.
.PP
.B cap_init
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 .
.PP
.B cap_free
frees the resources associated with the capability set
.IR *caps_p ,
and sets
.I *caps_p
to NULL.
.PP
.B cap_dup
returns a newly-allocated duplicate of the provided capability set.
.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)
@
