CAP_GET_FILE(3)

NAME
cap_get_file, cap_set_file, cap_get_fd, cap_set_fd - capability manipulation on files

Note: support for file capabilities is anticipated in Linux 2.6.23+

SYNOPSIS

#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);

USAGE
cc ... -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 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 shall be 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 enabled and either the effective user ID of the process must match the file owner or the calling process must have the effective flag of the CAP_FOWNER capability set. The effects of writing the capability state to any file type other than a regular file are undefined.

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(3) is set to EACCES, EBADFD, ENAMETOOLONG, ENOENT, ENOMEM, ENOTDIR, EPERM, or EROFS.

CONFORMING TO
These functions are specified by POSIX.1e.

SEE ALSO
cap_clear(3), cap_copy_ext(3), cap_from_text(3), cap_get_proc(3), cap_init(3)