path: root/doc/cap_get_proc.3
diff options
Diffstat (limited to 'doc/cap_get_proc.3')
1 files changed, 204 insertions, 0 deletions
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 1999/04/17 22:16:31 morgan Exp $
+.TH CAP_GET_PROC 3 "2008-05-11" "" "Linux Programmer's Manual"
+cap_get_proc, cap_set_proc, capgetp, cap_get_bound, cap_drop_bound \-
+capability manipulation on processes
+.B #include <sys/capability.h>
+.B "cap_t cap_get_proc(void);"
+.BI "int cap_set_proc(cap_t " cap_p );
+.BI "int cap_get_bound(cap_value_t " cap );
+.BI "CAP_IS_SUPPORTED(cap_value_t " cap );
+.BI "int cap_drop_bound(cap_value_t " cap );
+.B #include <sys/types.h>
+.BI "cap_t cap_get_pid(pid_t " pid );
+Link with \fI-lcap\fP.
+.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.
+.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
+.BR cap_get_pid ()
+.IR cap_d ,
+.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
+.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 ().
+.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
+The functions
+.BR cap_get_proc ()
+.BR cap_get_pid ()
+return a non-NULL value on success, and NULL on failure.
+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,
+The functions
+.BR cap_set_proc ()
+.BR cap_drop_bound ()
+return zero for success, and \-1 on failure.
+On failure,
+.I errno
+is set to
+.BR cap_set_proc ()
+.BR cap_get_proc ()
+are specified in the withdrawn POSIX.1e draft specification.
+.BR cap_get_pid ()
+is a Linux extension.
+The library also supports the deprecated functions:
+.BI "int capgetp(pid_t " pid ", cap_t " cap_d );
+.BI "int capsetp(pid_t " pid ", cap_t " cap_d );
+.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 ().
+.BR capsetp ()
+attempts to set the capabilities of some other process(es),
+.IR pid .
+.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
+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
+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
+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.
+The code segment below raises the
+effective capabilities for the caller:
+ cap_t caps;
+ cap_value_t cap_list[2];
+ /* 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 */;
+.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)