Debian Codegraph @

doc/cap_init.3

raw
1 .\"
2 .\" written by Andrew Main <[email protected]>
3 .\"
4 .TH CAP_INIT 3 "2021-03-06" "" "Linux Programmer's Manual"
5 .SH NAME
6 cap_init, cap_free, cap_dup \- capability data object storage management
7 .SH SYNOPSIS
8 .nf
9 #include <sys/capability.h>
10
11 cap_t cap_init(void);
12 int cap_free(void *obj_d);
13 cap_t cap_dup(cap_t cap_p);
14 .fi
15 .sp
16 Link with \fI\-lcap\fP.
17 .SH DESCRIPTION
18 The capabilities associated with a file or process are never edited
19 directly. Instead, working storage is allocated to contain a
20 representation of the capability state. Capabilities are edited and
21 manipulated only within this working storage area. Once editing of
22 the capability state is complete, the updated capability state is used
23 to replace the capability state associated with the file or process.
24 .PP
25 .BR cap_init ()
26 creates a capability state in working storage and returns a pointer to
27 the capability state. The initial value of all flags are cleared. The
28 caller should free any releasable memory, when the capability state in
29 working storage is no longer required, by calling
30 .BR cap_free ()
31 with the
32 .I cap_t
33 as an argument.
34 .PP
35 .BR cap_free ()
36 liberates any releasable memory that has been allocated to the
37 capability state identified by
38 .IR obj_d .
39 The
40 .I obj_d
41 argument may identify either a
42 .I cap_t
43 entity, or a
44 .I "char\ *"
45 entity allocated by the
46 .BR cap_to_text ()
47 function.
48 .PP
49 .BR cap_dup ()
50 returns a duplicate capability state in working storage given by the
51 source object
52 .IR cap_p ,
53 allocating any memory necessary, and returning a
54 pointer to the newly created capability state. Once duplicated, no
55 operation on either capability state affects the other in any way.
56 When the duplicated capability state in working storage is no longer required,
57 the caller should free any releasable memory by calling
58 .BR cap_free ()
59 with the
60 .I cap_t
61 as an argument.
62 .SH "RETURN VALUE"
63 .BR cap_init ()
64 and
65 .BR cap_dup ()
66 return a non-NULL value on success, and NULL on failure.
67 .PP
68 .BR cap_free ()
69 returns zero on success, and \-1 on failure.
70 .PP
71 On failure,
72 .I errno
73 is set to
74 .BR EINVAL
75 or
76 .BR ENOMEM .
77 .SH "CONFORMING TO"
78 These functions are specified in the withdrawn POSIX.1e draft specification.
79 .SH "SEE ALSO"
80 .BR libcap (3),
81 .BR cap_clear (3),
82 .BR cap_copy_ext (3),
83 .BR cap_from_text (3),
84 .BR cap_get_file (3),
85 .BR cap_get_proc (3),
86 .BR capabilities (7)