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


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

1.3
date	98.05.17.17.39.20;	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
@changed date of file
@
text
@.\"
.\" $Id: cap_get_file.3,v 1.3 1998/05/17 17:39:20 morgan Exp morgan $
.\" written by Andrew Main <zefram@@dcs.warwick.ac.uk>
.\"
.TH CAP_GET_FILE 3 "17th May 1998" "" "Linux Programmer's Manual"
.SH NAME
cap_get_file, cap_set_file, cap_get_fd, cap_set_fd \- capability manipulation on files
.sp
.B "    PLEASE NOTE NONE OF THESE FUNCTIONS ARE IMPLEMENTED IN 0.102. NEITHER IS THERE SUPPORT FOR THEM IN LINUX 2.1.102."
.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 );
.SH USAGE
.br
.B cc ... -lcap
.SH DESCRIPTION
.B cap_get_file
and
.B 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
.B cap_free
with the used
.I cap_t
as an argument.
.PP
.B cap_set_file
and
.B 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 shall be completely determined by the
contents of 
.IR cap_p .
For these functions to succeed, the calling process must have the
.B CAP_SETFCAP
capability enabled and either the effective user ID of the process must match
the file owner or the calling process must have the effective flag of the
.B CAP_FOWNER
capability set.  The effects of writing the capability state to any file
type other than a regular file are undefined.
.SH "RETURN VALUE"
.B cap_get_file
and
.B cap_get_fd
return a non-NULL value on success, and NULL on failure.
.PP
.B cap_set_file
and
.B cap_set_fd
return zero on success, and \-1 on failure.
.PP
On failure,
.BR errno (3)
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 POSIX.1e.
.SH "SEE ALSO"
.IR cap_clear (3),
.IR cap_copy_ext (3),
.IR cap_from_text (3),
.IR cap_get_proc (3),
.IR cap_init (3)
@


1.3
log
@added comment about the fact that none of these functions are
currently implemented
@
text
@d2 1
a2 1
.\" $Id: cap_get_file.3,v 1.2 1997/05/24 19:45:28 morgan Exp morgan $
d5 1
a5 1
.TH CAP_GET_FILE 3 "26th May 1997" "" "Linux Programmer's Manual"
@


1.2
log
@corrections from Aleph1
@
text
@d2 1
a2 1
.\" $Id: cap_get_file.3,v 1.1 1997/04/28 00:54:52 morgan Exp morgan $
d8 2
d11 2
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" $Id$
d5 1
a5 1
.TH CAP_GET_FILE 3 "26th April 1997" "" "Linux Programmer's Manual"
d7 1
a7 1
cap_get_file, cap_set_file, cap_get_fd, cap_set_fd \- get/set capabilities of files
d11 1
a11 1
.BI "cap_t cap_get_file(char const *" filename );
d13 1
a13 1
.BI "int cap_set_file(char const *" filename ", cap_t " caps );
d25 4
a28 3
return the capability sets of the file specified by
.I filename
or
d30 9
a38 2
The returned value must later be disposed of by passing it to
.BR cap_free .
d43 17
a59 6
set the capabilities of the file specified by
.I filename
or
.I fd
to
.IR caps .
d70 13
@
