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: src/lib/libposix1e/acl_from_text.3,v 1.3.2.5 2001/12/20 16:27:06 ru Exp $ 27.\" $DragonFly: src/lib/libposix1e/acl_from_text.3,v 1.3 2004/03/11 12:28:52 hmp Exp $ 28.\" 29.Dd January 28, 2000 30.Dt ACL_FROM_TEXT 3 31.Os 32.Sh NAME 33.Nm acl_from_text 34.Nd create an ACL from text 35.Sh LIBRARY 36.Lb libposix1e 37.Sh SYNOPSIS 38.In sys/types.h 39.In sys/acl.h 40.Ft acl_t 41.Fn acl_from_text "const char *buf_p" 42.Sh DESCRIPTION 43The 44.Fn acl_from_text 45function converts the text form of an ACL referred to by 46.Va buf_p 47into the internal working structure for ACLs, appropriate for applying to 48files or manipulating. 49.Pp 50This function may cause memory to be allocated. The caller should free any 51releasable memory, when the new ACL is no longer required, by calling 52.Xr acl_free 3 53with the 54.Va (void *)acl_t 55as an argument. 56.Sh IMPLEMENTATION NOTES 57.Dx Ns 's 58support for POSIX.1e interfaces and features is still under 59development at this time. 60.Sh RETURN VALUES 61Upon successful completion, the function shall return a pointer to the 62internal representation of the ACL in working storage. Otherwise, a value 63of 64.Va (acl_t)NULL 65shall be returned, and 66.Va errno 67shall be set to indicate the error. 68.Sh ERRORS 69If any of the following conditions occur, the 70.Fn acl_from_text 71function shall return a value of 72.Va (acl_t)NULL 73and set 74.Va errno 75to the corresponding value: 76.Bl -tag -width Er 77.It Bq Er EACCES 78Search permission is denied for a component of the path prefix, or the 79object exists and the process does not have appropriate access rights. 80.It Bq Er EINVAL 81Argument 82.Va buf_p 83cannot be translated into an ACL. 84.It Bq Er ENOMEM 85The ACL working storage requires more memory than is allowed by the 86hardware or system-imposed memory management constraints. 87.El 88.Sh SEE ALSO 89.Xr acl 3 , 90.Xr acl_free 3 , 91.Xr acl_get 3 , 92.Xr acl_to_text 3 , 93.Xr posix1e 3 94.Sh STANDARDS 95POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion 96of the draft continues on the cross-platform POSIX.1e implementation 97mailing list. To join this list, see the 98.Fx 99POSIX.1e implementation 100page for more information. 101.Sh HISTORY 102POSIX.1e support was introduced in 103.Fx 4.0 , 104and development continues. 105.Sh AUTHORS 106.An Robert N M Watson 107.Sh BUGS 108These features are not yet fully implemented. In particular, the shipped 109version of UFS/FFS does not support storage of additional security labels, 110and so is unable to (easily) provide support for most of these features. 111.Pp 112.Fn acl_from_text 113and 114.Fn acl_to_text 115rely on the 116.Xr getpwent 3 117library calls to manage username and uid mapping, as well as the 118.Xr getgrent 3 119library calls to manage groupname and gid mapping. These calls are not 120thread safe, and so transitively, neither are 121.Fn acl_from_text 122and 123.Fn acl_to_text . 124These functions may also interfere with stateful 125calls associated with the 126.Fn getpwent 127and 128.Fn getgrent 129calls. 130