1FSTATAT(3P)                POSIX Programmer's Manual               FSTATAT(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       fstatat, lstat, stat — get file status
13

SYNOPSIS

15       #include <fcntl.h>
16       #include <sys/stat.h>
17
18       int fstatat(int fd, const char *restrict path,
19           struct stat *restrict buf, int flag);
20       int lstat(const char *restrict path, struct stat *restrict buf);
21       int stat(const char *restrict path, struct stat *restrict buf);
22

DESCRIPTION

24       The stat() function shall obtain information about the named  file  and
25       write  it to the area pointed to by the buf argument. The path argument
26       points to a pathname naming a file. Read, write, or execute  permission
27       of  the  named  file  is  not required. An implementation that provides
28       additional or alternate  file  access  control  mechanisms  may,  under
29       implementation-defined conditions, cause stat() to fail. In particular,
30       the system may deny the existence of the file specified by path.
31
32       If the named file is a symbolic link, the stat()  function  shall  con‐
33       tinue  pathname resolution using the contents of the symbolic link, and
34       shall return information pertaining to the resulting file if  the  file
35       exists.
36
37       The  buf  argument  is a pointer to a stat structure, as defined in the
38       <sys/stat.h> header, into which information is  placed  concerning  the
39       file.
40
41       The  stat() function shall update any time-related fields (as described
42       in the Base Definitions volume of POSIX.1‐2017, Section 4.9, File Times
43       Update), before writing into the stat structure.
44
45       If  the  named file is a shared memory object, the implementation shall
46       update in the stat structure pointed to by the buf argument the st_uid,
47       st_gid,  st_size,  and  st_mode  fields, and only the S_IRUSR, S_IWUSR,
48       S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file  permission  bits  need  be
49       valid. The implementation may update other fields and flags.
50
51       If  the  named  file is a typed memory object, the implementation shall
52       update in the stat structure pointed to by the buf argument the st_uid,
53       st_gid,  st_size,  and  st_mode  fields, and only the S_IRUSR, S_IWUSR,
54       S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file  permission  bits  need  be
55       valid. The implementation may update other fields and flags.
56
57       For  all  other  file types defined in this volume of POSIX.1‐2017, the
58       structure members st_mode, st_ino,  st_dev,  st_uid,  st_gid,  st_atim,
59       st_ctim,  and st_mtim shall have meaningful values and the value of the
60       member st_nlink shall be set to the number of links to the file.
61
62       The lstat() function shall be equivalent to stat(),  except  when  path
63       refers  to  a symbolic link. In that case lstat() shall return informa‐
64       tion about the link, while stat() shall return  information  about  the
65       file the link references.
66
67       For  symbolic links, the st_mode member shall contain meaningful infor‐
68       mation when used with the file type  macros.  The  file  mode  bits  in
69       st_mode  are unspecified. The structure members st_ino, st_dev, st_uid,
70       st_gid, st_atim, st_ctim, and st_mtim shall have meaningful values  and
71       the  value  of the st_nlink member shall be set to the number of (hard)
72       links to the symbolic link.  The value of the st_size member  shall  be
73       set  to  the  length of the pathname contained in the symbolic link not
74       including any terminating null byte.
75
76       The fstatat() function shall be equivalent to  the  stat()  or  lstat()
77       function,  depending  on  the  value of flag (see below), except in the
78       case where path specifies a relative path.  In  this  case  the  status
79       shall  be  retrieved  from  a file relative to the directory associated
80       with the file descriptor fd instead of the current  working  directory.
81       If  the  access  mode  of the open file description associated with the
82       file descriptor is not  O_SEARCH,  the  function  shall  check  whether
83       directory  searches  are permitted using the current permissions of the
84       directory underlying  the  file  descriptor.  If  the  access  mode  is
85       O_SEARCH, the function shall not perform the check.
86
87       Values for flag are constructed by a bitwise-inclusive OR of flags from
88       the following list, defined in <fcntl.h>:
89
90       AT_SYMLINK_NOFOLLOW
91             If path names a symbolic link, the status of the symbolic link is
92             returned.
93
94       If  fstatat() is passed the special value AT_FDCWD in the fd parameter,
95       the current working directory shall be used and the behavior  shall  be
96       identical  to  a  call  to stat() or lstat() respectively, depending on
97       whether or not the AT_SYMLINK_NOFOLLOW bit is set in flag.
98

RETURN VALUE

100       Upon successful completion, these functions shall return 0.  Otherwise,
101       these functions shall return -1 and set errno to indicate the error.
102

ERRORS

104       These functions shall fail if:
105
106       EACCES Search permission is denied for a component of the path prefix.
107
108       EIO    An error occurred while reading from the file system.
109
110       ELOOP  A loop exists in symbolic links encountered during resolution of
111              the path argument.
112
113       ENAMETOOLONG
114              The  length  of  a  component  of  a  pathname  is  longer  than
115              {NAME_MAX}.
116
117       ENOENT A component of path does not name an existing file or path is an
118              empty string.
119
120       ENOTDIR
121              A component of the path prefix names an existing  file  that  is
122              neither  a  directory nor a symbolic link to a directory, or the
123              path argument contains at least one  non-<slash>  character  and
124              ends  with  one or more trailing <slash> characters and the last
125              pathname component names an existing  file  that  is  neither  a
126              directory nor a symbolic link to a directory.
127
128       EOVERFLOW
129              The  file size in bytes or the number of blocks allocated to the
130              file or the file serial number cannot be  represented  correctly
131              in the structure pointed to by buf.
132
133       The fstatat() function shall fail if:
134
135       EACCES The  access mode of the open file description associated with fd
136              is not O_SEARCH and the permissions of the directory  underlying
137              fd do not permit directory searches.
138
139       EBADF  The  path  argument does not specify an absolute path and the fd
140              argument is neither AT_FDCWD nor a valid  file  descriptor  open
141              for reading or searching.
142
143       ENOTDIR
144              The  path  argument  is  not  an  absolute path and fd is a file
145              descriptor associated with a non-directory file.
146
147       These functions may fail if:
148
149       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
150              resolution of the path argument.
151
152       ENAMETOOLONG
153              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
154              tion of a symbolic link produced an intermediate result  with  a
155              length that exceeds {PATH_MAX}.
156
157       EOVERFLOW
158              A  value  to  be stored would overflow one of the members of the
159              stat structure.
160
161       The fstatat() function may fail if:
162
163       EINVAL The value of the flag argument is not valid.
164
165       The following sections are informative.
166

