1 files changed, 124 insertions, 0 deletions
diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
new file mode 100644
index 0000000..107b6d1
--- /dev/null
+++ b/doc/cap_get_file.3
@@ -0,0 +1,124 @@
+.\"
+.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
+.\"
+.TH CAP_GET_FILE 3 "2008-05-11" "" "Linux Programmer's Manual"
+.SH NAME
+cap_get_file, cap_set_file, cap_get_fd, cap_set_fd \- capability
+manipulation on files
+.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 is completely determined by the
+contents of
+.IR cap_p .
+A 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
+effective capability,
+.BR CAP_SETFCAP ,
+enabled and either the effective user ID of the process must match the
+file owner or the calling process must have the
+.B CAP_FOWNER
+flag in its effective 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 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
+.BR execve (2).
+Because the file Effective set is a single bit,
+if any capability is enabled in the Effective set of the
+.I cap_t
+given to
+.BR cap_set_file ()
+or
+.BR 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
+.I cap_t
+returned by
+.BR cap_get_file()
+and
+.BR cap_get_fd()
+will have the Effective flag enabled for each capability that has the
+Permitted or Inheritable flag enabled.
+.SH "SEE ALSO"
+.BR libcap (3),
+.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)