Debian Codegraph @

doc/cap_from_text.3

raw
1 .\"
2 .\" written by Andrew Main <[email protected]>
3 .\"
4 .TH CAP_FROM_TEXT 3 "2025-03-19" "" "Linux Programmer's Manual"
5 .SH NAME
6 cap_from_text, cap_to_text, cap_to_name, cap_from_name \- capability
7 state textual representation translation
8 .SH SYNOPSIS
9 .nf
10 #include <sys/capability.h>
11
12 cap_t cap_from_text(const char *buf_p);
13 char *cap_to_text(cap_t caps, ssize_t *len_p);
14 int cap_from_name(const char *name, cap_value_t *cap_p);
15 char *cap_to_name(cap_value_t cap);
16 .fi
17 .sp
18 Link with \fI\-lcap\fP.
19 .SH DESCRIPTION
20 These functions translate a capability state between
21 an internal representation and a textual one.
22 The internal representation is managed by the capability
23 functions in working storage. The textual representation is a structured,
24 human-readable string suitable for display.
25 .PP
26 .BR cap_from_text ()
27 allocates and initializes a capability state in working storage. It
28 then sets the contents of this newly created capability state to the
29 state represented by a human-readable, nul-terminated character
30 string pointed to by
31 .IR buf_p .
32 It returns a pointer to the newly created capability state.
33 When the capability state in working storage is no longer required,
34 the caller should free any releasable memory
35 by calling
36 .BR cap_free ()
37 with
38 .I cap_t
39 as an argument. The function returns an error if it cannot parse the
40 contents of the string pointed to by
41 .I buf_p
42 or does not recognize any
43 .I capability_name
44 or flag character as valid. The function also returns an error if any flag
45 is both set and cleared within a single clause.
46 .PP
47 .BR cap_to_text ()
48 converts the capability state in working storage identified by
49 .I caps
50 into a nul-terminated human-readable string. This function allocates
51 any memory necessary to contain the string, and returns a pointer to
52 the string. If the pointer
53 .I len_p
54 is not NULL,
55 the function shall also return the full length of the string (not including
56 the nul terminator) in the location pointed to by
57 .IR len_p .
58 The capability state in working storage, identified by
59 .IR caps ,
60 is completely represented in the character string.
61 When the capability state in working storage is no longer required,
62 the caller should free any releasable memory by calling
63 .BR cap_free ()
64 with the returned string pointer as an argument.
65 .PP
66 .BR cap_from_name ()
67 converts a text representation of a capability, such as "cap_chown",
68 to its numerical representation
69 .RB ( CAP_CHOWN=0 ),
70 writing the decoded value into
71 .IR *cap_p .
72 If
73 .I cap_p
74 is NULL
75 no result is written, but the return code of the function indicates
76 whether or not the specified capability can be represented by the
77 library.
78 .PP
79 .BR cap_to_name ()
80 converts a capability index value,
81 .IR cap ,
82 to a libcap-allocated textual string. This string should be
83 deallocated with
84 .BR cap_free ().
85 .SH "TEXTUAL REPRESENTATION"
86 The text format is described in the
87 .BR cap_text_formats (7)
88 man page.
89 .SH "RETURN VALUE"
90 .BR cap_from_text (),
91 .BR cap_to_text ()
92 and
93 .BR cap_to_name ()
94 return a non-NULL value on success, and NULL on failure.
95 .BR cap_from_name ()
96 returns 0 for success, and \-1 on failure (unknown capability).
97 .PP
98 On failure,
99 .I errno
100 is set to
101 .BR EINVAL ,
102 or
103 .BR ENOMEM .
104 .SH "CONFORMING TO"
105 .BR cap_from_text ()
106 and
107 .BR cap_to_text ()
108 are specified by the withdrawn POSIX.1e draft specification.
109 .BR cap_from_name ()
110 and
111 .BR cap_to_name ()
112 are Linux extensions.
113 .SH EXAMPLE
114 The example program below demonstrates the use of
115 .BR cap_from_text ()
116 and
117 .BR cap_to_text ().
118 The following shell session shows some example runs:
119 .nf
120
121 $ ./a.out "cap_chown=p cap_chown+e"
122 caps_to_text() returned "cap_chown=ep"
123 $ ./a.out "all=pe cap_chown\-e cap_kill\-pe"
124 caps_to_text() returned "=ep cap_chown\-e cap_kill\-ep"
125
126 .fi
127 The source code of the program is as follows:
128 .nf
129
130 #include <stdlib.h>
131 #include <stdio.h>
132 #include <sys/capability.h>
133
134 #define handle_error(msg) \\
135 do { perror(msg); exit(EXIT_FAILURE); } while (0)
136
137 int
138 main(int argc, char *argv[])
139 {
140 cap_t caps;
141 char *txt_caps;
142
143 if (argc != 2) {
144 fprintf(stderr, "%s <textual\-cap\-set>\\n", argv[0]);
145 exit(EXIT_FAILURE);
146 }
147
148 caps = cap_from_text(argv[1]);
149 if (caps == NULL)
150 handle_error("cap_from_text");
151
152 txt_caps = cap_to_text(caps, NULL);
153 if (txt_caps == NULL)
154 handle_error("cap_to_text");
155
156 printf("caps_to_text() returned \\"%s\\"\\n", txt_caps);
157
158 if (cap_free(txt_caps) != 0 || cap_free(caps) != 0)
159 handle_error("cap_free");
160
161 exit(EXIT_SUCCESS);
162 }
163 .fi
164 .SH "SEE ALSO"
165 .BR libcap (3),
166 .BR cap_clear (3),
167 .BR cap_copy_ext (3),
168 .BR cap_get_file (3),
169 .BR cap_get_proc (3),
170 .BR cap_init (3),
171 .BR cap_text_formats (7),
172 .BR capabilities (7)