1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
.\"
.\" $Id: cap_get_file.3,v 1.1.1.1 1999/04/17 22:16:31 morgan Exp $
.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
.\"
.TH CAP_GET_FILE 3 "17th May 1998" "" "Linux Programmer's Manual"
.SH NAME
cap_get_file, cap_set_file, cap_get_fd, cap_set_fd \- capability manipulation on files
.sp
.B " Note: support for file capabilities is anticipated in Linux 2.6.23+"
.SH SYNOPSIS
.B
.sp
.B #include <sys/capability.h>
.sp
.BI "cap_t cap_get_file(const char *" path_p );
.sp
.BI "int cap_set_file(const char *" path_p ", cap_t " cap_p );
.sp
.BI "cap_t cap_get_fd(int " fd );
.sp
.BI "int cap_set_fd(int " fd ", cap_t " caps );
.sp
Link with \fI-lcap\fP.
.SH DESCRIPTION
.BR cap_get_file ()
and
.BR cap_get_fd ()
allocate a capability state in working storage and set it to represent the
capability state of the pathname pointed to by
.I path_p
or the file open on descriptor
.IR 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
.BR cap_free ()
with the used
.I cap_t
as an argument.
.PP
.BR cap_set_file ()
and
.BR cap_set_fd ()
set the values for all capability flags for all capabilities for the pathname
pointed to by
.I path_p
or the file open on descriptor
.IR fd ,
with the capability state identified by
.IR cap_p .
The new capability state of the file shall be completely determined by the
contents of
.IR cap_p .
A
.IR NULL
value for
.IR 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
.B CAP_SETFCAP
capability enabled and either the effective user ID of the process must match
the file owner or the calling process must have the effective flag of the
.B CAP_FOWNER
capability set. The effects of writing the capability state to any file
type other than a regular file are undefined.
.SH "RETURN VALUE"
.BR cap_get_file ()
and
.BR cap_get_fd ()
return a non-NULL value on success, and NULL on failure.
.PP
.BR cap_set_file ()
and
.BR cap_set_fd ()
return zero on success, and \-1 on failure.
.PP
On failure,
.I errno
is set to
.BR EACCES ,
.BR EBADFD ,
.BR ENAMETOOLONG ,
.BR ENOENT ,
.BR ENOMEM ,
.BR ENOTDIR ,
.BR EPERM ,
or
.BR EROFS .
.SH "CONFORMING TO"
These functions are specified by withdrawn POSIX.1e draft specification.
.SH "SEE ALSO"
.BR cap_clear (3),
.BR cap_copy_ext (3),
.BR cap_from_text (3),
.BR cap_get_proc (3),
.BR cap_init (3),
.BR capabilities (7)
|
