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