Debian Codegraph @

doc/cap_copy_ext.3

raw
1 .TH CAP_COPY_EXT 3 "2021-03-06" "" "Linux Programmer's Manual"
2 .SH NAME
3 cap_copy_ext, cap_size, cap_copy_int \- capability state
4 external representation translation
5 .SH SYNOPSIS
6 .nf
7 #include <sys/capability.h>
8
9 ssize_t cap_size(cap_t cap_p);
10 ssize_t cap_copy_ext(void *ext_p, cap_t cap_p, ssize_t size);
11 cap_t cap_copy_int(const void * ext_p);
12 cap_t cap_copy_int_check(const void *cap_ext, ssize_t length);
13 .fi
14 .sp
15 Link with \fI\-lcap\fP.
16 .SH DESCRIPTION
17 These functions translate between internal and external
18 representations of a capability state. The external representation is
19 an exportable, contiguous, persistent representation of a capability
20 state in user-managed space. The internal representation is managed
21 by the capability functions in working storage.
22 .PP
23 .BR cap_size ()
24 returns the total length (in bytes) that the capability state in working
25 storage identified by
26 .I cap_p
27 would require when converted by
28 .BR cap_copy_ext ().
29 This function is used primarily to determine the amount of buffer space that
30 must be provided to the
31 .BR cap_copy_ext ()
32 function in order to hold the capability data record created from
33 .IR cap_p .
34 .PP
35 .BR cap_copy_ext ()
36 copies a capability state in working storage, identified by
37 .IR cap_p ,
38 from system-managed space to user-managed space (pointed to by
39 .IR ext_p )
40 and returns the length of the resulting data record. The size parameter
41 represents the maximum size, in bytes, of the resulting data record. The
42 .BR cap_copy_ext ()
43 function will do any conversions necessary to convert the capability
44 state from the undefined internal format to an exportable, contiguous,
45 persistent data record. It is the responsibility of the user to
46 allocate a buffer large enough to hold the copied data. The buffer
47 length required to hold the copied data may be obtained by a call to
48 the
49 .BR cap_size ()
50 function.
51 .PP
52 .BR cap_copy_int ()
53 copies a capability state from a capability data record in user-managed
54 space to a new capability state in working storage, allocating any
55 memory necessary, and returning a pointer to the newly created capability
56 state. The function initializes the capability state and then copies
57 the capability state from the record pointed to by
58 .I ext_p
59 into the capability state, converting, if necessary, the data from a
60 contiguous, persistent format to an opaque, internal format. Once
61 copied into internal format, the object can be manipulated by the
62 capability state manipulation functions (see
63 .BR cap_clear (3)).
64 Note that the record pointed to by
65 .I ext_p
66 must have been obtained from a previous, successful call to
67 .BR cap_copy_ext ()
68 for this function to work successfully. The caller should free any
69 releasable memory, when the capability state in working storage is no
70 longer required, by calling
71 .BR cap_free ()
72 with the
73 .I cap_t
74 as an argument.
75 .PP
76 .BR cap_copy_int_check ()
77 performs the same operation as
78 .BR cap_copy_int ()
79 but additionally checks that the provided external data's size is not
80 larger than the noted length.
81 .SH "RETURN VALUE"
82 .BR cap_size ()
83 returns the length required to hold a capability data record on success,
84 and \-1 on failure.
85 .PP
86 .BR cap_copy_ext ()
87 returns the number of bytes placed in the user managed space pointed to by
88 .I ext_p
89 on success, and \-1 on failure.
90 .PP
91 .BR cap_copy_int ()
92 and
93 .BR cap_copy_int_check ()
94 return a pointer to the newly created capability state in working
95 storage on success, and NULL on failure.
96 .PP
97 On failure,
98 .BR errno
99 is set to
100 .BR EINVAL ,
101 .BR ENOMEM ,
102 or
103 .BR ERANGE .
104 .SH "CONFORMING TO"
105 These functions are specified in the withdrawn POSIX.1e draft specification.
106 .SH "SEE ALSO"
107 .BR libcap (3),
108 .BR cap_clear (3),
109 .BR cap_from_text (3),
110 .BR cap_get_file (3),
111 .BR cap_get_proc (3),
112 .BR cap_init (3),
113 .BR capabilities (7)