1 .\" Copyright (c) 1980, 1991, 1993, 1994
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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
28 .\" @(#)stat.2 8.4 (Berkeley) 5/1/95
29 .\" $FreeBSD: src/lib/libc/sys/stat.2,v 1.16.2.7 2001/12/14 18:34:01 ru Exp $
31 .Dd September 13, 2019
46 .Fn stat "const char *path" "struct stat *sb"
48 .Fn lstat "const char *path" "struct stat *sb"
50 .Fn fstat "int fd" "struct stat *sb"
52 .Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag"
56 system call obtains information about the file pointed to by
58 Read, write or execute
59 permission of the named file is not required, but all directories
60 listed in the path name leading to the file must be searchable.
65 except in the case where the named file is a symbolic link,
68 returns information about the link,
71 returns information about the file the link references.
75 system call obtains the same information about an open file
76 known by the file descriptor
81 system call is equivalent to
85 except in the case where the
87 specifies a relative path.
88 In this case the status is retrieved from a file relative to
89 the directory associated with the file descriptor
91 instead of the current working directory.
95 are constructed by a bitwise-inclusive OR of flags from the following list,
98 .Bl -tag -width indent
99 .It Dv AT_SYMLINK_NOFOLLOW
102 names a symbolic link, the status of the symbolic link is returned.
107 is passed the special value
111 parameter, the current working directory is used and the behavior is
112 identical to a call to
116 respectively, depending on whether or not the
117 .Dv AT_SYMLINK_NOFOLLOW
123 argument is a pointer to a
129 and into which information is placed concerning the file.
132 ino_t st_ino; /* inode's number */
133 nlink_t st_nlink; /* number of hard links */
134 dev_t st_dev; /* inode's device */
135 mode_t st_mode; /* inode protection mode */
136 uint16_t st_padding1;
137 uid_t st_uid; /* user ID of the file's owner */
138 gid_t st_gid; /* group ID of the file's group */
139 dev_t st_rdev; /* device type */
140 struct timespec st_atim; /* time of last access */
141 struct timespec st_mtim; /* time of last data modification */
142 struct timespec st_ctim; /* time of last file status change */
143 off_t st_size; /* file size, in bytes */
144 blkcnt_t st_blocks; /* blocks allocated for file */
145 u_int32_t __old_st_blksize; /* (for old ABI compat only, do not use) */
146 u_int32_t st_flags; /* user defined flags for file */
147 u_int32_t st_gen; /* file generation number */
149 blksize_t st_blksize; /* optimal blocksize for I/O */
150 int64_t st_qspare2; /* (placeholder for future, do not use) */
154 The time-related fields of
157 .Bl -tag -width ".Fa st_mtime"
159 Time when file data last accessed.
169 Time when file data last modified.
177 Time when file status was last changed (inode data modification).
191 For compatibility with earlier versions of the
193 standard, the following macros are defined:
195 #define st_atime st_atim.tv_sec
196 #define st_mtime st_mtim.tv_sec
197 #define st_ctime st_ctim.tv_sec
200 The size-related fields of the
203 .Bl -tag -width ".Fa st_blksize"
205 The optimal I/O block size for the file.
207 The actual number of blocks allocated for the file in 512-byte units.
208 As short symbolic links are stored in the inode, this number may
212 The status information word
214 has the following bits:
216 #define S_IFMT 0170000 /* type of file */
217 #define S_IFIFO 0010000 /* named pipe (fifo) */
218 #define S_IFCHR 0020000 /* character special */
219 #define S_IFDIR 0040000 /* directory */
220 #define S_IFBLK 0060000 /* block special */
221 #define S_IFREG 0100000 /* regular */
222 #define S_IFLNK 0120000 /* symbolic link */
223 #define S_IFSOCK 0140000 /* socket */
224 #define S_IFWHT 0160000 /* whiteout */
225 #define S_ISUID 0004000 /* set user id on execution */
226 #define S_ISGID 0002000 /* set group id on execution */
227 #define S_ISVTX 0001000 /* save swapped text even after use */
228 #define S_IRUSR 0000400 /* read permission, owner */
229 #define S_IWUSR 0000200 /* write permission, owner */
230 #define S_IXUSR 0000100 /* execute/search permission, owner */
233 For a list of access modes, see
241 Previous versions of the system used different types for the
258 Search permission is denied for a component of the path prefix.
260 An I/O error occurred while reading from or writing to the file system.
262 Too many symbolic links were encountered in translating the pathname.
263 .It Bq Er ENAMETOOLONG
264 A component of a pathname exceeded 255 characters,
265 or an entire path name exceeded 1023 characters.
267 The named file does not exist.
269 A component of the path prefix is not a directory.
274 points to an invalid address.
282 is not a valid open file descriptor.
285 points to an invalid address.
287 An I/O error occurred while reading from or writing to the file system.
302 system calls are expected to conform to
309 system call appeared in
313 system call appeared in
317 system call appeared in
322 to a socket (and thus to a pipe)
323 returns a zeroed buffer,
324 except for the blocksize field,
325 and a unique device and inode number.