|
Packit Service |
410935 |
.\"
|
|
Packit Service |
410935 |
.\" $Id: cap_get_proc.3,v 1.1.1.1 1999/04/17 22:16:31 morgan Exp $
|
|
Packit Service |
410935 |
.\"
|
|
Packit Service |
410935 |
.TH CAP_GET_PROC 3 "2008-05-11" "" "Linux Programmer's Manual"
|
|
Packit Service |
410935 |
.SH NAME
|
|
Packit Service |
c7be57 |
cap_get_proc, cap_set_proc, capgetp, cap_get_bound, cap_drop_bound \
|
|
Packit Service |
c7be57 |
cap_get_ambient, cap_set_ambient, cap_reset_ambient, \-
|
|
Packit Service |
410935 |
capability manipulation on processes
|
|
Packit Service |
410935 |
.SH SYNOPSIS
|
|
Packit Service |
410935 |
.B #include <sys/capability.h>
|
|
Packit Service |
410935 |
.sp
|
|
Packit Service |
410935 |
.B "cap_t cap_get_proc(void);"
|
|
Packit Service |
410935 |
.sp
|
|
Packit Service |
410935 |
.BI "int cap_set_proc(cap_t " cap_p );
|
|
Packit Service |
410935 |
.sp
|
|
Packit Service |
410935 |
.BI "int cap_get_bound(cap_value_t " cap );
|
|
Packit Service |
410935 |
.sp
|
|
Packit Service |
410935 |
.BI "CAP_IS_SUPPORTED(cap_value_t " cap );
|
|
Packit Service |
410935 |
.sp
|
|
Packit Service |
410935 |
.BI "int cap_drop_bound(cap_value_t " cap );
|
|
Packit Service |
410935 |
.sp
|
|
Packit Service |
c7be57 |
.BI "int cap_get_ambient(cap_value_t " cap );
|
|
Packit Service |
c7be57 |
.sp
|
|
Packit Service |
c7be57 |
.BI "int cap_set_ambient(cap_value_t " cap ", cap_flag_value_t " value);
|
|
Packit Service |
c7be57 |
.sp
|
|
Packit Service |
c7be57 |
.B int cap_reset_ambient(void);
|
|
Packit Service |
c7be57 |
.sp
|
|
Packit Service |
c7be57 |
.BI CAP_AMBIENT_SUPPORTED();
|
|
Packit Service |
c7be57 |
.sp
|
|
Packit Service |
410935 |
.B #include <sys/types.h>
|
|
Packit Service |
410935 |
.sp
|
|
Packit Service |
410935 |
.BI "cap_t cap_get_pid(pid_t " pid );
|
|
Packit Service |
410935 |
.sp
|
|
Packit Service |
410935 |
Link with \fI-lcap\fP.
|
|
Packit Service |
410935 |
.SH DESCRIPTION
|
|
Packit Service |
410935 |
.BR cap_get_proc ()
|
|
Packit Service |
410935 |
allocates a capability state in working storage, sets its state to
|
|
Packit Service |
410935 |
that of the calling process, and returns a pointer to this newly
|
|
Packit Service |
410935 |
created capability state. The caller should free any releasable
|
|
Packit Service |
410935 |
memory, when the capability state in working storage is no longer
|
|
Packit Service |
410935 |
required, by calling
|
|
Packit Service |
410935 |
.BR cap_free ()
|
|
Packit Service |
410935 |
with the
|
|
Packit Service |
410935 |
.I cap_t
|
|
Packit Service |
410935 |
as an argument.
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
.BR cap_set_proc ()
|
|
Packit Service |
410935 |
sets the values for all capability flags for all capabilities to the
|
|
Packit Service |
410935 |
capability state identified by
|
|
Packit Service |
410935 |
.IR cap_p .
|
|
Packit Service |
410935 |
The new capability state of the process will be completely determined by
|
|
Packit Service |
410935 |
the contents of
|
|
Packit Service |
410935 |
.I cap_p
|
|
Packit Service |
410935 |
upon successful return from this function. If any flag in
|
|
Packit Service |
410935 |
.I cap_p
|
|
Packit Service |
410935 |
is set for any capability not currently permitted for the calling process,
|
|
Packit Service |
410935 |
the function will fail, and the capability state of the process will remain
|
|
Packit Service |
410935 |
unchanged.
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
.BR cap_get_pid ()
|
|
Packit Service |
410935 |
returns
|
|
Packit Service |
410935 |
.IR cap_t ,
|
|
Packit Service |
410935 |
see
|
|
Packit Service |
410935 |
.BR cap_init (3),
|
|
Packit Service |
410935 |
with the process capabilities of the process indicated by
|
|
Packit Service |
410935 |
.IR pid .
|
|
Packit Service |
410935 |
This information can also be obtained from the
|
|
Packit Service |
410935 |
.I /proc/<pid>/status
|
|
Packit Service |
410935 |
file.
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
.BR cap_get_bound ()
|
|
Packit Service |
410935 |
with a
|
|
Packit Service |
410935 |
.I cap
|
|
Packit Service |
410935 |
as an argument returns the current value of this bounding set
|
|
Packit Service |
410935 |
capability flag in effect for the current process. This operation is
|
|
Packit Service |
410935 |
unpriveged. Note, a macro function
|
|
Packit Service |
410935 |
.BI "CAP_IS_SUPPORTED(cap_value_t " cap )
|
|
Packit Service |
410935 |
is provided that evaluates to true (1) if the system supports the
|
|
Packit Service |
410935 |
specified capability,
|
|
Packit Service |
410935 |
.IR cap .
|
|
Packit Service |
410935 |
If the system does not support the capability, this function returns
|
|
Packit Service |
410935 |
0. This macro works by testing for an error condition with
|
|
Packit Service |
410935 |
.BR cap_get_bound ().
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
.BR cap_drop_bound ()
|
|
Packit Service |
410935 |
can be used to lower the specified bounding set capability,
|
|
Packit Service |
c7be57 |
.BR cap .
|
|
Packit Service |
410935 |
To complete successfully, the prevailing
|
|
Packit Service |
410935 |
.I effective
|
|
Packit Service |
410935 |
capability set must have a raised
|
|
Packit Service |
410935 |
.BR CAP_SETPCAP .
|
|
Packit Service |
c7be57 |
.BR cap_get_ambient ()
|
|
Packit Service |
c7be57 |
returns the prevailing value of the specified ambient capability, or
|
|
Packit Service |
c7be57 |
-1 if the capability is not supported by the running kernel. A macro
|
|
Packit Service |
c7be57 |
.BR CAP_AMBIENT_SUPPORTED ()
|
|
Packit Service |
c7be57 |
uses this function to determine if ambient capabilities are supported
|
|
Packit Service |
c7be57 |
by the kernel.
|
|
Packit Service |
c7be57 |
.PP
|
|
Packit Service |
c7be57 |
.BR cap_set_ambient ()
|
|
Packit Service |
c7be57 |
sets the specified ambient capability to a specific value. To complete
|
|
Packit Service |
c7be57 |
successfully, the prevailing
|
|
Packit Service |
c7be57 |
.I effective
|
|
Packit Service |
c7be57 |
capability set must have a raised
|
|
Packit Service |
c7be57 |
.BR CAP_SETPCAP .
|
|
Packit Service |
c7be57 |
.PP
|
|
Packit Service |
c7be57 |
.BR cap_reset_ambient ()
|
|
Packit Service |
c7be57 |
resets all of the ambient capabilities for the current process to
|
|
Packit Service |
c7be57 |
their lowered value. To complete successfully, the prevailing
|
|
Packit Service |
c7be57 |
.I effective
|
|
Packit Service |
c7be57 |
capability set must have a raised
|
|
Packit Service |
c7be57 |
.BR CAP_SETPCAP .
|
|
Packit Service |
c7be57 |
Note, the ambient set is intended to operate in a legacy environment
|
|
Packit Service |
c7be57 |
where the application has limited awareness of capabilities in
|
|
Packit Service |
c7be57 |
general. Executing a file with associated filesystem capabilities, the
|
|
Packit Service |
c7be57 |
kernel will implicitly reset the ambient set of the process. Also,
|
|
Packit Service |
c7be57 |
changes to the inheritable set by the program code without explicitly
|
|
Packit Service |
c7be57 |
fixing up the ambient set can also drop ambient bits.
|
|
Packit Service |
c7be57 |
.PP
|
|
Packit Service |
410935 |
.SH "RETURN VALUE"
|
|
Packit Service |
410935 |
The functions
|
|
Packit Service |
410935 |
.BR cap_get_proc ()
|
|
Packit Service |
410935 |
and
|
|
Packit Service |
410935 |
.BR cap_get_pid ()
|
|
Packit Service |
410935 |
return a non-NULL value on success, and NULL on failure.
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
The function
|
|
Packit Service |
410935 |
.BR cap_get_bound ()
|
|
Packit Service |
410935 |
returns -1 if the requested capability is unknown, otherwise the
|
|
Packit Service |
410935 |
return value reflects the current state of that capability in the
|
|
Packit Service |
410935 |
prevailing bounding set. Note, a macro function,
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
The functions
|
|
Packit Service |
410935 |
.BR cap_set_proc ()
|
|
Packit Service |
410935 |
and
|
|
Packit Service |
410935 |
.BR cap_drop_bound ()
|
|
Packit Service |
410935 |
return zero for success, and \-1 on failure.
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
On failure,
|
|
Packit Service |
410935 |
.I errno
|
|
Packit Service |
410935 |
is set to
|
|
Packit Service |
410935 |
.BR EINVAL ,
|
|
Packit Service |
410935 |
.BR EPERM,
|
|
Packit Service |
410935 |
or
|
|
Packit Service |
410935 |
.BR ENOMEM .
|
|
Packit Service |
410935 |
.SH "CONFORMING TO"
|
|
Packit Service |
410935 |
.BR cap_set_proc ()
|
|
Packit Service |
410935 |
and
|
|
Packit Service |
410935 |
.BR cap_get_proc ()
|
|
Packit Service |
410935 |
are specified in the withdrawn POSIX.1e draft specification.
|
|
Packit Service |
410935 |
.BR cap_get_pid ()
|
|
Packit Service |
410935 |
is a Linux extension.
|
|
Packit Service |
410935 |
.SH "NOTES"
|
|
Packit Service |
410935 |
The library also supports the deprecated functions:
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
.BI "int capgetp(pid_t " pid ", cap_t " cap_d );
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
.BI "int capsetp(pid_t " pid ", cap_t " cap_d );
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
.BR capgetp ()
|
|
Packit Service |
410935 |
attempts to obtain the capabilities of some other process; storing the
|
|
Packit Service |
410935 |
capabilities in a pre-allocated
|
|
Packit Service |
410935 |
.IR cap_d . See
|
|
Packit Service |
410935 |
.BR cap_init ()
|
|
Packit Service |
410935 |
for information on allocating an empty capability set. This function,
|
|
Packit Service |
410935 |
.BR capgetp (),
|
|
Packit Service |
410935 |
is deprecated, you should use
|
|
Packit Service |
410935 |
.BR cap_get_pid ().
|
|
Packit Service |
410935 |
.PP
|
|
Packit Service |
410935 |
.BR capsetp ()
|
|
Packit Service |
410935 |
attempts to set the capabilities of some other process(es),
|
|
Packit Service |
410935 |
.IR pid .
|
|
Packit Service |
410935 |
If
|
|
Packit Service |
410935 |
.I pid
|
|
Packit Service |
410935 |
is positive it refers to a specific process; if it is zero, it refers
|
|
Packit Service |
410935 |
to the current process; -1 refers to all processes other than the
|
|
Packit Service |
410935 |
current process and process '1' (typically
|
|
Packit Service |
410935 |
.BR init (8));
|
|
Packit Service |
410935 |
other negative values refer to the
|
|
Packit Service |
410935 |
.I -pid
|
|
Packit Service |
410935 |
process group. In order to use this function, the kernel must support
|
|
Packit Service |
410935 |
it and the current process must have
|
|
Packit Service |
410935 |
.B CAP_SETPCAP
|
|
Packit Service |
410935 |
raised in its Effective capability set. The capabilities set in the
|
|
Packit Service |
410935 |
target process(es) are those contained in
|
|
Packit Service |
410935 |
.IR cap_d .
|
|
Packit Service |
410935 |
Kernels that support filesystem capabilities redefine the semantics of
|
|
Packit Service |
410935 |
.B CAP_SETPCAP
|
|
Packit Service |
410935 |
and on such systems this function will always fail for any target not
|
|
Packit Service |
410935 |
equal to the current process.
|
|
Packit Service |
410935 |
.BR capsetp ()
|
|
Packit Service |
410935 |
returns zero for success, and \-1 on failure.
|
|
Packit Service |
410935 |
|
|
Packit Service |
410935 |
Where supported by the kernel, the function
|
|
Packit Service |
410935 |
.BR capsetp ()
|
|
Packit Service |
410935 |
should be used with care. It existed, primarily, to overcome an early
|
|
Packit Service |
410935 |
lack of support for capabilities in the filesystems supported by
|
|
Packit Service |
410935 |
Linux. Note that, by default, the only processes that have
|
|
Packit Service |
410935 |
.B CAP_SETPCAP
|
|
Packit Service |
410935 |
available to them are processes started as a kernel thread.
|
|
Packit Service |
410935 |
(Typically this includes
|
|
Packit Service |
410935 |
.BR init (8),
|
|
Packit Service |
410935 |
kflushd and kswapd). You will need to recompile the kernel to modify
|
|
Packit Service |
410935 |
this default.
|
|
Packit Service |
410935 |
.SH EXAMPLE
|
|
Packit Service |
410935 |
The code segment below raises the
|
|
Packit Service |
410935 |
.B CAP_FOWNER
|
|
Packit Service |
410935 |
and
|
|
Packit Service |
410935 |
.B CAP_SETFCAP
|
|
Packit Service |
410935 |
effective capabilities for the caller:
|
|
Packit Service |
410935 |
.nf
|
|
Packit Service |
410935 |
|
|
Packit Service |
410935 |
cap_t caps;
|
|
Packit Service |
410935 |
cap_value_t cap_list[2];
|
|
Packit Service |
410935 |
|
|
Packit Service |
410935 |
if (!CAP_IS_SUPPORTED(CAP_SETFCAP))
|
|
Packit Service |
410935 |
/* handle error */
|
|
Packit Service |
410935 |
|
|
Packit Service |
410935 |
caps = cap_get_proc();
|
|
Packit Service |
410935 |
if (caps == NULL)
|
|
Packit Service |
410935 |
/* handle error */;
|
|
Packit Service |
410935 |
|
|
Packit Service |
410935 |
cap_list[0] = CAP_FOWNER;
|
|
Packit Service |
410935 |
cap_list[1] = CAP_SETFCAP;
|
|
Packit Service |
410935 |
if (cap_set_flag(caps, CAP_EFFECTIVE, 2, cap_list, CAP_SET) == -1)
|
|
Packit Service |
410935 |
/* handle error */;
|
|
Packit Service |
410935 |
|
|
Packit Service |
410935 |
if (cap_set_proc(caps) == -1)
|
|
Packit Service |
410935 |
/* handle error */;
|
|
Packit Service |
410935 |
|
|
Packit Service |
410935 |
if (cap_free(caps) == -1)
|
|
Packit Service |
410935 |
/* handle error */;
|
|
Packit Service |
410935 |
.fi
|
|
Packit Service |
410935 |
.SH "SEE ALSO"
|
|
Packit Service |
410935 |
.BR libcap (3),
|
|
Packit Service |
410935 |
.BR cap_clear (3),
|
|
Packit Service |
410935 |
.BR cap_copy_ext (3),
|
|
Packit Service |
410935 |
.BR cap_from_text (3),
|
|
Packit Service |
410935 |
.BR cap_get_file (3),
|
|
Packit Service |
410935 |
.BR cap_init (3),
|
|
Packit Service |
410935 |
.BR capabilities (7)
|