Debian Codegraph @

doc/old/_setfilecap.2

raw
1 .\"
2 .\" $Id: _setfilecap.2,v 1.1.1.1 1999/04/17 22:16:31 morgan Exp $
3 .\" written by Andrew Main <[email protected]>
4 .\"
5 .TH _SETFILECAP 2 "26th April 1997" "Linux 2.1" "Linux Programmer's Manual"
6 .SH NAME
7 _setfilecap, _getfilecap, _fsetfilecap, _fgetfilecap \- set/get file capabilities
8 .SH SYNOPSIS
9 .B #include <sys/capability.h>
10 .sp
11 .BI "int _setfilecap(char const *" filename ", size_t " usize ", __cap_s const *" iset ", __cap_s const *" pset ", __cap_s const *" eset );
12 .sp
13 .BI "int _getproccap(char const *" filename ", size_t " usize ", __cap_s *" iset ", __cap_s *" pset ", __cap_s *" eset );
14 .sp
15 .BI "int _fsetfilecap(int " fd ", size_t " usize ", __cap_s const *" iset ", __cap_s const *" pset ", __cap_s const *" eset );
16 .sp
17 .BI "int _fgetproccap(int " fd ", size_t " usize ", __cap_s *" iset ", __cap_s *" pset ", __cap_s *" eset );
18 .SH USAGE
19 .br
20 .B cc ... -lcap
21 .SH DESCRIPTION
22 .B _setfilecap
23 sets the specified
24 .IR filename 's
25 Inheritable, Permitted and Effective capabilities to the sets specified.
26 A NULL pointer specifies that a set should not be changed.
27 .PP
28 .B _fsetfilecap
29 does the same thing to the file referenced by file descriptor
30 .IR fd .
31 .PP
32 .B _getfilecap
33 and
34 .B _fgetfilecap
35 copy the file's capability sets into the sets provided.
36 A NULL pointer specifies that a set should not be returned.
37 .PP
38 The
39 .I usize
40 argument specifies the size of the user-space capability sets, in bytes.
41 If the kernel uses a different size internally, it will truncate or
42 zero-fill as required.
43 .PP
44 Files don't actually have a proper Effective capability set. Instead they
45 have a single-bit flag, that indicates that the set is either full or
46 empty. When setting a file's capabilities, that flag will be set if
47 and only if the Effective set specified has at least one bit set.
48 .SH "RETURN VALUE"
49 On success, zero is returned. On error, -1 is returned, and
50 .I errno
51 is set appropriately.
52 .SH ERRORS
53 .TP
54 .SB EFAULT
55 One of the capability arguments or the filename was an invalid data pointer.
56 .TP
57 .SB EPERM
58 An attempt was made to set non-empty capabilities on a file,
59 and the caller does not have the
60 .SB CAP_FSETCAP
61 capability raised.
62 .TP
63 .SB EPERM
64 An attempt was made to set capabilities on a file, and
65 the effective UID does not match the owner of the file, and the caller
66 does not have the
67 .SB CAP_FOWNER
68 capability raised.
69 .TP
70 .SB EINVAL
71 An attempt was made to set non-empty capabilities on a file
72 residing on a file system that does not support them.
73 .TP
74 .SB EROFS
75 An attempt was made to set capabilities on a file residing
76 on a read-only file system.
77 .TP
78 .SB ENAMETOOLONG
79 .I filename
80 is too long.
81 .TP
82 .SB ENOENT
83 The file specified does not exist.
84 .TP
85 .SB ENOMEM
86 Insufficient kernel memory was available.
87 .TP
88 .SB ENOTDIR
89 A component of the path prefix is not a directory.
90 .TP
91 .SB EACCES
92 Search permission is denied on a component of the path prefix.
93 .TP
94 .SB ELOOP
95 .I filename
96 contains a circular reference (via symlinks).
97 .TP
98 .SB EBADF
99 .I fd
100 is not a valid file descriptor.
101 .TP
102 .SB EIO
103 A hard error occurred while reading or writing the file system.
104 .TP
105 .SB ENOSYS
106 The POSIX.1e capability system was not configured into the kernel.
107 .SH "CONFORMING TO"
108 These system calls are specific to Linux.
109 The portable interfaces are
110 .IR cap_set_file (3),
111 .IR cap_get_file (3),
112 .IR cap_set_fd (3),
113 and
114 .IR cap_get_fd (3).
115 .SH "SEE ALSO"
116 .IR _setproccap (2).
117