1CAP_GET_FILE(3)            Linux Programmer's Manual           CAP_GET_FILE(3)
2
3
4

NAME

6       cap_get_file, cap_set_file, cap_get_fd, cap_set_fd - capability manipu‐
7       lation on files
8

SYNOPSIS

10       #include <sys/capability.h>
11
12       cap_t cap_get_file(const char *path_p);
13
14       int cap_set_file(const char *path_p, cap_t cap_p);
15
16       cap_t cap_get_fd(int fd);
17
18       int cap_set_fd(int fd, cap_t caps);
19
20       uid_t cap_get_nsowner(cap_t caps);
21
22       int cap_set_nsowner(cap_t caps, uid_t rootid);
23
24       Link with -lcap.
25

DESCRIPTION

27       cap_get_file() and cap_get_fd() allocate a capability state in  working
28       storage  and  set  it to represent the capability state of the pathname
29       pointed to by path_p or the file open on descriptor  fd.   These  func‐
30       tions  return  a  pointer  to  the newly created capability state.  The
31       effects of reading the capability state from any file other than a reg‐
32       ular  file is undefined.  The caller should free any releasable memory,
33       when the capability state in working storage is no longer required,  by
34       calling cap_free() with the used cap_t as an argument.
35
36       cap_set_file() and cap_set_fd() set the values for all capability flags
37       for all capabilities for the pathname pointed to by path_p or the  file
38       open  on  descriptor fd, with the capability state identified by cap_p.
39       The new capability state of the file is completely  determined  by  the
40       contents  of  cap_p.   A  NULL value for cap_p is used to indicate that
41       capabilities for the file should be deleted.  For  these  functions  to
42       succeed,  the  calling  process  must  have  the  effective capability,
43       CAP_SETFCAP, enabled and either the effective user ID  of  the  process
44       must  match  the  file  owner  or  the  calling  process  must have the
45       CAP_FOWNER flag in its effective capability set.  The effects of  writ‐
46       ing the capability state to any file type other than a regular file are
47       undefined.
48
49       A capability set held in memory can be associated with  the  rootid  in
50       use  in  a specific namespace. It is possible to get and set this value
51       (in the  memory  copy)  with  cap_get_nsowner()  and  cap_set_nsowner()
52       respectively.  The rootid is ignored by the libcap library in all cases
53       other than when the capability is written to a file. Only if the  value
54       is  non-zero will the library attempt to include it in the written file
55       capability set.
56

RETURN VALUE

58       cap_get_file() and cap_get_fd() return a non-NULL value on success, and
59       NULL on failure.
60
61       cap_set_file() and cap_set_fd() return zero on success, and -1 on fail‐
62       ure.
63
64       On failure, errno is  set  to  EACCES,  EBADFD,  ENAMETOOLONG,  ENOENT,
65       ENOMEM, ENOTDIR, EPERM, or EROFS.
66

CONFORMING TO

68       These  functions  are  specified by withdrawn POSIX.1e draft specifica‐
69       tion.
70

NOTES

72       Support for file  capabilities  is  provided  on  Linux  since  version
73       2.6.24.
74
75       On  Linux,  the  file Effective set is a single bit.  If it is enabled,
76       then all Permitted capabilities are enabled in the Effective set of the
77       calling  process  when the file is executed; otherwise, no capabilities
78       are enabled in the process's  Effective  set  following  an  execve(2).
79       Because  the  file  Effective set is a single bit, if any capability is
80       enabled in the Effective set of the cap_t given  to  cap_set_file()  or
81       cap_set_fd(), then all capabilities whose Permitted or Inheritable flag
82       is enabled must also have the Effective flag enabled.   Conversely,  if
83       the  Effective  bit  is  enabled  on a file, then the cap_t returned by
84       cap_get_file() and cap_get_fd() will have the  Effective  flag  enabled
85       for each capability that has the Permitted or Inheritable flag enabled.
86

SEE ALSO

88       libcap(3),     cap_clear(3),     cap_copy_ext(3),     cap_from_text(3),
89       cap_get_proc(3), cap_init(3), capabilities(7)
90
91
92
93                                  2008-05-11                   CAP_GET_FILE(3)
Impressum