1CAP_GET_FILE(3) Linux Programmer's Manual CAP_GET_FILE(3)
2
6 cap_get_file, cap_set_file, cap_get_fd, cap_set_fd - capability manipu‐
7 lation on files
8
10 #include <sys/capability.h>
11 cap_t cap_get_file(const char *path_p);
13 int cap_set_file(const char *path_p, cap_t cap_p);
15 cap_t cap_get_fd(int fd);
17 int cap_set_fd(int fd, cap_t caps);
19 uid_t cap_get_nsowner(cap_t caps);
21 int cap_set_nsowner(cap_t caps, uid_t rootid);
23 Link with -lcap.
25
27 cap_get_file() and cap_get_fd() allocate a capability state in working
28 storage and set it to represent the capability state of the pathname
29 pointed to by path_p or the file open on descriptor fd. These func‐
30 tions return a pointer to the newly created capability state. The
31 effects of reading the capability state from any file other than a reg‐
32 ular file is undefined. The caller should free any releasable memory,
33 when the capability state in working storage is no longer required, by
34 calling cap_free() with the used cap_t as an argument.
35 cap_set_file() and cap_set_fd() set the values for all capability flags
37 for all capabilities for the pathname pointed to by path_p or the file
38 open on descriptor fd, with the capability state identified by cap_p.
39 The new capability state of the file is completely determined by the
40 contents of cap_p. A NULL value for cap_p is used to indicate that
41 capabilities for the file should be deleted. For these functions to
42 succeed, the calling process must have the effective capability,
43 CAP_SETFCAP, enabled and either the effective user ID of the process
44 must match the file owner or the calling process must have the
45 CAP_FOWNER flag in its effective capability set. The effects of writ‐
46 ing the capability state to any file type other than a regular file are
47 undefined.
48 A capability set held in memory can be associated with the rootid in
50 use in a specific namespace. It is possible to get and set this value
51 (in the memory copy) with cap_get_nsowner() and cap_set_nsowner()
52 respectively. The rootid is ignored by the libcap library in all cases
53 other than when the capability is written to a file. Only if the value
54 is non-zero will the library attempt to include it in the written file
55 capability set.
56
58 cap_get_file() and cap_get_fd() return a non-NULL value on success, and
59 NULL on failure.
60 cap_set_file() and cap_set_fd() return zero on success, and -1 on fail‐
62 ure.
63 On failure, errno is set to EACCES, EBADFD, ENAMETOOLONG, ENOENT,
65 ENOMEM, ENOTDIR, EPERM, or EROFS.
66
68 These functions are specified by withdrawn POSIX.1e draft specifica‐
69 tion.
70
72 Support for file capabilities is provided on Linux since version
73 2.6.24.
74 On Linux, the file Effective set is a single bit. If it is enabled,
76 then all Permitted capabilities are enabled in the Effective set of the
77 calling process when the file is executed; otherwise, no capabilities
78 are enabled in the process's Effective set following an execve(2).
79 Because the file Effective set is a single bit, if any capability is
80 enabled in the Effective set of the cap_t given to cap_set_file() or
81 cap_set_fd(), then all capabilities whose Permitted or Inheritable flag
82 is enabled must also have the Effective flag enabled. Conversely, if
83 the Effective bit is enabled on a file, then the cap_t returned by
84 cap_get_file() and cap_get_fd() will have the Effective flag enabled
85 for each capability that has the Permitted or Inheritable flag enabled.
86
88 libcap(3), cap_clear(3), cap_copy_ext(3), cap_from_text(3),
89 cap_get_proc(3), cap_init(3), capabilities(7)
90 2008-05-11 CAP_GET_FILE(3)