Imported Upstream version 2.22upstream/2.22

39 files changed, 1551 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..7d1f347
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,50 @@
+#
+# Makefile for libcap documentation
+#
+
+topdir=$(shell pwd)/..
+include $(topdir)/Make.Rules
+
+MAN1S = capsh.1
+MAN3S = cap_init.3 cap_free.3 cap_dup.3 \
+	cap_clear.3 cap_clear_flag.3 cap_get_flag.3 cap_set_flag.3 \
+	cap_compare.3 cap_get_proc.3 cap_get_pid.3 cap_set_proc.3 \
+	cap_get_file.3 cap_get_fd.3 cap_set_file.3 cap_set_fd.3 \
+	cap_copy_ext.3 cap_size.3 cap_copy_int.3 \
+	cap_from_text.3 cap_to_text.3 cap_from_name.3 cap_to_name.3 \
+	capsetp.3 capgetp.3 libcap.3 \
+	cap_get_bound.3 cap_drop_bound.3
+MAN8S = getcap.8 setcap.8
+
+MANS = $(MAN1S) $(MAN3S) $(MAN8S)
+
+all: $(MANS)
+
+.PHONY: html
+html:
+	mkdir -p html
+	for man in $(MANS) ; \
+	do \
+		egrep '^\.so man' $$man > /dev/null || \
+		groff -man -Thtml $$man > html/$$man.html ; \
+	done
+
+install:
+	mkdir -p -m 755 $(MANDIR)/man1 $(MANDIR)/man3 $(MANDIR)/man8
+	for man in \
+		$(MANDIR)/man1 $(MAN1S) \
+		$(MANDIR)/man3 $(MAN3S) \
+		$(MANDIR)/man8 $(MAN8S) \
+		; \
+	do \
+		case $$man in \
+		/*)	sub=$$man ; continue ;; \
+		esac; \
+		install -m 644 $$man $$sub ; \
+	done
+
+clean:
+	$(LOCALCLEAN)
+	rm -rf html
+
+
diff --git a/doc/cap_clear.3 b/doc/cap_clear.3
new file mode 100644
index 0000000..48f5cc0
--- /dev/null
+++ b/doc/cap_clear.3
@@ -0,0 +1,133 @@
+.TH CAP_CLEAR 3 "2008-05-11" "" "Linux Programmer's Manual"
+.SH NAME
+cap_clear, cap_clear_flag, cap_get_flag, cap_set_flag, cap_compare \- capability data object manipulation
+.SH SYNOPSIS
+.nf
+.B #include <sys/capability.h>
+.sp
+.BI "int cap_clear(cap_t " cap_p );
+.sp
+.BI "int cap_clear_flag(cap_t " cap_p ", cap_flag_t " flag ");"
+.sp
+.BI "int cap_get_flag(cap_t " cap_p ", cap_value_t " cap ,
+.BI "                 cap_flag_t " flag ", cap_flag_value_t *" value_p ");"
+.sp
+.BI "int cap_set_flag(cap_t " cap_p ", cap_flag_t " flag ", int " ncap ,
+.BI "                 const cap_value_t *" caps \
+", cap_flag_value_t " value ");"
+.sp
+.BI "int cap_compare(cap_t " cap_a ", cap_t " cap_b ");"
+.sp
+Link with \fI-lcap\fP.
+.fi
+.SH DESCRIPTION
+These functions work on a capability state held in working storage.
+A
+.I cap_t
+holds information about the capabilities in each of the three sets,
+Permitted, Inheritable, and Effective.
+Each capability in a set may be clear (disabled, 0) or set (enabled, 1).
+.PP
+These functions work with the following data types:
+.TP 18
+.I cap_value_t
+identifies a capability, such as
+.BR CAP_CHOWN .
+.TP
+.I cap_flag_t
+identifies one of the three flags associated with a capability
+(i.e., it identifies one of the three capability sets).
+Valid values for this type are
+.BR CAP_EFFECTIVE ,
+.B CAP_INHERITABLE
+or
+.BR CAP_PERMITTED .
+.TP
+.I cap_flag_value_t
+identifies the setting of a particular capability flag
+(i.e, the value of a capability in a set).
+Valid values for this type are
+.B CAP_CLEAR
+(0) or
+.B CAP_SET
+(1).
+.PP
+.BR cap_clear ()
+initializes the capability state in working storage identified by
+.I cap_p
+so that all capability flags are cleared.
+.PP
+.BR cap_clear_flag ()
+clears all of the capabilities of the specified capability flag,
+.IR flag .
+.PP
+.BR cap_get_flag ()
+obtains the current value of the capability flag,
+.IR flag ,
+of the capability,
+.IR cap ,
+from the capability state identified by
+.I cap_p
+and places it in the location pointed to by
+.IR value_p .
+.PP
+.BR cap_set_flag ()
+sets the flag,
+.IR flag ,
+of each capability in the array
+.I caps
+in the capability state identified by
+.I cap_p
+to
+.IR value .
+The argument,
+.IR ncap ,
+is used to specify the number of capabilities in the array,
+.IR caps .
+.PP
+.BR cap_compare ()
+compares two full capability sets and, in the spirit of
+.BR memcmp (),
+returns zero if the two capability sets are identical. A positive
+return value,
+.BR status ,
+indicates there is a difference between them. The
+returned value carries further information about which of three sets,
+.I cap_flag_t
+.BR flag ,
+differ. Specifically, the macro
+.B CAP_DIFFERS
+.RI ( status ", " flag )
+evaluates to non-zero if the returned status differs in its
+.I flag
+components.
+.SH "RETURN VALUE"
+.BR cap_clear (),
+.BR cap_clear_flag (),
+.BR cap_get_flag ()
+.BR cap_set_flag ()
+and
+.BR cap_compare ()
+return zero on success, and \-1 on failure. Other return values for
+.BR cap_compare ()
+are described above.
+.PP
+On failure,
+.I errno
+is set to 
+.BR EINVAL ,
+indicating that one of the arguments is invalid.
+.SH "CONFORMING TO"
+These functions are as per the withdrawn POSIX.1e draft specification.
+.BR cap_clear_flag ()
+and
+.BR cap_compare ()
+are Linux extensions.
+.SH "SEE ALSO"
+.BR libcap (3),
+.BR cap_copy_ext (3),
+.BR cap_from_text (3),
+.BR cap_get_file (3),
+.BR cap_get_proc (3),
+.BR cap_init (3),
+.BR capabilities (7)
diff --git a/doc/cap_clear_flag.3 b/doc/cap_clear_flag.3
new file mode 100644
index 0000000..db506c6
--- /dev/null
+++ b/doc/cap_clear_flag.3
@@ -0,0 +1 @@
+.so man3/cap_clear.3
diff --git a/doc/cap_compare.3 b/doc/cap_compare.3
new file mode 100644
index 0000000..db506c6
--- /dev/null
+++ b/doc/cap_compare.3
@@ -0,0 +1 @@
+.so man3/cap_clear.3
diff --git a/doc/cap_copy_ext.3 b/doc/cap_copy_ext.3
new file mode 100644
index 0000000..61d9381
--- /dev/null
+++ b/doc/cap_copy_ext.3
@@ -0,0 +1,104 @@
+.TH CAP_COPY_EXT 3 "2008-05-11" "" "Linux Programmer's Manual"
+.SH NAME
+cap_copy_ext, cap_size, cap_copy_int \- capability state
+external representation translation
+.SH SYNOPSIS
+.B #include <sys/capability.h>
+.sp
+.BI "ssize_t cap_size(cap_t " cap_p );
+.sp
+.BI "ssize_t cap_copy_ext(void *" ext_p ", cap_t " cap_p ", ssize_t " size );
+.sp
+.BI "cap_t cap_copy_int(const void *" ext_p );
+.sp
+Link with \fI-lcap\fP.
+.SH DESCRIPTION
+These functions translate between internal and external
+representations of a capability state.  The external representation is
+an exportable, contiguous, persistent representation of a capability
+state in user-managed space.  The internal representation is managed
+by the capability functions in working storage.
+.PP
+.BR cap_size ()
+returns the total length (in bytes) that the capability state in working
+storage identified by
+.I cap_p
+would require when converted by
+.BR cap_copy_ext ().
+This function is used primarily to determine the amount of buffer space that
+must be provided to the
+.BR cap_copy_ext ()
+function in order to hold the capability data record created from
+.IR cap_p .
+.PP
+.BR cap_copy_ext ()
+copies a capability state in working storage, identified by
+.IR cap_p ,
+from system managed space to user-managed space (pointed to by
+.IR ext_p )
+and returns the length of the resulting data record.  The size parameter
+represents the maximum size, in bytes, of the resulting data record.  The
+.BR cap_copy_ext ()
+function will do any conversions necessary to convert the capability
+state from the undefined internal format to an exportable, contiguous,
+persistent data record.  It is the responsibility of the user to
+allocate a buffer large enough to hold the copied data.  The buffer
+length required to hold the copied data may be obtained by a call to
+the
+.BR cap_size ()
+function.
+.PP
+.BR cap_copy_int ()
+copies a capability state from a capability data record in user-managed
+space to a new capability state in working storage, allocating any
+memory necessary, and returning a pointer to the newly created capability
+state.  The function initializes the capability state and then copies
+the capability state from the record pointed to by
+.I ext_p
+into the capability state, converting, if necessary, the data from a
+contiguous, persistent format to an undefined, internal format.  Once
+copied into internal format, the object can be manipulated by the capability
+state manipulation functions (see
+.BR cap_clear (3)).
+Note that the record pointed to by
+.I ext_p
+must have been obtained from a previous, successful call to
+.BR cap_copy_ext ()
+for this function to work successfully.  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
+.I cap_t
+as an argument.
+.SH "RETURN VALUE"
+.BR cap_size ()
+returns the length required to hold a capability data record on success,
+and -1 on failure.
+.PP
+.BR cap_copy_ext ()
+returns the number of bytes placed in the user managed space pointed to by
+.I ext_p 
+on success, and -1 on failure.
+.PP
+.BR cap_copy_int ()
+returns a pointer to the newly created capability state in working storage
+on success, and NULL on failure.
+.PP
+On failure,
+.BR errno
+is set to
+.BR EINVAL ,
+.BR ENOMEM ,
+or
+.BR ERANGE .
+.SH "CONFORMING TO"
+These functions are specified in the withdrawn POSIX.1e draft specification.
+.SH "SEE ALSO"
+.BR libcap (3),
+.BR cap_clear (3),
+.BR cap_from_text (3),
+.BR cap_get_file (3),
+.BR cap_get_proc (3),
+.BR cap_init (3),
+.BR capabilities (7)
diff --git a/doc/cap_copy_int.3 b/doc/cap_copy_int.3
new file mode 100644
index 0000000..2e6e89c
--- /dev/null
+++ b/doc/cap_copy_int.3
@@ -0,0 +1 @@
+.so man3/cap_copy_ext.3
diff --git a/doc/cap_drop_bound.3 b/doc/cap_drop_bound.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/cap_drop_bound.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/cap_dup.3 b/doc/cap_dup.3
new file mode 100644
index 0000000..7810cff
--- /dev/null
+++ b/doc/cap_dup.3
@@ -0,0 +1 @@
+.so man3/cap_init.3
diff --git a/doc/cap_free.3 b/doc/cap_free.3
new file mode 100644
index 0000000..7810cff
--- /dev/null
+++ b/doc/cap_free.3
@@ -0,0 +1 @@
+.so man3/cap_init.3
diff --git a/doc/cap_from_name.3 b/doc/cap_from_name.3
new file mode 100644
index 0000000..83ec8b5
--- /dev/null
+++ b/doc/cap_from_name.3
@@ -0,0 +1 @@
+.so man3/cap_from_text.3
diff --git a/doc/cap_from_text.3 b/doc/cap_from_text.3
new file mode 100644
index 0000000..ccf7d95
--- /dev/null
+++ b/doc/cap_from_text.3
@@ -0,0 +1,233 @@
+.\"
+.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
+.\"
+.TH CAP_FROM_TEXT 3 "2008-05-10" "" "Linux Programmer's Manual"
+.SH NAME
+cap_from_text, cap_to_text, cap_to_name, cap_from_name \- capability
+state textual representation translation
+.SH SYNOPSIS
+.B #include <sys/capability.h>
+.sp
+.BI "cap_t cap_from_text(const char *" buf_p );
+.sp
+.BI "char *cap_to_text(cap_t " caps ", ssize_t *" length_p );
+.sp
+.BI "int cap_from_name(const char *" name ", cap_value_t *" cap_p );
+.sp
+.BI "char *cap_to_name(cap_value_t " cap );
+.sp
+Link with \fI-lcap\fP.
+.SH DESCRIPTION
+These functions translate a capability state between
+an internal representation and a textual one.
+The internal representation is managed by the capability
+functions in working storage. The textual representation is a structured,
+human-readable string suitable for display.
+.PP
+.BR cap_from_text ()
+allocates and initializes a capability state in working storage. It
+then sets the contents of this newly created capability state to the
+state represented by a human-readable, nul-terminated character
+string pointed to by
+.IR buf_p .
+It returns a pointer to the newly created capability state.
+When the capability state in working storage is no longer required,
+the caller should free any releasable memory
+by calling
+.BR cap_free ()
+with
+.I cap_t
+as an argument.  The function returns an error if it cannot parse the
+contents of the string pointed to by
+.I buf_p
+or does not recognize any
+.I capability_name
+or flag character as valid.  The function also returns an error if any flag
+is both set and cleared within a single clause.
+.PP
+.BR cap_to_text ()
+converts the capability state in working storage identified by
+.I cap_p
+into a nul-terminated human-readable string.  This function allocates
+any memory necessary to contain the string, and returns a pointer to
+the string.  If the pointer
+.I len_p
+is not NULL,
+the function shall also return the full length of the string (not including
+the nul terminator) in the location pointed to by
+.IR len_p .
+The capability state in working storage, identified by
+.IR cap_p ,
+is completely represented in the character string.
+When the capability state in working storage is no longer required,
+the caller should free any releasable memory by calling
+.BR cap_free ()
+with the returned string pointer as an argument.
+.PP
+.BR cap_from_name ()
+converts a text representation of a capability, such as "cap_chown",
+to its numerical representation
+.RB ( CAP_CHOWN=0 ),
+writing the decoded value into
+.IR *cap_p .
+If
+.I cap_p
+is NULL
+no result is written, but the return code of the function indicates
+whether or not the specified capability can be represented by the
+library.
+.PP
+.BR cap_to_name ()
+converts a capability index value,
+.IR cap ,
+to a libcap-allocated textual string. This string should be
+deallocated with
+.BR cap_free ().
+.SH "TEXTUAL REPRESENTATION"
+A textual representation of capability sets consists of one or more
+whitespace-separated
+.IR clauses .
+Each clause specifies some operations on a capability set; the set
+starts out with all capabilities lowered, and the meaning of the
+string is the state of the capability set after all the clauses have
+been applied in order.
+.PP
+Each clause consists of a list of comma-separated capability names
+(or the word
+.RB ` all '),
+followed by an
+.IR action-list .
+An action-list consists of a sequence of
+.I operator flag
+pairs.  Legal operators are:
+.RB ` = "', '" + "', and `" - "'."
+Legal flags are:
+.RB ` e "', `" i "', and `" p "'."
+These flags are case-sensitive and specify the Effective, Inheritable
+and Permitted sets respectively.
+.PP
+In the capability name lists, all names are case-insensitive.  The
+special name
+.RB ` all '
+specifies all capabilities; it is equivalent to a list naming every
+capability individually.
+.PP
+Unnamed capabilities can also be specified by number. This feature
+ensures that libcap can support capabilities that were not allocated
+at the time libcap was compiled. However, generally upgrading libcap
+will add names for recently allocated capabilities.
+.PP
+The
+.RB ` = '
+operator indicates that the listed capabilities are first reset in
+all three capability sets.  The subsequent flags (which are optional
+when associated with this operator) indicate that the listed
+capabilities for the corresponding set are to be raised.  For example:
+"all=p" means lower every capability in the Effective and Inheritable
+sets but raise all of the Permitted capabilities;
+or, "cap_fowner=ep" means raise the Effective and Permitted
+override-file-ownership capability, while lowering this Inheritable
+capability.
+.PP
+In the case that the leading operator is
+.RB ` = ',
+and no list of capabilities is provided, the action-list is assumed to
+refer to `all' capabilities.  For example, the following three
+clauses are equivalent to each other (and indicate a completely empty
+capability set): "all="; "="; "cap_chown,<every-other-capability>=".
+.PP
+The operators, `+' and `-' both require an explicit preceding
+capability list and one or more explicit trailing flags.  The `+'
+operator will raise all of the listed capabilities in the flagged
+capability sets.  The `-' operator will lower all of the listed
+capabilities in the flagged capability sets.  For example:
+"all+p" will raise all of the Permitted capabilities; "cap_fowner+p-i"
+will raise the override-file-ownership capability in the Permitted
+capability set and lower this Inheritable capability;
+"cap_fowner+pe-i" and "cap_fowner=+pe" are equivalent.
+.SH "RETURN VALUE"
+.BR cap_from_text (),
+.BR cap_to_text ()
+and
+.BR cap_to_name ()
+return a non-NULL value on success, and NULL on failure.
+.BR cap_from_name ()
+returns 0 for success, and -1 on failure (unknown capability).
+.PP
+On failure,
+.I errno
+is set to 
+.BR EINVAL ,
+or 
+.BR ENOMEM .
+.SH "CONFORMING TO"
+.BR cap_from_text ()
+and
+.BR cap_to_text ()
+are specified by the withdrawn POSIX.1e draft specification.
+.BR cap_from_name ()
+and
+.BR cap_to_name ()
+are Linux extensions.
+.SH EXAMPLE
+The example program below demonstrates the use of
+.BR cap_from_text ()
+and
+.BR cap_to_text ().
+The following shell session shows a some example runs:
+.in +4n
+.nf
+
+$ ./a.out "cap_chown=p cap_chown+e"
+caps_to_text() returned "= cap_chown+ep"
+$ ./a.out "all=pe cap_chown-e cap_kill-pe"
+caps_to_text() returned "=ep cap_chown-e cap_kill-ep"
+
+.fi
+.in
+The source code of the program is as follows:
+.nf
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <sys/capability.h>
+
+#define handle_error(msg) \\
+    do { perror(msg); exit(EXIT_FAILURE); } while (0)
+
+int
+main(int argc, char *argv[])
+{
+    cap_t caps;
+    char *txt_caps;
+
+    if (argc != 2) {
+        fprintf(stderr, "%s <textual\-cap\-set>\\n", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+
+    caps = cap_from_text(argv[1]);
+    if (caps == NULL)
+        handle_error("cap_from_text");
+
+    txt_caps = cap_to_text(caps, NULL);
+    if (txt_caps == NULL)
+        handle_error("cap_to_text");
+
+    printf("caps_to_text() returned \\"%s\\"\\n", txt_caps);
+
+    if (cap_free(txt_caps) != 0 || cap_free(caps) != 0)
+        handle_error("cap_free");
+
+    exit(EXIT_SUCCESS);
+}
+.fi
+.SH "SEE ALSO"
+.BR libcap (3),
+.BR cap_clear (3),
+.BR cap_compare (3),
+.BR cap_copy_ext (3),
+.BR cap_get_file (3),
+.BR cap_get_proc (3),
+.BR cap_init (3),
+.BR capabilities (7)
diff --git a/doc/cap_get_bound.3 b/doc/cap_get_bound.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/cap_get_bound.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/cap_get_fd.3 b/doc/cap_get_fd.3
new file mode 100644
index 0000000..3970c34
--- /dev/null
+++ b/doc/cap_get_fd.3
@@ -0,0 +1 @@
+.so man3/cap_get_file.3
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)
diff --git a/doc/cap_get_flag.3 b/doc/cap_get_flag.3
new file mode 100644
index 0000000..db506c6
--- /dev/null
+++ b/doc/cap_get_flag.3
@@ -0,0 +1 @@
+.so man3/cap_clear.3
diff --git a/doc/cap_get_pid.3 b/doc/cap_get_pid.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/cap_get_pid.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/cap_get_proc.3 b/doc/cap_get_proc.3
new file mode 100644
index 0000000..123ab3d
--- /dev/null
+++ b/doc/cap_get_proc.3
@@ -0,0 +1,204 @@
+.\"
+.\" $Id: cap_get_proc.3,v 1.1.1.1 1999/04/17 22:16:31 morgan Exp $
+.\"
+.TH CAP_GET_PROC 3 "2008-05-11" "" "Linux Programmer's Manual"
+.SH NAME
+cap_get_proc, cap_set_proc, capgetp, cap_get_bound, cap_drop_bound \-
+capability manipulation on processes
+.SH SYNOPSIS
+.B #include <sys/capability.h>
+.sp
+.B "cap_t cap_get_proc(void);"
+.sp
+.BI "int cap_set_proc(cap_t " cap_p );
+.sp
+.BI "int cap_get_bound(cap_value_t " cap );
+.sp
+.BI "CAP_IS_SUPPORTED(cap_value_t " cap );
+.sp
+.BI "int cap_drop_bound(cap_value_t " cap );
+.sp
+.B #include <sys/types.h>
+.sp
+.BI "cap_t cap_get_pid(pid_t " pid );
+.sp
+Link with \fI-lcap\fP.
+.SH DESCRIPTION
+.BR cap_get_proc ()
+allocates a capability state in working storage, sets its state to
+that of the calling process, and returns a pointer to this newly
+created capability state.  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
+.I cap_t
+as an argument.
+.PP
+.BR cap_set_proc ()
+sets the values for all capability flags for all capabilities to the
+capability state identified by
+.IR cap_p .
+The new capability state of the process will be completely determined by
+the contents of
+.I cap_p
+upon successful return from this function.  If any flag in
+.I cap_p
+is set for any capability not currently permitted for the calling process,
+the function will fail, and the capability state of the process will remain
+unchanged.
+.PP
+.BR cap_get_pid ()
+returns
+.IR cap_d ,
+see 
+.BR cap_init (3),
+with the process capabilities of the process indicated by
+.IR pid .
+This information can also be obtained from the
+.I /proc/<pid>/status
+file.
+.PP
+.BR cap_get_bound ()
+with a
+.I  cap
+as an argument returns the current value of this bounding set
+capability flag in effect for the current process. This operation is
+unpriveged. Note, a macro function
+.BI "CAP_IS_SUPPORTED(cap_value_t " cap )
+is provided that evaluates to true (1) if the system supports the
+specified capability,
+.IR cap .
+If the system does not support the capability, this function returns
+0. This macro works by testing for an error condition with
+.BR cap_get_bound ().
+.PP
+.BR cap_drop_bound ()
+can be used to lower the specified bounding set capability,
+.BR cap ,
+To complete successfully, the prevailing
+.I effective
+capability set must have a raised
+.BR CAP_SETPCAP .
+.SH "RETURN VALUE"
+The functions
+.BR cap_get_proc ()
+and
+.BR cap_get_pid ()
+return a non-NULL value on success, and NULL on failure.
+.PP
+The function
+.BR cap_get_bound ()
+returns -1 if the requested capability is unknown, otherwise the
+return value reflects the current state of that capability in the
+prevailing bounding set. Note, a macro function,
+.PP
+The functions
+.BR cap_set_proc ()
+and
+.BR cap_drop_bound ()
+return zero for success, and \-1 on failure.
+.PP
+On failure,
+.I errno
+is set to
+.BR EINVAL ,
+.BR EPERM,
+or
+.BR ENOMEM .
+.SH "CONFORMING TO"
+.BR cap_set_proc ()
+and
+.BR cap_get_proc ()
+are specified in the withdrawn POSIX.1e draft specification.
+.BR cap_get_pid ()
+is a Linux extension.
+.SH "NOTES"
+The library also supports the deprecated functions:
+.PP
+.BI "int capgetp(pid_t " pid ", cap_t " cap_d );
+.PP
+.BI "int capsetp(pid_t " pid ", cap_t " cap_d );
+.PP
+.BR capgetp ()
+attempts to obtain the capabilities of some other process; storing the
+capabilities in a pre-allocated
+.IR cap_d . See
+.BR cap_init ()
+for information on allocating an empty capability set. This function,
+.BR capgetp (),
+is deprecated, you should use
+.BR cap_get_pid ().
+.PP
+.BR capsetp ()
+attempts to set the capabilities of some other process(es),
+.IR pid . 
+If
+.I pid
+is positive it refers to a specific process;  if it is zero, it refers
+to the current process; -1 refers to all processes other than the
+current process and process '1' (typically 
+.BR init (8));
+other negative values refer to the
+.I -pid
+process group.  In order to use this function, the kernel must support
+it and the current process must have
+.B CAP_SETPCAP
+raised in its Effective capability set. The capabilities set in the
+target process(es) are those contained in
+.IR cap_d .
+Kernels that support filesystem capabilities redefine the semantics of
+.B CAP_SETPCAP
+and on such systems this function will always fail for any target not
+equal to the current process.
+.BR capsetp ()
+returns zero for success, and \-1 on failure.
+
+Where supported by the kernel, the function
+.BR capsetp ()
+should be used with care.  It existed, primarily, to overcome an early
+lack of support for capabilities in the filesystems supported by
+Linux.  Note that, by default, the only processes that have
+.B CAP_SETPCAP
+available to them are processes started as a kernel thread.
+(Typically this includes
+.BR init (8),
+kflushd and kswapd). You will need to recompile the kernel to modify
+this default.
+.SH EXAMPLE
+The code segment below raises the
+.B CAP_FOWNER
+and
+.B CAP_SETFCAP
+effective capabilities for the caller:
+.nf
+
+    cap_t caps;
+    cap_value_t cap_list[2];
+
+    if (!CAP_IS_SUPPORTED(CAP_SETFCAP))
+        /* handle error */
+
+    caps = cap_get_proc();
+    if (caps == NULL)
+        /* handle error */;
+
+    cap_list[0] = CAP_FOWNER;
+    cap_list[1] = CAP_SETFCAP;
+    if (cap_set_flag(caps, CAP_EFFECTIVE, 2, cap_list, CAP_SET) == -1)
+        /* handle error */;
+
+    if (cap_set_proc(caps) == -1)
+        /* handle error */;
+
+    if (cap_free(caps) == -1)
+        /* handle error */;
+.fi
+.SH "SEE ALSO"
+.BR libcap (3),
+.BR cap_clear (3),
+.BR cap_copy_ext (3),
+.BR cap_from_text (3),
+.BR cap_get_file (3),
+.BR cap_init (3),
+.BR capabilities (7)
diff --git a/doc/cap_init.3 b/doc/cap_init.3
new file mode 100644
index 0000000..f198f63
--- /dev/null
+++ b/doc/cap_init.3
@@ -0,0 +1,86 @@
+.\"
+.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
+.\"
+.TH CAP_INIT 3 "2008-05-11" "" "Linux Programmer's Manual"
+.SH NAME
+cap_init, cap_free, cap_dup \- capability data object storage management
+.SH SYNOPSIS
+.B #include <sys/capability.h>
+.sp
+.B cap_t cap_init(void);
+.sp
+.BI "int cap_free(void *" obj_d );
+.sp
+.BI "cap_t cap_dup(cap_t " cap_p );
+.sp
+Link with \fI-lcap\fP.
+.SH DESCRIPTION
+The capabilities associated with a file or process are never edited
+directly.  Instead, working storage is allocated to contain a
+representation of the capability state.  Capabilities are edited and
+manipulated only within this working storage area.  Once editing of
+the capability state is complete, the updated capability state is used
+to replace the capability state associated with the file or process.
+.PP
+.BR cap_init ()
+creates a capability state in working storage and returns a pointer to
+the capability state.  The initial value of all flags are cleared.  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 
+.I cap_t
+as an argument.
+.PP
+.BR cap_free ()
+liberates any releasable memory that has been allocated to the
+capability state identified by
+.IR obj_d .
+The
+.I obj_d
+argument may identify either a
+.I cap_t
+entity, or a
+.I char *
+entity allocated by the
+.BR cap_to_text ()
+function.
+.PP
+.BR cap_dup ()
+returns a duplicate capability state in working storage given by the
+source object
+.IR cap_p , 
+allocating any memory necessary, and returning a
+pointer to the newly created capability state.  Once duplicated, no
+operation on either capability state affects the other in any way.
+When the duplicated capability state in working storage is no longer required,
+the caller should free any releasable memory by calling
+.BR cap_free ()
+with the 
+.I cap_t
+as an argument.
+.SH "RETURN VALUE"
+.BR cap_init ()
+and
+.BR cap_dup ()
+return a non-NULL value on success, and NULL on failure.
+.PP
+.BR cap_free ()
+returns zero on success, and \-1 on failure.
+.PP
+On failure,
+.I errno
+is set to
+.BR EINVAL
+or
+.BR ENOMEM .
+.SH "CONFORMING TO"
+These functions are specified in the withdrawn POSIX.1e draft specification.
+.SH "SEE ALSO"
+.BR libcap (3),
+.BR cap_clear (3),
+.BR cap_copy_ext (3),
+.BR cap_from_text (3),
+.BR cap_get_file (3),
+.BR cap_get_proc (3),
+.BR capabilities (7)
diff --git a/doc/cap_set_fd.3 b/doc/cap_set_fd.3
new file mode 100644
index 0000000..3970c34
--- /dev/null
+++ b/doc/cap_set_fd.3
@@ -0,0 +1 @@
+.so man3/cap_get_file.3
diff --git a/doc/cap_set_file.3 b/doc/cap_set_file.3
new file mode 100644
index 0000000..3970c34
--- /dev/null
+++ b/doc/cap_set_file.3
@@ -0,0 +1 @@
+.so man3/cap_get_file.3
diff --git a/doc/cap_set_flag.3 b/doc/cap_set_flag.3
new file mode 100644
index 0000000..db506c6
--- /dev/null
+++ b/doc/cap_set_flag.3
@@ -0,0 +1 @@
+.so man3/cap_clear.3
diff --git a/doc/cap_set_proc.3 b/doc/cap_set_proc.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/cap_set_proc.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/cap_size.3 b/doc/cap_size.3
new file mode 100644
index 0000000..2e6e89c
--- /dev/null
+++ b/doc/cap_size.3
@@ -0,0 +1 @@
+.so man3/cap_copy_ext.3
diff --git a/doc/cap_to_name.3 b/doc/cap_to_name.3
new file mode 100644
index 0000000..83ec8b5
--- /dev/null
+++ b/doc/cap_to_name.3
@@ -0,0 +1 @@
+.so man3/cap_from_text.3
diff --git a/doc/cap_to_text.3 b/doc/cap_to_text.3
new file mode 100644
index 0000000..83ec8b5
--- /dev/null
+++ b/doc/cap_to_text.3
@@ -0,0 +1 @@
+.so man3/cap_from_text.3
diff --git a/doc/capability.notes b/doc/capability.notes
new file mode 100644
index 0000000..b1e5245
--- /dev/null
+++ b/doc/capability.notes
@@ -0,0 +1,58 @@
+Overview
+--------
+
+As of Linux 2.2.0, the power of the superuser has been partitioned
+into a set of discrete capabilities (in other places, these
+capabilities are know as privileges).
+
+The contents of the libcap package are a library and a number of
+simple programs that are intended to show how an application/daemon
+can be protected (with wrappers) or rewritten to take advantage of
+this fine grained approach to constraining the danger to your system
+from programs running as 'root'.
+
+Notes on securing your system
+-----------------------------
+
+Adopting a role approach to system security:
+
+changing all of the system binaries and directories to be owned by
+some user that cannot log on. You might like to create a user with
+the name 'system' who's account is locked with a '*' password. This
+user can be made the owner of all of the system directories on your
+system and critical system binaries too.
+
+Why is this a good idea? In a simple case, the CAP_FUSER capabilty is
+required for the superuser to delete files owned by a non-root user in
+a 'sticky-bit' protected non-root owned directory. Thus, the sticky
+bit can help you protect the /lib/ directory from an compromized
+daemon where the directory and the files it contains are owned by the
+system user. It can be protected by using a wrapper like execcap to
+ensure that the daemon is not running with the CAP_FUSER capability...
+
+
+Limiting the damage:
+
+If your daemon only needs to be setuid-root in order to bind to a low
+numbered port. You should restrict it to only having access to the
+CAP_NET_BIND_SERVICE capability. Coupled with not having any files on
+the system owned by root, it becomes significantly harder for such a
+daemon to damage your system.
+
+Note, you should think of this kind of trick as making things harder
+for a potential attacker to exploit a hole in a daemon of this
+type. Being able to bind to any privileged port is still a formidable
+privilege and can lead to difficult but 'interesting' man in the
+middle attacks -- hijack the telnet port for example and masquerade as
+the login program... Collecting passwords for another day.
+
+
+The /proc/ filesystem:
+
+This Linux-specific directory tree holds most of the state of the
+system in a form that can sometimes be manipulated by file
+read/writes.  Take care to ensure that the filesystem is not mounted
+with uid=0, since root (with no capabilities) would still be able to
+read sensitive files in the /proc/ tree - kcore for example.
+
+[Patch is available for 2.2.1 - I just wrote it!]
diff --git a/doc/capgetp.3 b/doc/capgetp.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/capgetp.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/capsetp.3 b/doc/capsetp.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/capsetp.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/capsh.1 b/doc/capsh.1
new file mode 100644
index 0000000..e68df2c
--- /dev/null
+++ b/doc/capsh.1
@@ -0,0 +1,173 @@
+.\"
+.\" capsh.1 Man page added 2009-12-23 Andrew G. Morgan <morgan@kernel.org>
+.\"
+.TH CAPSH 1 "2011-04-24" "libcap 2" "User Commands"
+.SH NAME
+capsh \- capability shell wrapper
+.SH SYNOPSIS
+.B capsh
+[\fIOPTION\fR]...
+.SH DESCRIPTION
+Linux capability support and use can be explored and constrained with
+this tool. This tool provides a handy wrapper for certain types
+of capability testing and environment creation. It also provides some
+debugging features useful for summarizing capability state.
+.SH OPTIONS
+The tool takes a number of optional arguments, acting on them in the
+order they are provided. They are as follows:
+.TP 22
+.B --print
+Display prevailing capability and related state.
+.TP
+.BI -- " [args]"
+Execute
+.B /bin/bash
+with trailing arguments. Note, you can use
+.B -c 'command to execute'
+for specific commands.
+.TP
+.B ==
+Execute
+.B capsh
+again with remaining arguments. Useful for testing
+.BR exec ()
+behavior.
+.TP
+.BI --caps= cap-set
+Set the prevailing process capabilities to those specified by
+.IR cap-set .
+Where
+.I cap-set
+is a text-representation of capability state as per
+.BR cap_from_text (3).
+.TP
+.BI --drop= cap-list
+Remove the listed capabilities from the prevailing bounding set. The
+capabilites are a comma separated list of capabilities as recognized
+by the
+.BR cap_from_name (3)
+function. Use of this feature requires that the capsh program is
+operating with
+.B CAP_SETPCAP
+in its effective set.
+.TP
+.BI --inh= cap-list
+Set the inheritable set of capabilities for the current process to
+equal those provided in the comma separated list. For this action to
+succeed, the prevailing process should already have each of these
+capabilities in the union of the current inheritable and permitted
+capability sets, or the capsh program is operating with
+.B CAP_SETPCAP
+in its effective set.
+.TP
+.BI --user= username
+Assume the identity of the named user. That is, look up the user's
+.IR uid " and " gid
+with
+.BR getpwuid (3)
+and their group memberships with
+.BR getgrouplist (3)
+and set them all.
+.TP
+.BI --uid= id
+Force all
+.B uid
+values to equal
+.I id
+using the
+.BR setuid (2)
+system call.
+.TP
+.BI --gid= <id>
+Force all
+.B gid
+values to equal
+.I id
+using the
+.BR setgid (2)
+system call.
+.TP
+.BI --groups= <id-list>
+Set the supplementary groups to the numerical list provided. The
+groups are set with the
+.BR setgroups (2)
+system call.
+.TP
+.BI --keep= <0|1>
+In a non-pure capability mode, the kernel provides liberal privilege
+to the super-user. However, it is normally the case that when the
+super-user changes
+.I uid
+to some lesser user, then capabilities are dropped. For these
+situations, the kernel can permit the process to retain its
+capabilities after a
+.BR setuid (2)
+system call. This feature is known as
+.I keep-caps
+support. The way to activate it using this script is with this
+argument. Setting the value to 1 will cause
+.I keep-caps
+to be active. Setting it to 0 will cause keep-caps to deactivate for
+the current process. In all cases,
+.I keep-caps
+is deactivated when an
+.BR exec ()
+is performed. See
+.B --secbits
+for ways to disable this feature.
+.TP
+.BI --secbits= N
+XXX - need to document this feature.
+.TP
+.BI --chroot= path
+Execute the
+.BR chroot (2)
+system call with the new root-directory (/) equal to
+.IR path .
+This operation requires
+.B CAP_SYS_CHROOT
+to be in effect.
+.TP
+.BI --forkfor= sec
+.TP
+.BI --killit= sig
+.TP
+.BI --decode= N
+This is a convenience feature. If you look at
+.B /proc/1/status
+there are some capability related fields of the following form:
+
+ CapInh:	0000000000000000
+ CapPrm:	ffffffffffffffff
+ CapEff:	fffffffffffffeff
+ CapBnd:	ffffffffffffffff
+
+This option provides a quick way to decode a capability vector
+represented in this form. For example, the missing capability from
+this effective set is 0x0100. By running:
+
+ capsh --decode=0x0100
+
+we observe that the missing capability is:
+.BR cap_setpcap .
+.TP
+.BI --supports= xxx
+As the kernel evolves, more capabilities are added. This option can be used
+to verify the existence of a capability on the system. For example,
+.BI --supports= cap_syslog
+will cause capsh to promptly exit with a status of 1 when run on
+kernel 2.6.27.  However, when run on kernel 2.6.38 it will silently
+succeed.
+.TP
+.SH "EXIT STATUS"
+Following successful execution the tool exits with status 0. Following
+an error, the tool immediately exits with status 1.
+.SH AUTHOR
+Written by Andrew G. Morgan <morgan@kernel.org>.
+.SH "REPORTING BUGS"
+Please report bugs to the author.
+.SH "SEE ALSO"
+.BR libcap (3),
+.BR getcap (8), setcap (8)
+and
+.BR capabilities (7).
diff --git a/doc/getcap.8 b/doc/getcap.8
new file mode 100644
index 0000000..1d5ac0f
--- /dev/null
+++ b/doc/getcap.8
@@ -0,0 +1,29 @@
+.\"
+.\" $Id: getcap.8,v 1.1.1.1 1999/04/17 22:16:31 morgan Exp $
+.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
+.\"
+.TH GETCAP 8 "12 Nov 2007"
+.SH NAME
+getcap \- examine file capabilities
+.SH SYNOPSIS
+\fBgetcap\fP [-v] [-r] [-h] \fIfilename\fP [ ... ]
+.SH DESCRIPTION
+.B getcap
+displays the name and capabilities of each specified
+.SH OPTIONS
+.TP 4
+.B -r
+enables recursive search.
+.TP 4
+.B -v
+enables to display all searched entries, even if it has no file-capabilities.
+.TP 4
+.B -h
+prints quick usage.
+.TP 4
+.IR filename
+One file per line.
+.SH "SEE ALSO"
+.BR cap_get_file (3),
+.BR cap_to_text (3),
+.BR setcap (8)
diff --git a/doc/libcap.3 b/doc/libcap.3
new file mode 100644
index 0000000..0e76b4e
--- /dev/null
+++ b/doc/libcap.3
@@ -0,0 +1,114 @@
+.TH LIBCAP 3 "2008-07-29" "" "Linux Programmer's Manual"
+.SH NAME
+cap_clear, cap_clear_flag, cap_compare, cap_copy_ext, cap_copy_int, \
+cap_free, cap_from_name, cap_from_text, cap_get_fd, cap_get_file, \
+cap_get_flag, cap_get_pid, cap_get_proc, cap_set_fd, cap_set_file, \
+cap_set_flag, cap_set_proc, cap_size, cap_to_name, cap_to_text, \
+cap_get_pid, cap_dup \- capability data object manipulation
+.SH SYNOPSIS
+.nf
+.B #include <sys/capability.h>
+.sp
+.BI "int cap_clear(cap_t " cap_p );
+.sp
+.BI "int cap_clear_flag(cap_t " cap_p ", cap_flag_t " flag ");"
+.sp
+.BI "int cap_compare(cap_t " cap_a ", cap_t " cap_b ");"
+.sp
+.BI "ssize_t cap_copy_ext(void *" ext_p ", cap_t " cap_p ", ssize_t " size );
+.sp
+.BI "cap_t cap_copy_int(const void *" ext_p );
+.sp
+.BI "int cap_free(void *" obj_d );
+.sp
+.BI "int cap_from_name(const char *" name ", cap_value_t *" cap_p );
+.sp
+.BI "cap_t cap_from_text(const char *" buf_p );
+.sp
+.BI "cap_t cap_get_fd(int " fd );
+.sp
+.BI "cap_t cap_get_file(const char *" path_p );
+.sp
+.BI "int cap_get_flag(cap_t " cap_p ", cap_value_t " cap ,
+.BI "                 cap_flag_t " flag ", cap_flag_value_t *" value_p ");"
+.sp
+.B #include <sys/types.h>
+.BI "cap_t cap_get_pid(pid_t " pid );
+.sp
+.B "cap_t cap_get_proc(void);"
+.sp
+.BI "int cap_set_fd(int " fd ", cap_t " caps );
+.sp
+.BI "int cap_set_file(const char *" path_p ", cap_t " cap_p );
+.sp
+.sp
+.BI "int cap_set_flag(cap_t " cap_p ", cap_flag_t " flag ", int " ncap ,
+.BI "                 const cap_value_t *" caps ", cap_flag_value_t " value ");"
+.BI "int cap_set_proc(cap_t " cap_p );
+.sp
+.BI "ssize_t cap_size(cap_t " cap_p );
+.sp
+.BI "char *cap_to_name(cap_value_t " cap );
+.sp
+.BI "char *cap_to_text(cap_t " caps ", ssize_t *" length_p );
+.sp
+.BI "cap_t cap_get_pid(pid_t " pid );
+.sp
+.BI "cap_t cap_dup(cap_t " cap_p );
+.sp
+Link with \fI-lcap\fP.
+.fi
+.SH DESCRIPTION
+These functions work on a capability state held in working storage.
+A
+.I cap_t
+holds information about the capabilities in each of the three sets,
+Permitted, Inheritable, and Effective.
+Each capability in a set may be clear (disabled, 0) or set (enabled, 1).
+.PP
+These functions work with the following data types:
+.TP 18
+.I cap_value_t
+identifies a capability, such as
+.BR CAP_CHOWN .
+.TP
+.I cap_flag_t
+identifies one of the three flags associated with a capability
+(i.e., it identifies one of the three capability sets).
+Valid values for this type are
+.BR CAP_EFFECTIVE ,
+.B CAP_INHERITABLE
+or
+.BR CAP_PERMITTED .
+.TP
+.I cap_flag_value_t
+identifies the setting of a particular capability flag
+(i.e, the value of a capability in a set).
+Valid values for this type are
+.BR CAP_CLEAR (0)
+or
+.BR CAP_SET (1).
+.SH "RETURN VALUE"
+The return value is generally specific to the individual function called.
+On failure,
+.I errno
+is set appropriately.
+.SH "CONFORMING TO"
+These functions are as per the withdrawn POSIX.1e draft specification.
+The following functions are Linux extensions:
+.BR cap_clear_flag (),
+.BR cap_compare (),
+.BR cap_from_name (),
+.BR cap_to_name (),
+and
+.BR cap_compare ().
+.SH "SEE ALSO"
+.BR cap_clear (3),
+.BR cap_copy_ext (3),
+.BR cap_from_text (3),
+.BR cap_get_file (3),
+.BR cap_get_proc (3),
+.BR cap_init (3),
+.BR capabilities (7),
+.BR getpid (2)
+.BR capsh (1)
diff --git a/doc/old/README b/doc/old/README
new file mode 100644
index 0000000..75741d3
--- /dev/null
+++ b/doc/old/README
@@ -0,0 +1 @@
+these files are not relevant to this release
diff --git a/doc/old/_fgetfilecap.2 b/doc/old/_fgetfilecap.2
new file mode 100644
index 0000000..6ce400b
--- /dev/null
+++ b/doc/old/_fgetfilecap.2
@@ -0,0 +1 @@
+.so man2/_setfilecap.2
diff --git a/doc/old/_fsetfilecap.2 b/doc/old/_fsetfilecap.2
new file mode 100644
index 0000000..6ce400b
--- /dev/null
+++ b/doc/old/_fsetfilecap.2
@@ -0,0 +1 @@
+.so man2/_setfilecap.2
diff --git a/doc/old/_getfilecap.2 b/doc/old/_getfilecap.2
new file mode 100644
index 0000000..6ce400b
--- /dev/null
+++ b/doc/old/_getfilecap.2
@@ -0,0 +1 @@
+.so man2/_setfilecap.2
diff --git a/doc/old/_getproccap.2 b/doc/old/_getproccap.2
new file mode 100644
index 0000000..5090c98
--- /dev/null
+++ b/doc/old/_getproccap.2
@@ -0,0 +1 @@
+.so man2/_setproccap.2
diff --git a/doc/old/_setfilecap.2 b/doc/old/_setfilecap.2
new file mode 100644
index 0000000..6a0538c
--- /dev/null
+++ b/doc/old/_setfilecap.2
@@ -0,0 +1,117 @@
+.\"
+.\" $Id: _setfilecap.2,v 1.1.1.1 1999/04/17 22:16:31 morgan Exp $
+.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
+.\"
+.TH _SETFILECAP 2 "26th April 1997" "Linux 2.1" "Linux Programmer's Manual"
+.SH NAME
+_setfilecap, _getfilecap, _fsetfilecap, _fgetfilecap \- set/get file capabilities
+.SH SYNOPSIS
+.B #include <sys/capability.h>
+.sp
+.BI "int _setfilecap(char const *" filename ", size_t " usize ", __cap_s const *" iset ", __cap_s const *" pset ", __cap_s const *" eset );
+.sp
+.BI "int _getproccap(char const *" filename ", size_t " usize ", __cap_s *" iset ", __cap_s *" pset ", __cap_s *" eset );
+.sp
+.BI "int _fsetfilecap(int " fd ", size_t " usize ", __cap_s const *" iset ", __cap_s const *" pset ", __cap_s const *" eset );
+.sp
+.BI "int _fgetproccap(int " fd ", size_t " usize ", __cap_s *" iset ", __cap_s *" pset ", __cap_s *" eset );
+.SH USAGE
+.br
+.B cc ... -lcap
+.SH DESCRIPTION
+.B _setfilecap
+sets the specified
+.IR filename 's
+Inheritable, Permitted and Effective capabilities to the sets specified.
+A NULL pointer specifies that a set should not be changed.
+.PP
+.B _fsetfilecap
+does the same thing to the file referenced by file descriptor
+.IR fd .
+.PP
+.B _getfilecap
+and
+.B _fgetfilecap
+copy the file's capability sets into the sets provided.
+A NULL pointer specifies that a set should not be returned.
+.PP
+The
+.I usize
+argument specifies the size of the user-space capability sets, in bytes.
+If the kernel uses a different size internally, it will truncate or
+zero-fill as required.
+.PP
+Files don't actually have a proper Effective capability set.  Instead they
+have a single-bit flag, that indicates that the set is either full or
+empty.  When setting a file's capabilities, that flag will be set if
+and only if the Effective set specified has at least one bit set.
+.SH "RETURN VALUE"
+On success, zero is returned.  On error, -1 is returned, and
+.I errno
+is set appropriately.
+.SH ERRORS
+.TP
+.SB EFAULT
+One of the capability arguments or the filename was an invalid data pointer.
+.TP
+.SB EPERM
+An attempt was made to set non-empty capabilities on a file,
+and the caller does not have the
+.SB CAP_FSETCAP
+capability raised.
+.TP
+.SB EPERM
+An attempt was made to set capabilities on a file, and
+the effective UID does not match the owner of the file, and the caller
+does not have the
+.SB CAP_FOWNER
+capability raised.
+.TP
+.SB EINVAL
+An attempt was made to set non-empty capabilities on a file
+residing on a file system that does not support them.
+.TP
+.SB EROFS
+An attempt was made to set capabilities on a file residing
+on a read-only file system.
+.TP
+.SB ENAMETOOLONG
+.I filename
+is too long.
+.TP
+.SB ENOENT
+The file specified does not exist.
+.TP
+.SB ENOMEM
+Insufficient kernel memory was available.
+.TP
+.SB ENOTDIR
+A component of the path prefix is not a directory.
+.TP
+.SB EACCES
+Search permission is denied on a component of the path prefix.
+.TP
+.SB ELOOP
+.I filename
+containes a circular reference (via symlinks).
+.TP
+.SB EBADF
+.I fd
+is not a valid file descriptor.
+.TP
+.SB EIO
+A hard error occurred while reading or writing the file system.
+.TP
+.SB ENOSYS
+The POSIX.1e capability system was not configured into the kernel.
+.SH "CONFORMING TO"
+These system calls are specific to Linux.
+The portable interfaces are
+.IR cap_set_file (3),
+.IR cap_get_file (3),
+.IR cap_set_fd (3),
+and
+.IR cap_get_fd (3).
+.SH "SEE ALSO"
+.IR _setproccap (2).
+
diff --git a/doc/old/_setproccap.2 b/doc/old/_setproccap.2
new file mode 100644
index 0000000..d4579c8
--- /dev/null
+++ b/doc/old/_setproccap.2
@@ -0,0 +1,52 @@
+.\"
+.\" $Id: _setproccap.2,v 1.1.1.1 1999/04/17 22:16:31 morgan Exp $
+.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
+.\"
+.TH _SETPROCCAP 2 "26th April 1997" "Linux 2.1" "Linux Programmer's Manual"
+.SH NAME
+_setproccap, _getproccap \- set/get process capabilities
+.SH SYNOPSIS
+.B #include <sys/capability.h>
+.sp
+.BI "int _setproccap(size_t " usize ", __cap_s const *" iset ", __cap_s const *" pset ", __cap_s const *" eset );
+.sp
+.BI "int _getproccap(size_t " usize ", __cap_s *" iset ", __cap_s *" pset ", __cap_s *" eset );
+.SH DESCRIPTION
+.B _setproccap
+sets the calling process'
+Inheritable, Permitted and Effective capabilities to the sets specified.
+A NULL pointer specifies that a set should not be changed.
+.PP
+.B _getproccap
+copies the process' capability sets into the sets provided.
+A NULL pointer specifies that a set should not be returned.
+.PP
+The
+.I usize
+argument specifies the size of the user-space capability sets, in bytes.
+If the kernel uses a different size internally, it will truncate or
+zero-fill as required.
+.SH "RETURN VALUE"
+On success, zero is returned.  On error, -1 is returned, and
+.I errno
+is set appropriately.
+.SH ERRORS
+.TP
+.SB EFAULT
+One of the capability arguments was an invalid data pointer.
+.TP
+.SB EPERM
+An attempt was made to add a capability to the Permitted set, or to set
+a capability in the Effective or Inheritable sets that is not in the
+Permitted set.
+.TP
+.SB ENOSYS
+The POSIX.1e capability system was not configured into the kernel.
+.SH "CONFORMING TO"
+These system calls are specific to Linux.
+The portable interfaces are
+.IR cap_set_proc (3)
+and
+.IR cap_get_proc (3).
+.SH "SEE ALSO"
+.IR _setfilecap (2).
diff --git a/doc/setcap.8 b/doc/setcap.8
new file mode 100644
index 0000000..9344ba5
--- /dev/null
+++ b/doc/setcap.8
@@ -0,0 +1,49 @@
+.\"
+.\" $Id: setcap.8,v 1.1.1.1 1999/04/17 22:16:31 morgan Exp $
+.\"
+.TH SETCAP 8 "24th October 2008"
+.SH NAME
+setcap \- set file capabilities
+.SH SYNOPSIS
+\fBsetcap\fP [-q] [-v] (\fIcapabilities|-|-r) filename\fP [ ... \fIcapabilitiesN\fP \fIfileN\fP ]
+.SH DESCRIPTION
+In the absence of the
+.B -v
+(verify) option
+.B setcap
+sets the capabilities of each specified
+.I filename
+to the
+.I capabilities
+specified.  The
+.B -v
+option is used to verify that the specified capabilities are currently
+associated with the file.
+.PP
+The
+.I capabilities
+are specified in the form described in
+.IR cap_from_text (3).
+.PP
+The special capability string,
+.BR '-' ,
+can be used to indicate that capabilities are read from the standard
+input. In such cases, the capability set is terminated with a blank
+line.
+.PP
+The special capability string,
+.BR '-r' ,
+is used to remove a capability set from a file.
+.PP
+The
+.B -q
+flag is used to make the program less verbose in its output.
+.SH "EXIT CODE"
+The
+.B setcap
+program will exit with a 0 exit code if successful. On failure, the
+exit code is 1.
+.SH "SEE ALSO"
+.BR cap_from_text (3),
+.BR cap_set_file (3),
+.BR getcap (8)