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


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

1.2
date	97.05.04.05.32.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.3
log
@corrections from Aleph1
@
text
@.\"
.\" $Id: cap_copy_ext.3,v 1.2 1997/05/04 05:32:28 morgan Exp morgan $
.\"
.TH CAP_COPY_EXT 3 "26th May 1997" "" "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 );
.SH USAGE
.br
.B cc ... -lcap
.SH DESCRIPTION
These functions translate a capability state from an internal representation
into an external one.  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
.B 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
.B cap_copy_ext
function in order to hold the capability data record created from
.IR cap_p .
.PP
.B 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
.B 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
.B cap_size
function.
.PP
.B 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 painted 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.  Note that the record pointed to by
.I ext_p
must have been obtained from a previous, successful call to
.B 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
.B cap_free
with the
.I cap_t
as an argument.
.SH "RETURN VALUE"
.B cap_size
returns the length required to hold a capability data record on success,
and -1 on failure.
.PP
.B 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
.B 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 (3)
is set to
.BR EINVAL ,
.BR ENOMEM ,
or
.BR ERANGE .
.SH "CONFORMING TO"
These functions are specified by POSIX.1e.
.SH "SEE ALSO"
.IR cap_clear (3),
.IR cap_from_text (3),
.IR cap_get_file (3),
.IR cap_get_proc (3),
.IR cap_init (3)
@


1.2
log
@fixed title name
@
text
@d2 1
a2 1
.\" $Id: cap_copy_ext.3,v 1.1 1997/04/28 00:54:52 morgan Exp morgan $
d4 1
a4 1
.TH CAP_COPY_EXT 3 "26th April 1997" "" "Linux Programmer's Manual"
d6 1
a6 1
cap_copy_ext, cap_size, cap_copy_int \- external representation of capability sets
d10 1
a10 1
.BI "ssize_t cap_copy_ext(void *" extrep ", cap_t " caps ", ssize_t " length );
d12 1
a12 1
.BI "ssize_t cap_size(cap_t " caps );
d14 4
a17 1
.BI "cap_t cap_copy_int(void const *" extrep );
d19 5
a23 2
These functions provide an external representation of POSIX.1e capabilities,
suitable for storage in archives or communication over pipes, for example.
d25 8
d34 2
a35 7
copies the capability sets
.I caps
into the buffer
.I extrep
(of length
.IR length ),
and returns indicating how much of the buffer was actually used.
d37 13
d51 1
a51 3
returns indicating how large a buffer would be required to fully represent
the capability set
.IR caps .
d54 12
a65 3
takes a buffer
.IR extrep ,
whose contents are the result of a
d67 7
a73 4
call, and
reforms it into an internal-format capability set.
The return value must eventually be disposed of by passing it to
.BR cap_free .
d75 9
d85 2
a86 1
returns a non-NULL value on success, and NULL on failure.
d92 1
d94 1
a94 1
.BR ENOMEM .
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" $Id$
d4 1
a4 1
.TH CAP_INIT 3 "26th April 1997" "" "Linux Programmer's Manual"
@