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