1.\"- 2.\" Copyright (c) 2000 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd January 28, 2000 29.Dt ACL_FROM_TEXT 3 30.Os FreeBSD 4.0 31.Sh NAME 32.Nm acl_from_text 33.Nd create an ACL from text 34.Sh LIBRARY 35.Lb libposix1e 36.Sh SYNOPSIS 37.Fd #include <sys/types.h> 38.Fd #include <sys/acl.h> 39.Ft acl_t 40.Fn acl_from_text "const char *buf_p" 41.Sh DESCRIPTION 42The 43.Fn acl_from_text 44function converts the text form of an ACL referred to by 45.Va buf_p 46into the internal working structure for ACLs, appropriate for applying to 47files or manipulating. 48 49This function may cause memory to be allocated. The caller should free any 50releasable memory, when the new ACL is no longer required, by calling 51.Xr acl_free 3 52with the 53.Va (void *)acl_t 54as an argument. 55.Sh IMPLEMENTATION NOTES 56FreeBSD's support for POSIX.1e interfaces and features is still under 57development at this time. 58.Sh RETURN VALUES 59Upon successful completion, the function shall return a pointer to the 60internal representation of the ACL in working storage. Otherwise, a value 61of 62.Va (acl_t)NULL 63shall be returned, and 64.Va errno 65shall be set to indicate the error. 66.Sh ERRORS 67If any of the following conditions occur, the 68.Fn acl_from_text 69function shall return a value of 70.Va (acl_t)NULL 71and set 72.Va errno 73to the corresponding value: 74.Bl -tag -width Er 75.It Bq Er EACCES 76Search permission is denied for a component of the path prefix, or the 77object exists and the process does not have appropriate access rights. 78.It Bq Er EINVAL 79Argument 80.Va buf_p 81cannot be translated into an ACL. 82.It Bq Er ENOMEM 83The ACL working storage requires more memory than is allowed by the 84hardware or system-imposed memory management constraints. 85.El 86.Sh SEE ALSO 87.Xr acl 3 , 88.Xr acl_free 3 , 89.Xr acl_get 3 , 90.Xr acl_to_text 3 , 91.Xr posix1e 3 92.Sh STANDARDS 93POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion 94of the draft continues on the cross-platform POSIX.1e implementation 95mailing list. To join this list, see the 96.Fx 97POSIX.1e implementation 98page for more information. 99.Sh HISTORY 100POSIX.1e support was introduced in 101.Fx 4.0 , 102and development continues. 103.Sh AUTHORS 104.An Robert N M Watson 105.Sh BUGS 106These features are not yet fully implemented. In particular, the shipped 107version of UFS/FFS does not support storage of additional security labels, 108and so is unable to (easily) provide support for most of these features. 109 110.Fn acl_from_text 111and 112.Fn acl_to_text 113rely on the 114.Xr getpwent 3 115library calls to manage username and uid mapping, as well as the 116.Xr getgrent 3 117library calls to manage groupname and gid mapping. These calls are not 118thread safe, and so transitively, neither are 119.Fn acl_from_text 120and 121.Fn acl_to_text . 122These functions may also interfere with stateful 123calls associated with the 124.Fn getpwent 125and 126.Fn getgrent 127calls. 128