[apple/libc.git] / posix1e / acl_init.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_init.3,v 1.13 2002/12/29 20:52:42 rwatson Exp $
.\"
.Dd January 28, 2000
.Dt ACL_INIT 3
.Os
.Sh NAME
.Nm acl_init
.Nd initialize ACL working storage
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In sys/acl.h
.Ft acl_t
.Fn acl_init "int count"
.Sh DESCRIPTION
The
.Fn acl_init
function allocates and initializes the working storage for an ACL of at
least
.Va count
ACL entries.  A pointer to the working storage is returned.  The working
storage allocated to contain the ACL is freed by a call to
.Xr acl_free 3 .
When the area is first allocated, it shall contain an ACL that contains
no ACL entries.
.Pp
This function may cause memory to be allocated.  The caller should free any
releasable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void*)acl_t
as an argument.
.Sh RETURN VALUES
Upon successful completion, this function shall return a pointer to the
working storage.  Otherwise, a value of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_init
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
The value of count is less than zero.
.It Bq Er ENOMEM
The
.Va acl_t
to be returned requires more memory than is allowed by the hardware or
system-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 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_init.3,v 1.13 2002/12/29 20:52:42 rwatson Exp $
	29	.\"
	30	.Dd January 28, 2000
	31	.Dt ACL_INIT 3
	32	.Os
	33	.Sh NAME
	34	.Nm acl_init
	35	.Nd initialize ACL working storage
	36	.Sh LIBRARY
	37	.Lb libc
	38	.Sh SYNOPSIS
	39	.In sys/types.h
	40	.In sys/acl.h
	41	.Ft acl_t
	42	.Fn acl_init "int count"
	43	.Sh DESCRIPTION
	44	The
	45	.Fn acl_init
	46	function allocates and initializes the working storage for an ACL of at
	47	least
	48	.Va count
	49	ACL entries. A pointer to the working storage is returned. The working
	50	storage allocated to contain the ACL is freed by a call to
	51	.Xr acl_free 3 .
	52	When the area is first allocated, it shall contain an ACL that contains
	53	no ACL entries.
	54	.Pp
	55	This function may cause memory to be allocated. The caller should free any
	56	releasable memory, when the new ACL is no longer required, by calling
	57	.Xr acl_free 3
	58	with the
	59	.Va (void*)acl_t
	60	as an argument.
	61	.Sh RETURN VALUES
	62	Upon successful completion, this function shall return a pointer to the
	63	working storage. Otherwise, a value of
	64	.Va (acl_t)NULL
65	shall be returned, and
66	.Va errno
67	shall be set to indicate the error.
68	.Sh ERRORS
69	If any of the following conditions occur, the
70	.Fn acl_init
71	function shall return a value of
72	.Va (acl_t)NULL
73	and set
74	.Va errno
75	to the corresponding value:
76	.Bl -tag -width Er
77	.It Bq Er EINVAL
78	The value of count is less than zero.
79	.It Bq Er ENOMEM
80	The
81	.Va acl_t
82	to be returned requires more memory than is allowed by the hardware or
83	system-imposed memory management constraints.
84	.El
85	.Sh SEE ALSO
86	.Xr acl 3 ,
87	.Xr acl_free 3 ,
88	.Xr posix1e 3
89	.Sh STANDARDS
90	POSIX.1e is described in IEEE POSIX.1e draft 17.
91	.Sh AUTHORS
92	.An Michael Smith
93	.An Robert N M Watson