Debian Codegraph @

doc/cap_get_file.3

raw
1 .\"
2 .\" written by Andrew Main <[email protected]>
3 .\"
4 .TH CAP_GET_FILE 3 "2022-10-16" "" "Linux Programmer's Manual"
5 .SH NAME
6 cap_get_file, cap_set_file, cap_get_fd, cap_set_fd, cap_get_nsowner, \
7 cap_set_nsowner \- capability manipulation on files
8 .SH SYNOPSIS
9 .nf
10 #include <sys/capability.h>
11
12 cap_t cap_get_file(const char *path_p);
13 int cap_set_file(const char *path_p, cap_t cap_p);
14 cap_t cap_get_fd(int fd);
15 int cap_set_fd(int fd, cap_t caps);
16 uid_t cap_get_nsowner(cap_t caps);
17 int cap_set_nsowner(cap_t caps, uid_t rootuid);
18 .fi
19 .sp
20 Link with \fI\-lcap\fP.
21 .SH DESCRIPTION
22 .BR cap_get_file ()
23 and
24 .BR cap_get_fd ()
25 allocate a capability state in working storage and set it to represent the
26 capability state of the pathname pointed to by
27 .I path_p
28 or the file open on descriptor
29 .IR fd .
30 These functions return a pointer to the newly created capability
31 state. The effects of reading the capability state from any file
32 other than a regular file is undefined. The caller should free any
33 releasable memory, when the capability state in working storage is no
34 longer required, by calling
35 .BR cap_free ()
36 with the used
37 .I cap_t
38 as an argument.
39 .PP
40 .BR cap_set_file ()
41 and
42 .BR cap_set_fd ()
43 set the values for all capability flags for all capabilities for the pathname
44 pointed to by
45 .I path_p
46 or the file open on descriptor
47 .IR fd ,
48 with the capability state identified by
49 .IR cap_p .
50 The new capability state of the file is completely determined by the
51 contents of
52 .IR cap_p .
53 A NULL value for
54 .IR cap_p
55 is used to indicate that capabilities for the file should be deleted.
56 For these functions to succeed, the calling process must have the
57 .BR CAP_SETFCAP
58 capability in its effective set
59 and either the effective user ID of the process must match the
60 file owner or the calling process must have the
61 .B CAP_FOWNER
62 capability in its effective capability set. The effects of writing the
63 capability state to any file type other than a regular file are
64 undefined.
65 .PP
66 A capability set held in memory can be associated with the root user ID in
67 use in a specific user namespace. It is possible to get and set this value
68 (in the memory copy) with
69 .BR cap_get_nsowner ()
70 and
71 .BR cap_set_nsowner ()
72 respectively. The root user ID is ignored by the libcap library in all cases
73 other than when the capability is written to a file. Only if the value
74 is non-zero will the library attempt to include it in the written file
75 capability set.
76 .SH "RETURN VALUE"
77 .BR cap_get_file ()
78 and
79 .BR cap_get_fd ()
80 return a non-NULL value on success, and NULL on failure.
81 .PP
82 .BR cap_set_file ()
83 and
84 .BR cap_set_fd ()
85 return zero on success, and \-1 on failure.
86 .PP
87 On failure,
88 .I errno
89 is set to
90 .BR EACCES ,
91 .BR EBADFD ,
92 .BR ENAMETOOLONG ,
93 .BR ENOENT ,
94 .BR ENOMEM ,
95 .BR ENOTDIR ,
96 .BR EPERM ,
97 or
98 .BR EROFS .
99 .SH "CONFORMING TO"
100 These functions are specified by withdrawn POSIX.1e draft specification.
101 .SH NOTES
102 Support for file capabilities is provided on Linux since version 2.6.24.
103
104 On Linux, the file Effective set is a single bit.
105 If it is enabled, then all Permitted capabilities are enabled
106 in the Effective set of the calling process when the file is executed;
107 otherwise, no capabilities are enabled in the process's Effective set
108 following an
109 .BR execve (2).
110 Because the file Effective set is a single bit,
111 if any capability is enabled in the Effective set of the
112 .I cap_t
113 given to
114 .BR cap_set_file ()
115 or
116 .BR cap_set_fd (),
117 then all capabilities whose Permitted or Inheritable flag
118 is enabled must also have the Effective flag enabled.
119 Conversely, if the Effective bit is enabled on a file, then the
120 .I cap_t
121 returned by
122 .BR cap_get_file()
123 and
124 .BR cap_get_fd()
125 will have the Effective flag enabled for each capability that has the
126 Permitted or Inheritable flag enabled.
127 .SH "SEE ALSO"
128 .BR libcap (3),
129 .BR cap_clear (3),
130 .BR cap_copy_ext (3),
131 .BR cap_from_text (3),
132 .BR cap_get_proc (3),
133 .BR cap_init (3),
134 .BR capabilities (7),
135 .BR user_namespaces (7)