faccessat(2)

1access(2)                        System Calls                        access(2)
2
3
4

NAME

6       access, faccessat - determine accessibility of a file
7

SYNOPSIS

9       #include <unistd.h>
10       #include <sys/fcntl.h>
11
12       int access(const char *path, int amode);
13
14
15       int faccessat(int fd, const char *path, int amode, int flag);
16
17

DESCRIPTION

19       The  access() function checks the file named by the pathname pointed to
20       by the path argument for accessibility according  to  the  bit  pattern
21       contained  in  amode,  using the real user ID in place of the effective
22       user ID and the real group ID in place of the effective group ID.  This
23       allows  a  setuid process to verify that the user running it would have
24       had permission to access this file.
25
26
27       The value of amode is either the bitwise inclusive  OR  of  the  access
28       permissions  to  be  checked  (R_OK, W_OK, X_OK) or the existence test,
29       F_OK.
30
31
32       These constants are defined in <unistd.h> as follows:
33
34       R_OK    Test for read permission.
35
36
37       W_OK    Test for write permission.
38
39
40       X_OK    Test for execute or search permission.
41
42
43       F_OK    Check existence of file
44
45
46
47       See Intro(2) for additional information about "File Access Permission".
48
49
50       If any access permissions are to be checked, each will be checked indi‐
51       vidually,  as  described  in  Intro(2).  If the process has appropriate
52       privileges, an implementation may indicate success  for  X_OK  even  if
53       none of the execute file permission bits are set.
54
55
56       The faccessat() function is equivalent to the access() function, except
57       in the case where path specifies a relative path. In this case the file
58       whose  accessibility  is  to  be  determined is located relative to the
59       directory associated with the file descriptor fd instead of the current
60       working directory.
61
62
63       If  faccessat()  is  passed  in  the  fd  parameter  the  special value
64       AT_FDCWD, defined in <fcntl.h>, the current working directory  is  used
65       and the behavior is identical to a call to access().
66
67
68       Values for flag are constructed by a bitwise-inclusive OR of flags from
69       the following list, defined in <fcntl.h>:
70
71       AT_EACCESS    The checks for  accessibility  are  performed  using  the
72                     effective user and group IDs instead of the real user and
73                     group ID as required in a call to access().
74
75

RETURN VALUES

77       If the requested access is permitted, access()  and  faccessat()succeed
78       and  return  0.  Otherwise, −1 is returned and errno is set to indicate
79       the error.
80

ERRORS

82       The access() and faccessat() functions will fail if:
83
84       EACCES          Permission bits of the file  mode  do  not  permit  the
85                       requested  access,  or search permission is denied on a
86                       component of the path prefix.
87
88
89       EFAULT          The path argument points to an illegal address.
90
91
92       EINTR           A signal was caught during the access() function.
93
94
95       ELOOP           Too many symbolic links were encountered  in  resolving
96                       path, or loop exists in symbolic links encountered dur‐
97                       ing resolution of the path argument.
98
99
100       ENAMETOOLONG    The length of the path argument exceeds {PATH_MAX},  or
101                       a  pathname  component  is longer than {NAME_MAX} while
102                       _POSIX_NO_TRUNC is in effect.
103
104
105       ENOENT          A component of path does not name an existing  file  or
106                       path is an empty string.
107
108
109       ENOLINK         The  path  argument  points to a remote machine and the
110                       link to that machine is no longer active.
111
112
113       ENOTDIR         A component of the path prefix is not a directory.
114
115
116       ENXIO           The path argument points to a character or block device
117                       special  file  and  the  corresponding  device has been
118                       retired by the fault management framework.
119
120
121       EROFS           Write access is requested for a  file  on  a  read-only
122                       file system.
123
124
125
126       The faccessat() function will fail if:
127
128       EBADF    The path argument does not specify an absolute path and the fd
129                argument is neither AT_FDCWD nor a valid file descriptor  open
130                for reading or searching.
131
132
133
134       The access() and faccessat() functions may fail if:
135
136       EINVAL          The value of the amode argument is invalid.
137
138
139       ENAMETOOLONG    Pathname  resolution  of  a  symbolic  link produced an
140                       intermediate result whose length exceeds {PATH_MAX}.
141
142
143       ETXTBSY         Write access is requested for a pure procedure  (shared
144                       text) file that is being executed.
145
146
147
148       The faccessat() function may fail if:
149
150       EINVAL     The value of the flag argument is not valid.
151
152
153       ENOTDIR    The  path argument is not an absolute path and fd is neither
154                  AT_FDCWD nor a file descriptor associated with a directory.
155
156

USAGE

158       Additional values of amode other than the set defined in  the  descrip‐
159       tion  might be valid, for example, if a system has extended access con‐
160       trols.
161
162
163       The purpose of the faccessat() function is to enable  the  checking  of
164       the  accessibility of files in directories other than the current work‐
165       ing directory without exposure to race conditions. Any part of the path
166       of a file could be changed in parallel to a call to access(), resulting
167       in unspecified behavior. By opening a file descriptor  for  the  target
168       directory and using the faccessat() function, it can be guaranteed that
169       the file tested for accessibility is located relative  to  the  desired
170       directory.
171

ATTRIBUTES

173       See attributes(5) for descriptions of the following attributes:
174
175
176
177
178       ┌─────────────────────────────┬─────────────────────────────┐
179       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
180       ├─────────────────────────────┼─────────────────────────────┤
181       │Interface Stability          │Committed                    │
182       ├─────────────────────────────┼─────────────────────────────┤
183       │MT-Level                     │Async-Signal-Safe            │
184       ├─────────────────────────────┼─────────────────────────────┤
185       │Standard                     │See below.                   │
186       └─────────────────────────────┴─────────────────────────────┘
187
188
189       For access(), see standards(5).
190