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$ 29.\" 30.Dd December 29, 2002 31.Dt ACL_GET 3 32.Os 33.Sh NAME 34.Nm acl_get_fd , 35.Nm acl_get_fd_np , 36.Nm acl_get_file , 37.Nm acl_get_link_np 38.Nd get 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 acl_t 45.Fn acl_get_fd "int fd" 46.Ft acl_t 47.Fn acl_get_fd_np "int fd" "acl_type_t type" 48.Ft acl_t 49.Fn acl_get_file "const char *path_p" "acl_type_t type" 50.Ft acl_t 51.Fn acl_get_link_np "const char *path_p" "acl_type_t type" 52.Sh DESCRIPTION 53The 54.Fn acl_get_fd , 55.Fn acl_get_file , 56.Fn acl_get_link_np , 57.Fn acl_get_fd_np 58each allow the retrieval of an ACL from a file. 59The 60.Fn acl_get_fd 61is a POSIX.1e call that allows the retrieval of an ACL of type 62ACL_TYPE_ACCESS 63from a file descriptor. 64The 65.Fn acl_get_fd_np 66function 67is a non-portable form of 68.Fn acl_get_fd 69that allows the retrieval of any type of ACL from a file descriptor. 70.Fn acl_get_file 71is a POSIX.1e call that allows the retrieval of a 72specified type of ACL from a file by name; 73.Fn acl_get_link_np 74is a non-portable variation on 75.Fn acl_get_file 76which does not follow a symlink if the target of the call is a 77symlink. 78.Pp 79These functions may cause memory to be allocated. The caller should free 80any releasable memory, when the new ACL is no longer required, by calling 81.Xr acl_free 3 82with the 83.Va (void *)acl_t 84as an argument. 85.Pp 86The ACL in the working storage is an independent copy of the ACL associated 87with the object referred to by 88.Va fd . 89The ACL in the working storage shall not participate in any access control 90decisions. 91.Sh IMPLEMENTATION NOTES 92.Fx Ns 's 93support for POSIX.1e interfaces and features is still under 94development at this time. 95.Sh RETURN VALUES 96Upon successful completion, the function shall return a pointer to the ACL 97that was retrieved. Otherwise, a value of 98.Va (acl_t)NULL 99shall be returned, and 100.Va errno 101shall be set to indicate the error. 102.Sh ERRORS 103If any of the following conditions occur, the 104.Fn acl_get_fd 105function shall return a value of 106.Va (acl_t)NULL 107and set 108.Va errno 109to the corresponding value: 110.Bl -tag -width Er 111.It Bq Er EACCES 112Search permission is denied for a component of the path prefix, or the 113object exists and the process does not have appropriate access rights. 114.It Bq Er EBADF 115The 116.Va fd 117argument is not a valid file descriptor. 118.It Bq Er EINVAL 119The ACL type passed is invalid for this file object. 120.It Bq Er ENAMETOOLONG 121A component of a pathname exceeded 255 characters, or an 122entire path name exceeded 1023 characters. 123.It Bq Er ENOENT 124The named object does not exist, or the 125.Va path_p 126argument points to an empty string. 127.It Bq Er ENOMEM 128Insufficient memory available to fulfill request. 129.It Bq Er EOPNOTSUPP 130The file system does not support ACL retrieval. 131.El 132.Sh SEE ALSO 133.Xr acl 3 , 134.Xr acl_free 3 , 135.Xr acl_get 3 , 136.Xr acl_set 3 , 137.Xr posix1e 3 138.Sh STANDARDS 139POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion 140of the draft continues on the cross-platform POSIX.1e implementation 141mailing list. To join this list, see the 142.Fx 143POSIX.1e implementation 144page for more information. 145.Sh HISTORY 146POSIX.1e support was introduced in 147.Fx 4.0 , 148and development continues. 149.Sh AUTHORS 150.An Robert N M Watson 151