MAN page from Trustix libcap-devel-1.10-5tr.i586.rpm

CAP_COPY_EXT

Section: Linux Programmer's Manual (3)
Updated: 26th May 1997
Index

NAME

cap_copy_ext, cap_size, cap_copy_int - capability state external representation translation

SYNOPSIS

#include <sys/capability.h>

ssize_t cap_size(cap_t cap_p);

ssize_t cap_copy_ext(void *ext_p, cap_t cap_p, ssize_t size);

cap_t cap_copy_int(const void *ext_p);

USAGE

cc ... -lcap

DESCRIPTION

These functions translate a capability state from an internal representationinto an external one. The external representation is an exportable, contiguous,persistent representation of a capability state in user-managed space. Theinternal representation is managed by the capability functions in workingstorage.

cap_sizereturns the total length (in bytes) that the capability state in workingstorage identified bycap_pwould require when converted bycap_copy_ext.This function is used primarily to determine the amount of buffer space thatmust be provided to thecap_copy_extfunction in order to hold the capability data record created fromcap_p.

cap_copy_extcopies a capability state in working storage, identified bycap_p,from system managed space to user-managed space (pointed to byext_p)and returns the length of the resulting data record. The size parameterrepresents the maximum size, in bytes, of the resulting data record. Thecap_copy_extfunction will do any conversions necessary to convert the capability statefrom the undefined internal format to an exportable, contiguous, persistentdata record. It is the responsibility of the user to allocate a buffer largeenough to hold the copied data. The buffer length required to hold the copieddata may be obtained by a call to thecap_sizefunction.

cap_copy_intcopies a capability state from a capability data record in user-managedspace to a new capability state in working storage, allocating anymemory necessary, and returning a pointer to the newly created capabilitystate. The function initializes the capability state and then copiesthe capability state from the record painted to byext_pinto the capability state, converting, if necessary, the data from acontiguous, persistent format to an undefined, internal format. Oncecopied into internal format, the object can be manipulated by the capabilitystate manipulation functions. Note that the record pointed to byext_pmust have been obtained from a previous, successful call tocap_copy_extfor this function to work successfully. The caller should free anyreleasable memory, when the capability state in working storage is nolonger required, by callingcap_freewith thecap_tas an argument.

RETURN VALUE

cap_sizereturns the length required to hold a capability data record on success,and -1 on failure.

cap_copy_extreturns the number of bytes placed in the user managed space pointed to byext_p on success, and -1 on failure.

cap_copy_intreturns a pointer to the newly created capability state in working storageon success, and NULL on failure.

On failure,errno(3)is set toEINVAL,ENOMEM,orERANGE.

CONFORMING TO

These functions are specified by POSIX.1e.

This document was created byman2html,using the manual pages.