EXAMPLES

168   Obtaining File Status Information
169       The following example shows how to obtain file status information for a
170       file  named  /home/cnd/mod1.   The structure variable buffer is defined
171       for the stat structure.
172
173
174           #include <sys/types.h>
175           #include <sys/stat.h>
176           #include <fcntl.h>
177
178           struct stat buffer;
179           int         status;
180           ...
181           status = stat("/home/cnd/mod1", &buffer);
182
183   Getting Directory Information
184       The following example fragment gets status information for  each  entry
185       in a directory. The call to the stat() function stores file information
186       in the stat structure pointed to by statbuf.  The lines that follow the
187       stat() call format the fields in the stat structure for presentation to
188       the user of the program.
189
190
191           #include <sys/types.h>
192           #include <sys/stat.h>
193           #include <dirent.h>
194           #include <pwd.h>
195           #include <grp.h>
196           #include <time.h>
197           #include <locale.h>
198           #include <langinfo.h>
199           #include <stdio.h>
200           #include <stdint.h>
201
202           struct dirent  *dp;
203           struct stat     statbuf;
204           struct passwd  *pwd;
205           struct group   *grp;
206           struct tm      *tm;
207           char            datestring[256];
208           ...
209           /* Loop through directory entries. */
210           while ((dp = readdir(dir)) != NULL) {
211
212               /* Get entry's information. */
213               if (stat(dp->d_name, &statbuf) == -1)
214                   continue;
215
216               /* Print out type, permissions, and number of links. */
217               printf("%10.10s", sperm (statbuf.st_mode));
218               printf("%4d", statbuf.st_nlink);
219
220               /* Print out owner's name if it is found using getpwuid(). */
221               if ((pwd = getpwuid(statbuf.st_uid)) != NULL)
222                   printf(" %-8.8s", pwd->pw_name);
223               else
224                   printf(" %-8d", statbuf.st_uid);
225
226               /* Print out group name if it is found using getgrgid(). */
227               if ((grp = getgrgid(statbuf.st_gid)) != NULL)
228                   printf(" %-8.8s", grp->gr_name);
229               else
230                   printf(" %-8d", statbuf.st_gid);
231
232               /* Print size of file. */
233               printf(" %9jd", (intmax_t)statbuf.st_size);
234
235               tm = localtime(&statbuf.st_mtime);
236
237               /* Get localized date string. */
238               strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm);
239
240               printf(" %s %s\n", datestring, dp->d_name);
241           }
242
243   Obtaining Symbolic Link Status Information
244       The following example shows how to obtain status information for a sym‐
245       bolic  link  named  /modules/pass1.   The  structure variable buffer is
246       defined for the stat structure. If  the  path  argument  specified  the
247       pathname for the file pointed to by the symbolic link (/home/cnd/mod1),
248       the results of calling the function would be the same as those returned
249       by a call to the stat() function.
250
251
252           #include <sys/stat.h>
253
254           struct stat buffer;
255           int status;
256           ...
257           status = lstat("/modules/pass1", &buffer);
258

APPLICATION USAGE

260       None.
261

RATIONALE

263       The  intent  of the paragraph describing ``additional or alternate file
264       access control mechanisms'' is to allow a secure implementation where a
265       process  with  a  label  that does not dominate the file's label cannot
266       perform a stat() function. This is not related to  read  permission;  a
267       process with a label that dominates the file's label does not need read
268       permission.  An implementation that supports write-up operations  could
269       fail  fstat() function calls even though it has a valid file descriptor
270       open for writing.
271
272       The purpose of the fstatat() function is to obtain the status of  files
273       in  directories  other than the current working directory without expo‐
274       sure to race conditions. Any part of  the  path  of  a  file  could  be
275       changed  in  parallel  to  a  call  to stat(), resulting in unspecified
276       behavior. By opening a file descriptor for  the  target  directory  and
277       using  the  fstatat()  function  it can be guaranteed that the file for
278       which status is returned is located relative to the desired directory.
279

FUTURE DIRECTIONS

281       None.
282

SEE ALSO

284       access(), chmod(), fdopendir(), fstat(), mknod(), readlink(), symlink()
285
286       The Base Definitions volume of POSIX.1‐2017, Section  4.9,  File  Times
287       Update, <fcntl.h>, <sys_stat.h>, <sys_types.h>
288
290       Portions  of  this text are reprinted and reproduced in electronic form
291       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
292       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
293       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
294       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
295       event of any discrepancy between this version and the original IEEE and
296       The  Open Group Standard, the original IEEE and The Open Group Standard
297       is the referee document. The original Standard can be  obtained  online
298       at http://www.opengroup.org/unix/online.html .
299
300       Any  typographical  or  formatting  errors that appear in this page are
301       most likely to have been introduced during the conversion of the source
302       files  to  man page format. To report such errors, see https://www.ker
303       nel.org/doc/man-pages/reporting_bugs.html .
304
305
306
307IEEE/The Open Group                  2017                          FSTATAT(3P)
Impressum