Name
cap_get_file, cap_set_file, cap_get_fd, cap_set_fd, cap_get_nsowner, \ cap_set_nsowner - capability manipulation on filesSynopsis
#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.
Description
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 descriptorfd. 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_SETFCAPcapability 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.
Return Value
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 .