written by Andrew Main <zefram@dcs.warwick.ac.uk>

cap_get_file, cap_set_file, cap_get_fd, cap_set_fd - capability manipulation on files #include <sys/capability.h> "cap_t cap_get_file(const char *" path_p ); "int cap_set_file(const char *" path_p ", cap_t " cap_p ); "cap_t cap_get_fd(int " fd ); "int cap_set_fd(int " fd ", cap_t " caps ); "uid_t cap_get_nsowner(cap_t " caps ); "int cap_set_nsowner(cap_t " caps ", uid_t " rootuid ); Link with -lcap. cap_get_file () and cap_get_fd () allocate a capability state in working storage and set it to represent the capability state of the pathname pointed to by path_p or the file open on descriptor fd . These functions return a pointer to the newly created capability state. The effects of reading the capability state from any file other than a regular file is undefined. The caller should free any releasable memory, when the capability state in working storage is no longer required, by calling cap_free () with the used cap_t as an argument.

cap_set_file () and cap_set_fd () set the values for all capability flags for all capabilities for the pathname pointed to by path_p or the file open on descriptor fd , with the capability state identified by cap_p . The new capability state of the file is completely determined by the contents of cap_p . A NULL value for cap_p is used to indicate that capabilities for the file should be deleted. For these functions to succeed, the calling process must have the CAP_SETFCAP capability in its effective set and either the effective user ID of the process must match the file owner or the calling process must have the CAP_FOWNER capability in its effective capability set. The effects of writing the capability state to any file type other than a regular file are undefined.

A capability set held in memory can be associated with the root user ID in use in a specific user namespace. It is possible to get and set this value (in the memory copy) with cap_get_nsowner () and cap_set_nsowner () respectively. The root user ID is ignored by the libcap library in all cases other than when the capability is written to a file. Only if the value is non-zero will the library attempt to include it in the written file capability set.

cap_get_file () and cap_get_fd () return a non-NULL value on success, and NULL on failure.

cap_set_file () and cap_set_fd () return zero on success, and -1 on failure.

On failure, errno is set to EACCES , EBADFD , ENAMETOOLONG , ENOENT , ENOMEM , ENOTDIR , EPERM , or EROFS .

These functions are specified by withdrawn POSIX.1e draft specification. Support for file capabilities is provided on Linux since version 2.6.24. On Linux, the file Effective set is a single bit. If it is enabled, then all Permitted capabilities are enabled in the Effective set of the calling process when the file is executed; otherwise, no capabilities are enabled in the process's Effective set following an execve (2). Because the file Effective set is a single bit, if any capability is enabled in the Effective set of the cap_t given to cap_set_file () or cap_set_fd (), then all capabilities whose Permitted or Inheritable flag is enabled must also have the Effective flag enabled. Conversely, if the Effective bit is enabled on a file, then the cap_t returned by cap_get_file() and cap_get_fd() will have the Effective flag enabled for each capability that has the Permitted or Inheritable flag enabled. libcap (3), cap_clear (3), cap_copy_ext (3), cap_from_text (3), cap_get_proc (3), cap_init (3), capabilities (7), user_namespaces (7)