NAME

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

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

       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  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 effective capability,  CAP_SETFCAP,  enabled  and
       either  the  effective  user ID of the process must match the file owner or the calling process must have
       the CAP_FOWNER flag in its effective 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 is set to EACCES, EBADFD, ENAMETOOLONG, ENOENT, ENOMEM, ENOTDIR, EPERM, or EROFS.

CONFORMING TO

       These functions are specified by withdrawn POSIX.1e draft specification.

NOTES

       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.

SEE ALSO

       libcap(3), cap_clear(3), cap_copy_ext(3), cap_from_text(3), cap_get_proc(3), cap_init(3), capabilities(7)

                                                   2008-05-11                                    CAP_GET_FILE(3)