head	1.4;
access;
symbols;
locks; strict;
comment	@# @;


1.4
date	98.05.24.22.49.32;	author morgan;	state Exp;
branches;
next	1.3;

1.3
date	98.05.24.21.01.49;	author morgan;	state Exp;
branches;
next	1.2;

1.2
date	97.05.24.19.45.28;	author morgan;	state Exp;
branches;
next	1.1;

1.1
date	97.04.28.00.54.52;	author morgan;	state Exp;
branches;
next	;


desc
@zefram's manual
@


1.4
log
@corrected the list of processes with CAP_SETPCAP enabled
@
text
@.\"
.\" $Id: cap_get_proc.3,v 1.3 1998/05/24 21:01:49 morgan Exp morgan $
.\"
.TH CAP_GET_PROC 3 "26th May 1997" "" "Linux Programmer's Manual"
.SH NAME
cap_get_proc, cap_set_proc \- POSIX capability manipulation on
processes
.sp
capgetp, capsetp \- Linux specific capability manipulation on
arbitrary processes
.SH SYNOPSIS
.B #include <sys/capability.h>
.sp
.B cap_t cap_get_proc(void);
.br
.BI "int cap_set_proc(cap_t " cap_p );
.sp
.B #undef _POSIX_SOURCE
.br
.B #include <sys/capability.h>
.sp
.BI "cap_t capgetp(pid_t " pid ", cap_t " cap_d );
.br
.BI "cap_t capsetp(pid_t " pid ", cap_t " cap_d );

.SH USAGE
.br
.B cc ... -lcap
.SH DESCRIPTION
.B 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
.B cap_free
with the
.I cap_t
as an argument.
.PP
.B cap_set_proc
sets the values for all capability flags for all capabilities with 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
.B capgetp
fills an existing
.BR 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
.B /proc/<pid>/status
file.
.PP
.B 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 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 .

.SH "RETURN VALUE"
.B cap_get_proc
returns a non-NULL value on success, and NULL on failure.
.PP
.BR cap_set_proc ", " capgetp " and " capsetp
return zero for success, and \-1 on failure.
.PP
On failure,
.BR errno (3)
is set to
.BR EINVAL ,
.BR EPERM,
or
.BR ENOMEM .
.SH "CONFORMING TO"
.B cap_set_proc
and
.B cap_get_proc
are functions specified in the draft for POSIX.1e.

.SH "NOTES"
The function
.B capsetp
should be used with care.  It exists, primarily, to overcome a lack of
support for capabilities in any of the filesystems supported by Linux.
The semantics of this function may change as it is better understood.
Please note, 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 "SEE ALSO"
.IR cap_clear (3),
.IR cap_copy_ext (3),
.IR cap_from_text (3),
.IR cap_get_file (3),
.IR cap_init (3)
@


1.3
log
@added capsetp and capgetp descriptions
@
text
@d2 1
a2 1
.\" $Id: cap_get_proc.3,v 1.2 1997/05/24 19:45:28 morgan Exp morgan $
d109 1
a109 1
Please note, by default, the only process that has
d111 5
a115 3
available to it, is process 1 (typically
.BR init (8)).
You will need to recompile the kernel to modify this default.
@


1.2
log
@corrections from Aleph1
@
text
@d2 1
a2 1
.\" $Id: cap_get_proc.3,v 1.1 1997/04/28 00:54:52 morgan Exp morgan $
d6 5
a10 1
cap_get_proc, cap_set_proc \- capability manipulation on processes
d15 2
d18 8
a25 1
.BI "int cap_set_proc(cap_t " cap_p );
d53 30
d87 2
a88 2
.B cap_set_proc
returns zero on success, and \-1 on failure.
d98 17
a114 1
These functions are specified by POSIX.1e.
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" $Id$
d4 1
a4 1
.TH CAP_GET_PROC 3 "26th April 1997" "" "Linux Programmer's Manual"
d6 1
a6 1
cap_get_proc, cap_set_proc \- get/set capabilities of the process
d12 4
a15 1
.BI "int cap_set_proc(cap_t " caps );
d18 9
a26 3
returns the capability sets of the process.
The returned value must later be disposed of by passing it to
.BR cap_free .
d29 11
a39 2
sets the capabilities of the process to
.IR caps .
d46 8
@
