---
name: "acl_get_file"
section: "3"
platform: "linux"
package: "acl"
version: "2.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/acl_get_file"
---

# acl\_get\_file(3)

get an ACL by filename

## NAME

**acl\_get\_file**, **acl\_get\_file\_at** – get an ACL by filename

## LIBRARY

Linux Access Control Lists library (libacl, -lacl).

## SYNOPSIS

**#include \<sys/types.h\>**

**#include \<sys/acl.h\>**

*acl\_t*\

**acl\_get\_file**(*const char \*path\_p*, *acl\_type\_t type*);

*acl\_t*\

**acl\_get\_file\_at**(*int dirfd*, *const char \*path\_p*, *int at\_flags*, *acl\_type\_t type*);

## DESCRIPTION

The **acl\_get\_file**() function retrieves the access ACL associated with a file or directory, or the default ACL associated with a directory. The pathname for the file or directory is given in the argument *path\_p*. If *path\_p* is a symbolic link, **acl\_get\_file**() returns information about the file or directory the link refers to.

The ACL is placed into working storage and **acl\_get\_file**() returns a pointer to that storage.

In order to read an ACL from an object, a process must have read access to the object's attributes.

The value of the argument *type* is used to indicate whether the access ACL or the default ACL associated with *path\_p* is returned. If *type* is ACL\_TYPE\_ACCESS, the access ACL of *path\_p* is returned. If *type* is ACL\_TYPE\_DEFAULT, the default ACL of *path\_p* is returned. If *type* is ACL\_TYPE\_DEFAULT and no default ACL is associated with the directory *path\_p*, then an ACL containing zero ACL entries is returned. If *type* specifies a type of ACL that cannot be associated with *path\_p*, then the function fails.

This function may cause memory to be allocated.  The caller should free any releasable memory, when the new ACL is no longer required, by calling [acl\_free(3)](/acl_free/3.md) with the *(void\*)acl\_t* returned by **acl\_get\_file**() as an argument.

### Fn acl\_get\_file\_at

The **acl\_get\_file\_at**() function operates in exactly the same way as **acl\_get\_file**(), except for the differences described here.

If the pathname given in *path\_p* is relative, then it is interpreted relative to the directory referred to by the file descriptor *dirfd* (rather than relative to the current working directory of the calling process, as is done by **acl\_get\_file**()).

If *path\_p* is relative and *dirfd* is the special value AT\_FDCWD, then *path\_p* is interpreted relative to the current working directory of the calling process (like **acl\_get\_file**()).

If *path\_p* is absolute, then *dirfd* is ignored.

The *at\_flags* argument can either be 0, or include one or more of the following flags ORed:

- AT\_EMPTY\_PATH

  If *path\_p* is an empty string, operate on the file referred to by *dirfd* (which may have been obtained using the [open(2)](/open/2.md) O\_PATH flag). In this case, *dirfd* can refer to any type of file, not just a directory, and the behavior of **acl\_get\_file\_at**() is similar to that of **acl\_get\_fd**().

- AT\_SYMLINK\_NOFOLLOW

  If *path\_p* refers to a symbolic link, do not dereference it: instead, fail the operation and set the global variable *errno* to ENOTSUP. This indicates that the symbolic link cannot have ACLs.

## RETURN VALUE

On success, the **acl\_get\_file**() and **acl\_get\_file\_at**() functions return a pointer to the working storage.  On error, a value of (acl\_t)NULL is returned, and *errno* is set appropriately.

## ERRORS

If any of the following conditions occur, the **acl\_get\_file**() and **acl\_get\_file\_at**() functions return a value of (acl\_t)NULL and set *errno* to the corresponding value:

- \[EACCES\]

  Search permission is denied for a component of the path prefix or the object exists and the process does not have appropriate access rights.

  Argument *type* specifies a type of ACL that cannot be associated with *path\_p*.

- \[EBADF\]

  The argument *path\_p* is relative but the argument *dirfd* is neither AT\_FDCWD nor a valid file descriptor.

- \[EINVAL\]

  The argument *type* is not ACL\_TYPE\_ACCESS or ACL\_TYPE\_DEFAULT.

  An invalid flag was specified in the *at\_flags* argument.

- \[ENAMETOOLONG\]

  The length of the argument *path\_p* is too long.

- \[ENOENT\]

  The named object does not exist or the argument *path\_p* points to an empty string.

- \[ENOMEM\]

  The ACL working storage requires more memory than is allowed by the hardware or system-imposed memory management constraints.

- \[ENOTDIR\]

  A component of the path prefix is not a directory.

  The argument *path\_p* is relative and the argument *dirfd* is a file descriptor referring to a file other than a directory.

- \[ENOTSUP\]

  The argument *at\_flags* includes the flag AT\_SYMLINK\_NOFOLLOW and *path\_p* is a symbolic link.

  The file system on which the file identified by *path\_p* is located does not support ACLs, or ACLs are disabled.

## STANDARDS

IEEE Std 1003.1e draft 17 (“POSIX.1e”, abandoned)

Function **acl\_get\_file\_at**() is a Linux specific extension.

## SEE ALSO

[acl\_free(3)](/acl_free/3.md), [acl\_get\_entry(3)](/acl_get_entry/3.md), [acl\_get\_fd(3)](/acl_get_fd/3.md), [acl\_set\_file(3)](/acl_set_file/3.md), [acl(5)](/acl/5.md)

## AUTHOR

Derived from the FreeBSD manual pages written by Robert N M Watson ⟨rwatson@FreeBSD.org⟩, and adapted for Linux by Andreas Gruenbacher ⟨andreas.gruenbacher@gmail.com⟩.