[apple/libc.git] / posix1e / acl_set.3

.\"-
.\" Copyright (c) 2000, 2002 Robert N. M. Watson
.\" All rights reserved.
.\"
.\" This software was developed by Robert Watson for the TrustedBSD Project.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc/posix1e/acl_set.3,v 1.16 2003/02/23 01:44:59 ru Exp $
.\"
.Dd December 29, 2002
.Dt ACL_SET 3
.Os
.Sh NAME
.Nm acl_set_fd ,
.Nm acl_set_fd_np ,
.Nm acl_set_file ,
.Nm acl_set_link_np
.Nd set an ACL for a file
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In sys/acl.h
.Ft int
.Fn acl_set_fd "int fd" "acl_t acl"
.Ft int
.Fn acl_set_fd_np "int fd" "acl_t acl" "acl_type_t type"
.Ft int
.Fn acl_set_file "const char *path_p" "acl_type_t type" "acl_t acl"
.Ft int
.Fn acl_set_link_np "const char *path_p" "acl_type_t type" "acl_t acl"
.Sh DESCRIPTION
The
.Fn acl_set_fd ,
.Fn acl_set_fd_np ,
.Fn acl_set_file ,
and
.Fn acl_set_link_np
each associate an ACL with an object referred to by
.Va fd
or
.Va path_p .
The
.Fn acl_set_fd_np
and
.Fn acl_set_link_np
functions are not POSIX.1e calls.
The
.Fn acl_set_fd
function allows only the setting of ACLs of type ACL_TYPE_EXTENDED
where as
.Fn acl_set_fd_np
allows the setting of ACLs of any type.
.Pp
The
.Fn acl_set_link_np
function acts on a symlink rather than its target, if the target of the
path is a symlink.
In the case of a symlink, this function will return an error
because ACLs are not currently supported on symlinks.
Note that the implementation is not atomic, and so the target could change
between the time it is checked as not being a symlink, and the
time the ACL is set.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
If any of the following conditions occur, these functions shall return
-1 and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL for this object, or the ACL type
specified in
.Va type
is invalid for this object, or both.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er ENOSPC
The directory or file system that would contain the new ACL cannot be
extended, or the file system is out of file allocation resources.
.It Bq Er EOPNOTSUPP
The file system does not support ACL retrieval.
.It Bq Er EROFS
This function requires modification of a file system which is currently
read-only.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_delete 3 ,
.Xr acl_get 3 ,
.Xr acl_valid 3 ,
.Xr posix1e 3
.Sh STANDARDS
POSIX.1e is described in IEEE POSIX.1e draft 17.
.Sh AUTHORS
.An Michael Smith
.An Robert N M Watson
Commit	Line	Data
3d9156a7 A	1	.\"-
	2	.\" Copyright (c) 2000, 2002 Robert N. M. Watson
	3	.\" All rights reserved.
	4	.\"
	5	.\" This software was developed by Robert Watson for the TrustedBSD Project.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\"
	16	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	17	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	18	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	19	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	20	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	21	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	22	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	23	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	24	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	25	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	26	.\" SUCH DAMAGE.
	27	.\"
	28	.\" $FreeBSD: src/lib/libc/posix1e/acl_set.3,v 1.16 2003/02/23 01:44:59 ru Exp $
	29	.\"
	30	.Dd December 29, 2002
	31	.Dt ACL_SET 3
	32	.Os
	33	.Sh NAME
	34	.Nm acl_set_fd ,
	35	.Nm acl_set_fd_np ,
	36	.Nm acl_set_file ,
	37	.Nm acl_set_link_np
	38	.Nd set an ACL for a file
	39	.Sh LIBRARY
	40	.Lb libc
	41	.Sh SYNOPSIS
	42	.In sys/types.h
	43	.In sys/acl.h
	44	.Ft int
	45	.Fn acl_set_fd "int fd" "acl_t acl"
	46	.Ft int
	47	.Fn acl_set_fd_np "int fd" "acl_t acl" "acl_type_t type"
	48	.Ft int
	49	.Fn acl_set_file "const char *path_p" "acl_type_t type" "acl_t acl"
	50	.Ft int
	51	.Fn acl_set_link_np "const char *path_p" "acl_type_t type" "acl_t acl"
	52	.Sh DESCRIPTION
	53	The
	54	.Fn acl_set_fd ,
	55	.Fn acl_set_fd_np ,
	56	.Fn acl_set_file ,
	57	and
	58	.Fn acl_set_link_np
	59	each associate an ACL with an object referred to by
	60	.Va fd
	61	or
	62	.Va path_p .
	63	The
	64	.Fn acl_set_fd_np
65	and
66	.Fn acl_set_link_np
67	functions are not POSIX.1e calls.
68	The
69	.Fn acl_set_fd
70	function allows only the setting of ACLs of type ACL_TYPE_EXTENDED
71	where as
72	.Fn acl_set_fd_np
73	allows the setting of ACLs of any type.
34e8f829	74	.Pp
3d9156a7 A	75	The
	76	.Fn acl_set_link_np
	77	function acts on a symlink rather than its target, if the target of the
	78	path is a symlink.
34e8f829 A	79	In the case of a symlink, this function will return an error
	80	because ACLs are not currently supported on symlinks.
	81	Note that the implementation is not atomic, and so the target could change
	82	between the time it is checked as not being a symlink, and the
	83	time the ACL is set.
3d9156a7 A	84	.Sh RETURN VALUES
	85	.Rv -std
	86	.Sh ERRORS
	87	If any of the following conditions occur, these functions shall return
	88	-1 and set
	89	.Va errno
	90	to the corresponding value:
	91	.Bl -tag -width Er
	92	.It Bq Er EACCES
	93	Search permission is denied for a component of the path prefix, or the
	94	object exists and the process does not have appropriate access rights.
	95	.It Bq Er EBADF
	96	The
	97	.Va fd
	98	argument is not a valid file descriptor.
	99	.It Bq Er EINVAL
	100	Argument
	101	.Va acl
	102	does not point to a valid ACL for this object, or the ACL type
	103	specified in
	104	.Va type
	105	is invalid for this object, or both.
	106	.It Bq Er ENAMETOOLONG
	107	A component of a pathname exceeded 255 characters, or an
	108	entire path name exceeded 1023 characters.
	109	.It Bq Er ENOENT
	110	The named object does not exist, or the
	111	.Va path_p
	112	argument points to an empty string.
	113	.It Bq Er ENOMEM
	114	Insufficient memory available to fulfill request.
	115	.It Bq Er ENOSPC
	116	The directory or file system that would contain the new ACL cannot be
	117	extended, or the file system is out of file allocation resources.
	118	.It Bq Er EOPNOTSUPP
	119	The file system does not support ACL retrieval.
	120	.It Bq Er EROFS
	121	This function requires modification of a file system which is currently
	122	read-only.
	123	.El
	124	.Sh SEE ALSO
	125	.Xr acl 3 ,
	126	.Xr acl_delete 3 ,
	127	.Xr acl_get 3 ,
	128	.Xr acl_valid 3 ,
	129	.Xr posix1e 3
	130	.Sh STANDARDS
	131	POSIX.1e is described in IEEE POSIX.1e draft 17.
	132	.Sh AUTHORS
	133	.An Michael Smith
	134	.An Robert N M Watson