cap_get_file(3C)

NAME
     cap_get_file, cap_set_file - get or set the capabilities for a pathname

SYNOPSIS
     #include <sys/capability.h>

     cap_t cap_get_file(const char *path);
     int cap_set_file(const char *path, cap_t cap);

DESCRIPTION
     cap_get_file returns a pointer to an allocated cap_t associated with the
     pathname pointed to by path. If there is no capability set associated
     with the file, cap_get_file returns a NULL pointer and sets errno to
     ENOATTR.  If _POSIX_MAC is in effect, then the process must have MAC read
     access to the object.

     cap_set_file sets the capabilities of the specified pathname.  For this
     function to succeed, the 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. In addition, if _POSIX_MAC is defined, then
     the process must have MAC write access to the file.

RETURN VALUES
     cap_get_file a pointer to an allocated cap_t if successful, NULL
     otherwise.  The storage should be freed with a call to cap_free with the
     returned pointer as an argument when it is no longer needed.

     cap_set_file returns 0 if successful, -1 otherwise.

ERRORS
     cap_get_file:

     ENOATTR         There is no capability set associated with the file.

     EACCESS         Search permission is denied for a component of the path
                     prefix or the object exists and the process does not have
                     appropriate access rights.

     ENAMETOLONG     The pathname or one of its components is too long.

     ENOENT          The named object does not exist or path points to an
                     empty string.

     ENOMEM          allocation of the cap failed.

     ENOSYS          Capability support is not available (not installed).

     ENOTDIR         A component of the path prefix is not a directory.
     cap_set_file:

     EACCESS         Search permission is denied for a component of the path
                     prefix or the object exists and the process does not have
                     appropriate access rights.

     ENAMETOLONG     The pathname or one of its components is too long.

     ENOENT          The named object does not exist or path points to an
                     empty string.

     ENOSYS          Capability support is not available (not installed).

     ENOTDIR         A component of the path prefix is not a directory.

     EPERM           The process does not have appropriate privilege to
                     perform the operation to set the capabilities.

     EROFS           This function requires modification of a file system
                     which is currently read-only.

SEE ALSO
     capabilities(4)