1.\" $NetBSD: acl_get.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ 2.\"- 3.\" Copyright (c) 2000, 2002 Robert N. M. Watson 4.\" All rights reserved. 5.\" 6.\" This software was developed by Robert Watson for the TrustedBSD Project. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD: head/lib/libc/posix1e/acl_get.3 213573 2010-10-08 12:40:16Z uqs $ 30.\" 31.Dd June 25, 2009 32.Dt ACL_GET 3 33.Os 34.Sh NAME 35.Nm acl_get_fd , 36.Nm acl_get_fd_np , 37.Nm acl_get_file , 38.Nm acl_get_link_np 39.Nd get an ACL for a file 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/acl.h 45.Ft acl_t 46.Fn acl_get_fd "int fd" 47.Ft acl_t 48.Fn acl_get_fd_np "int fd" "acl_type_t type" 49.Ft acl_t 50.Fn acl_get_file "const char *path_p" "acl_type_t type" 51.Ft acl_t 52.Fn acl_get_link_np "const char *path_p" "acl_type_t type" 53.Sh DESCRIPTION 54The 55.Fn acl_get_fd , 56.Fn acl_get_file , 57.Fn acl_get_link_np , 58and 59.Fn acl_get_fd_np 60each allow the retrieval of an ACL from a file. 61The 62.Fn acl_get_fd 63is a POSIX.1e call that allows the retrieval of an ACL of type 64ACL_TYPE_ACCESS 65from a file descriptor. 66The 67.Fn acl_get_fd_np 68function 69is a non-portable form of 70.Fn acl_get_fd 71that allows the retrieval of any type of ACL from a file descriptor. 72The 73.Fn acl_get_file 74function is a POSIX.1e call that allows the retrieval of a 75specified type of ACL from a file by name; 76.Fn acl_get_link_np 77is a non-portable variation on 78.Fn acl_get_file 79which does not follow a symlink if the target of the call is a 80symlink. 81.Pp 82These functions may cause memory to be allocated. 83The caller should free 84any releasable memory, when the new ACL is no longer required, by calling 85.Xr acl_free 3 86with the 87.Va (void *)acl_t 88as an argument. 89.Pp 90The ACL in the working storage is an independent copy of the ACL associated 91with the object referred to by 92.Va fd . 93The ACL in the working storage shall not participate in any access control 94decisions. 95.Pp 96Valid values for the 97.Va type 98argument are: 99.Bl -column -offset 3n "ACL_TYPE_DEFAULT" 100.It ACL_TYPE_ACCESS POSIX.1e access ACL 101.It ACL_TYPE_DEFAULT POSIX.1e default ACL 102.It ACL_TYPE_NFS4 NFSv4 ACL 103.El 104.Pp 105The ACL returned will be branded accordingly. 106.Sh IMPLEMENTATION NOTES 107.Fx Ns 's 108support for POSIX.1e interfaces and features is still under 109development at this time. 110.Sh RETURN VALUES 111Upon successful completion, the function shall return a pointer to the ACL 112that was retrieved. 113Otherwise, a value of 114.Va (acl_t)NULL 115shall be returned, and 116.Va errno 117shall be set to indicate the error. 118.Sh ERRORS 119If any of the following conditions occur, the 120.Fn acl_get_fd 121function shall return a value of 122.Va (acl_t)NULL 123and set 124.Va errno 125to the corresponding value: 126.Bl -tag -width Er 127.It Bq Er EACCES 128Search permission is denied for a component of the path prefix, or the 129object exists and the process does not have appropriate access rights. 130.It Bq Er EBADF 131The 132.Va fd 133argument is not a valid file descriptor. 134.It Bq Er EINVAL 135The ACL type passed is invalid for this file object. 136.It Bq Er ENAMETOOLONG 137A component of a pathname exceeded 255 characters, or an 138entire path name exceeded 1023 characters. 139.It Bq Er ENOENT 140The named object does not exist, or the 141.Va path_p 142argument points to an empty string. 143.It Bq Er ENOMEM 144Insufficient memory available to fulfill request. 145.It Bq Er EOPNOTSUPP 146The file system does not support ACL retrieval. 147.El 148.Sh SEE ALSO 149.Xr acl 3 , 150.Xr acl_free 3 , 151.Xr acl_get 3 , 152.Xr acl_get_brand_np 3 , 153.Xr acl_set 3 , 154.Xr posix1e 3 155.Sh STANDARDS 156POSIX.1e is described in IEEE POSIX.1e draft 17. 157Discussion 158of the draft continues on the cross-platform POSIX.1e implementation 159mailing list. 160To join this list, see the 161.Fx 162POSIX.1e implementation 163page for more information. 164.Sh HISTORY 165POSIX.1e support was introduced in 166.Fx 4.0 , 167and development continues. 168.Sh AUTHORS 169.An Robert N M Watson 170