d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

mdoc(7) police: markup and minor content fixes.

Browse Source 
o Removed whitespace at EOL
o Removed hard sentence breaks
o Added cap_size() to the NAME section
o Normalized .Nd descriptions
o Fixed the abuses of .Nm and .Va
o Fixed some DESCRIPTION texts
o Fixed the RETURN VALUES and ERRORS texts to look more traditional

Reviewed by:	tmm
This commit is contained in:
Ruslan Ermilov 2001-09-05 14:09:08 +00:00
parent 76897a893f
commit 8872ae5340
2 changed files with 69 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
lib/libc/posix1e/cap_copy_ext.3
View File

@ -22,7 +22,7 @@
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
@ -30,87 +30,83 @@
.Dt CAP_COPY_EXT 3
.Os
.Sh NAME
.Nm cap_copy_ext
.Nd Convert a Capability State in Working Storage to an External Representation
.Nm cap_copy_ext , cap_size
.Nd convert a capability state in working storage to an external representation
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/capability.h>
.In sys/types.h
.In sys/capability.h
.Ft ssize_t
.Fn cap_copy_ext "void *ext_p" "cap_t cap" "ssize_t len"
.Ft ssize_t
.Fn cap_size "cap_t cap"
.Sh DESCRIPTION
The
.Nm
.Fn cap_copy_ext
function converts the capability state in working storage identified by
.Va cap
.Fa cap
to an opaque contiguous external representation in the buffer
.Va ext_p
points to.
.Va size
pointed to by
.Fa ext_p .
.Fa len
specifies the maximum number of bytes that may be written into the buffer.
.Pp
An application can use the
.Nm cap_size
.Fn cap_size
function to determine the amount of storage in bytes that are needed for
the external representation of
.Va cap .
.Fa cap .
.Sh IMPLEMENTATION NOTES
The format of the external representation is not specified in the POSIX.1e
draft. Applications that need a portable representation should use
draft.
Applications that need a portable representation should use
.Xr cap_to_text 3 .
.Pp
This function is appropriate in cases where a persistent representation is
needed that needs no to be portable. Due to endianess issues, this format might
needed that needs not to be portable.
Due to endianess issues, this format might
not even be portable between machines of different architectures running this
implementation.
.Pp
.Xr cap_copy_int 3
can be used to convert the external representation back to a
.Va cap_t .
.Vt cap_t .
.Sh RETURN VALUES
Upon successful completion, the
.Nm
.Fn cap_copy_ext
function returns the number of bytes written to
.Va ext_t .
.Nm cap_size
.Fa ext_p ,
and
.Fn cap_size
returns the number of bytes needed for the external representation of
.Va cap
if it is valid.
On error, both return
.Va -1
and set
.Fa cap .
Otherwise, the value \-1 is returned and the global variable
.Va errno
appropriately.
is set to indicate the error.
.Sh ERRORS
.Nm
can set
.Dv errno
to the following values:
.Bl -tag -width Er
.It Bq Er EINVAL
Either the
.Va cap
argument does not refer to a capability state in working storage
or the
.Va len
argument is below zero, or both.
.It Bq Er ERANGE
The buffer size specified by
.Va len
argument is too small to hold the external representation.
.El
.Pp
.Nm cap_size
can set
.Dv errno
to the following values:
.Fn cap_copy_ext
fails if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Va cap
.Fa cap
argument does not refer to a capability state in working storage,
or the
.Fa len
argument is negative.
.It Bq Er ERANGE
The buffer size specified by
.Fa len
argument is too small to hold the external representation.
.El
.Pp
.Fn cap_size
fails if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa cap
argument does not refer to a capability state in working storage.
.El
.Sh SEE ALSO
@ -123,12 +119,9 @@ argument does not refer to a capability state in working storage.
.Sh STANDARDS
This function is expected to conform to the withdrawn
IEEE draft 1003.1e
.Po
.Do POSIX.1e
.Dc
.Pc .
.Pq Dq POSIX.1e .
.Sh HISTORY
This function first appeared in
These functions first appeared in
.Fx 5.0 .
.Sh AUTHORS
.An Thomas Moestl Aq tmm@FreeBSD.org

53
lib/libc/posix1e/cap_copy_int.3
View File

@ -22,7 +22,7 @@
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
@ -31,54 +31,52 @@
.Os
.Sh NAME
.Nm cap_copy_int
.Nd Convert an External Capability Representation to a Capability State in
Working Storage
.Nd convert an external capability representation to a capability state in
working storage
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/capability.h>
.In sys/types.h
.In sys/capability.h
.Ft cap_t
.Fn cap_copy_int "void *ext_p"
.Sh DESCRIPTION
The
.Nm
function converts an external capability representation as returned by
.Nm cap_copy_ext
in the memory that
.Va ext_p
points to to a handle to a capability state in working storage.
.Fn cap_copy_int
function converts an external capability representation (as returned by
.Xr cap_copy_ext 3 )
in the buffer pointed to by
.Fa ext_p
to a handle to a capability state in working storage.
.Pp
This function may cause memory to be allocated.
The caller should free any releasable memory, when the capability state
in working memory is no longer required, by calling
.Xr cap_free 3
with the
.Va cap_t
.Vt cap_t
as an argument.
.Sh RETURN VALUES
Upon successful completion, the
.Nm
.Fn cap_copy_int
function returns a handle to a capability state in working storage.
On error, it returns
.Va (cap_t)NULL
and sets
Otherwise,
.Dv NULL
is returned and the global variable
.Va errno
appropriately.
is set to indicate the error.
.Sh ERRORS
The following
.Dv errno
values can be set by
.Nm cap_copy_ext :
.Fn cap_copy_int
fails if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Va ext_p
.Fa ext_p
does not refer to an external representation as returned by
.Xr cap_copy_ext 3
.Xr cap_copy_ext 3 .
.It Bq Er ENOMEM
Not enough memory could be allocated in the working storage to hold the
capability state.
The allocation of memory to hold the capability state
has failed.
.El
.Sh SEE ALSO
.Xr cap_copy_int 3 ,
@ -90,10 +88,7 @@ capability state.
.Sh STANDARDS
This function is expected to conform to the withdrawn
IEEE draft 1003.1e
.Po
.Do POSIX.1e
.Dc
.Pc .
.Pq Dq POSIX.1e .
.Sh HISTORY
This function first appeared in
.Fx 5.0 .