Movatterモバイル変換

cap_get_file(3) — Linux manual page

CAP_GET_FILE(3)         Linux Programmer's ManualCAP_GET_FILE(3)

NAME        top

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

SYNOPSIS        top

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

cap_get_file() andcap_get_fd() allocate a capability state in       working storage and set it to represent the capability state of       the pathname pointed to bypath_p or the file open on descriptorfd.  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 callingcap_free() with       the usedcap_t as an argument.cap_set_file() andcap_set_fd() set the values for all capability       flags for all capabilities for the pathname pointed to bypath_p       or the file open on descriptorfd, with the capability state       identified bycap_p.  The new capability state of the file is       completely determined by the contents ofcap_p.  A NULL value forcap_p is used to indicate that capabilities for the file should be       deleted.  For these functions to succeed, the calling process must       have theCAP_SETFCAPcapability in its effective set and either       the effective user ID of the process must match the file owner or       the calling process must have theCAP_FOWNERcapability 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) withcap_get_nsowner() andcap_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        top

cap_get_file() andcap_get_fd() return a non-NULL value on       success, and NULL on failure.cap_set_file() andcap_set_fd() return zero on success, and -1 on       failure.       On failure,errno is set toEACCES,EBADFD,ENAMETOOLONG,ENOENT,ENOMEM,ENOTDIR,EPERM, orEROFS.

CONFORMING TO        top

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

NOTES        top

       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 anexecve(2).  Because the file Effective set is a       single bit, if any capability is enabled in the Effective set of       thecap_t given tocap_set_file() orcap_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 thecap_t returned bycap_get_file()andcap_get_fd()will have the Effective flag       enabled for each capability that has the Permitted or Inheritable       flag enabled.

SEE ALSO        top

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

COLOPHON        top

       This page is part of thelibcap (capabilities commands and       library) project.  Information about the project can be found at       ⟨https://git.kernel.org/pub/scm/libs/libcap/libcap.git/⟩.  If you       have a bug report for this manual page, send it to       morgan@kernel.org (please put "libcap" in the Subject line).  This       page was obtained from the project's upstream Git repository       ⟨https://git.kernel.org/pub/scm/libs/libcap/libcap.git/⟩ on       2025-08-11.  (At that time, the date of the most recent commit       that was found in the repository was 2025-08-10.)  If you discover       any rendering problems in this HTML version of the page, or you       believe there is a better or more up-to-date source for the page,       or you have corrections or improvements to the information in this       COLOPHON (which isnot part of the original manual page), send a       mail to man-pages@man7.org                                2022-10-16CAP_GET_FILE(3)

Pages that refer to this page:cap_clear(3), cap_copy_ext(3), cap_from_text(3), cap_get_proc(3), cap_init(3), libcap(3), capabilities(7), getcap(8), setcap(8)

HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH.