CAP\_GET\_FILE(3) Linux Programmer's Manual CAP\_GET\_FILE(3) # [NAME](#NAME) cap\_get\_file, cap\_set\_file, cap\_get\_fd, cap\_set\_fd, cap\_get\_nsowner, cap\_set\_nsowner - capability manipulation on files # [SYNOPSIS](#SYNOPSIS) ``` #include 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](#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](#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](#CONFORMING_TO) These functions are specified by withdrawn POSIX.1e draft specification. # [NOTES](#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)](/man/os/libcap/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](#SEE_ALSO) [**libcap**(3)](/man/os/libcap/libcap.3), [**cap\_clear**(3)](/man/os/libcap/cap_clear.3), [**cap\_copy\_ext**(3)](/man/os/libcap/cap_copy_ext.3), [**cap\_from\_text**(3)](/man/os/libcap/cap_from_text.3), [**cap\_get\_proc**(3)](/man/os/libcap/cap_get_proc.3), [**cap\_init**(3)](/man/os/libcap/cap_init.3), [**capabilities**(7)](/man/os/libcap/capabilities.7), [**user\_namespaces**(7)](/man/os/libcap/user_namespaces.7) 2022-10-16 --- Document: cap_get_nsowner(3) from libcap 2.78-r4 (Chainguard OS) Source: https://kernel.googlesource.com/pub/scm/libs/libcap/libcap.git