# cap_get_file

## NAME



           cap_get_file, cap_set_file, cap_get_fd, cap_set_fd,
           cap_get_nsowner, cap_set_nsowner - 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);
           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 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.
    


## 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.
    


* * *