From f512fee07c7b5c08b1d7e75add344f688a0de070 Mon Sep 17 00:00:00 2001 From: ru Date: Wed, 5 Sep 2001 14:09:08 +0000 Subject: mdoc(7) police: markup and minor content fixes. 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 --- lib/libc/posix1e/cap_copy_ext.3 | 81 +++++++++++++++++++---------------------- lib/libc/posix1e/cap_copy_int.3 | 53 ++++++++++++--------------- 2 files changed, 61 insertions(+), 73 deletions(-) (limited to 'lib/libc/posix1e') diff --git a/lib/libc/posix1e/cap_copy_ext.3 b/lib/libc/posix1e/cap_copy_ext.3 index 26d4b34..76e3b2b 100644 --- a/lib/libc/posix1e/cap_copy_ext.3 +++ b/lib/libc/posix1e/cap_copy_ext.3 @@ -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 -.Fd #include +.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: +.Fn cap_copy_ext +fails if: .Bl -tag -width Er .It Bq Er EINVAL -Either the -.Va cap -argument does not refer to a capability state in working storage +The +.Fa cap +argument does not refer to a capability state in working storage, or the -.Va len -argument is below zero, or both. +.Fa len +argument is negative. .It Bq Er ERANGE The buffer size specified by -.Va len +.Fa 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_size +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. .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 diff --git a/lib/libc/posix1e/cap_copy_int.3 b/lib/libc/posix1e/cap_copy_int.3 index 5e12701..57682a4 100644 --- a/lib/libc/posix1e/cap_copy_int.3 +++ b/lib/libc/posix1e/cap_copy_int.3 @@ -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 -.Fd #include +.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 . -- cgit v1.1