1.\" Copyright (c) 1980, 1991, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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. 15.\" 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 26.\" SUCH DAMAGE. 27.\" 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 $ 30.\" 31.Dd August 3, 2016 32.Dt STAT 2 33.Os 34.Sh NAME 35.Nm stat , 36.Nm lstat , 37.Nm fstat , 38.Nm fstatat 39.Nd get file status 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/stat.h 45.Ft int 46.Fn stat "const char *path" "struct stat *sb" 47.Ft int 48.Fn lstat "const char *path" "struct stat *sb" 49.Ft int 50.Fn fstat "int fd" "struct stat *sb" 51.Ft int 52.Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag" 53.Sh DESCRIPTION 54The 55.Fn stat 56system call obtains information about the file pointed to by 57.Fa path . 58Read, write or execute 59permission of the named file is not required, but all directories 60listed in the path name leading to the file must be searchable. 61.Pp 62.Fn Lstat 63is like 64.Fn stat 65except in the case where the named file is a symbolic link, 66in which case 67.Fn lstat 68returns information about the link, 69while 70.Fn stat 71returns information about the file the link references. 72.Pp 73The 74.Fn fstat 75system call obtains the same information about an open file 76known by the file descriptor 77.Fa fd . 78.Pp 79The 80.Fn fstatat 81system call is equivalent to 82.Fn stat 83and 84.Fn lstat 85except in the case where the 86.Fa path 87specifies a relative path. 88In this case the status is retrieved from a file relative to 89the directory associated with the file descriptor 90.Fa fd 91instead of the current working directory. 92.Pp 93The values for the 94.Fa flag 95are constructed by a bitwise-inclusive OR of flags from the following list, 96defined in 97.In fcntl.h : 98.Bl -tag -width indent 99.It Dv AT_SYMLINK_NOFOLLOW 100If 101.Fa path 102names a symbolic link, the status of the symbolic link is returned. 103.El 104.Pp 105If 106.Fn fstatat 107is passed the special value 108.Dv AT_FDCWD 109in the 110.Fa fd 111parameter, the current working directory is used and the behavior is 112identical to a call to 113.Fn stat 114or 115.Fn lstat 116respectively, depending on whether or not the 117.Dv AT_SYMLINK_NOFOLLOW 118bit is set in 119.Fa flag . 120.Pp 121The 122.Fa sb 123argument is a pointer to a 124.Vt stat 125structure 126as defined by 127.In sys/stat.h 128(shown below) 129and into which information is placed concerning the file. 130.Bd -literal 131struct stat { 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 int64_t st_blocks; /* blocks allocated for file */ 145 u_int32_t st_blksize; /* optimal blocksize for I/O */ 146 u_int32_t st_flags; /* user defined flags for file */ 147 u_int32_t st_gen; /* file generation number */ 148 int32_t st_lspare; 149 int64_t st_qspare1; /* was recursive change detect */ 150 int64_t st_qspare2; 151}; 152.Ed 153.Pp 154The time-related fields of 155.Vt struct stat 156are as follows: 157.Bl -tag -width ".Fa st_mtime" 158.It Fa st_atim 159Time when file data last accessed. 160Changed by the 161.Xr execve 2 , 162.Xr mknod 2 , 163.Xr mmap 2 , 164.Xr read 2 165and 166.Xr utimes 2 167system calls. 168.It Fa st_mtim 169Time when file data last modified. 170Changed by the 171.Xr mknod 2 , 172.Xr utimes 2 173and 174.Xr write 2 175system calls. 176.It Fa st_ctim 177Time when file status was last changed (inode data modification). 178Changed by the 179.Xr chmod 2 , 180.Xr chown 2 , 181.Xr link 2 , 182.Xr mknod 2 , 183.Xr rename 2 , 184.Xr unlink 2 , 185.Xr utimes 2 186and 187.Xr write 2 188system calls. 189.El 190.Pp 191For compatibility with earlier versions of the 192.Tn POSIX 193standard, the following macros are defined: 194.Bd -literal 195#define st_atime st_atim.tv_sec 196#define st_mtime st_mtim.tv_sec 197#define st_ctime st_ctim.tv_sec 198.Ed 199.Pp 200The size-related fields of the 201.Vt struct stat 202are as follows: 203.Bl -tag -width ".Fa st_blksize" 204.It Fa st_blksize 205The optimal I/O block size for the file. 206.It Fa st_blocks 207The actual number of blocks allocated for the file in 512-byte units. 208As short symbolic links are stored in the inode, this number may 209be zero. 210.El 211.Pp 212The status information word 213.Fa st_mode 214has the following bits: 215.Bd -literal 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 */ 231.Ed 232.Pp 233For a list of access modes, see 234.In sys/stat.h , 235.Xr access 2 236and 237.Xr chmod 2 . 238.Sh RETURN VALUES 239.Rv -std 240.Sh COMPATIBILITY 241Previous versions of the system used different types for the 242.Fa st_dev , 243.Fa st_uid , 244.Fa st_gid , 245.Fa st_rdev , 246.Fa st_size , 247.Fa st_blksize 248and 249.Fa st_blocks 250fields. 251.Sh ERRORS 252.Fn Stat 253and 254.Fn lstat 255will fail if: 256.Bl -tag -width Er 257.It Bq Er EACCES 258Search permission is denied for a component of the path prefix. 259.It Bq Er EIO 260An I/O error occurred while reading from or writing to the file system. 261.It Bq Er ELOOP 262Too many symbolic links were encountered in translating the pathname. 263.It Bq Er ENAMETOOLONG 264A component of a pathname exceeded 255 characters, 265or an entire path name exceeded 1023 characters. 266.It Bq Er ENOENT 267The named file does not exist. 268.It Bq Er ENOTDIR 269A component of the path prefix is not a directory. 270.It Bq Er EFAULT 271.Fa sb 272or 273.Em name 274points to an invalid address. 275.El 276.Pp 277.Fn Fstat 278will fail if: 279.Bl -tag -width Er 280.It Bq Er EBADF 281.Fa fd 282is not a valid open file descriptor. 283.It Bq Er EFAULT 284.Fa sb 285points to an invalid address. 286.It Bq Er EIO 287An I/O error occurred while reading from or writing to the file system. 288.El 289.Sh SEE ALSO 290.Xr access 2 , 291.Xr chmod 2 , 292.Xr chown 2 , 293.Xr statfs 2 , 294.Xr statvfs 2 , 295.Xr utimes 2 , 296.Xr symlink 7 297.Sh STANDARDS 298The 299.Fn stat 300and 301.Fn fstat 302system calls are expected to conform to 303.St -p1003.1-90 . 304.Sh HISTORY 305A 306.Fn stat 307and a 308.Fn fstat 309system call appeared in 310.At v7 . 311A 312.Fn lstat 313system call appeared in 314.Bx 4.2 . 315The 316.Fn fstatat 317system call appeared in 318.Dx 2.3 . 319.Sh BUGS 320Applying 321.Fn fstat 322to a socket (and thus to a pipe) 323returns a zeroed buffer, 324except for the blocksize field, 325and a unique device and inode number. 326