![Coreutils stat screenshot](https://upload.wikimedia.org/wikipedia/commons/d/d6/Coreutils_stat_screenshot.png)
is a
Unix
Unix (; trademarked as UNIX) is a family of multitasking, multiuser computer operating systems that derive from the original AT&T Unix, whose development started in 1969 at the Bell Labs research center by Ken Thompson, Dennis Ritchie, and ot ...
system call
In computing, a system call (commonly abbreviated to syscall) is the programmatic way in which a computer program requests a service from the operating system on which it is executed. This may include hardware-related services (for example, acc ...
that returns
file attribute File attributes are a type of meta-data that describe and may modify how files and/or directories in a filesystem behave. Typical file attributes may, for example, indicate or specify whether a file is visible, modifiable, compressed, or encrypted. ...
s about an
inode
The inode (index node) is a data structure in a Unix-style file system that describes a file-system object such as a file or a directory. Each inode stores the attributes and disk block locations of the object's data. File-system object attribute ...
. The semantics of vary between
operating system
An operating system (OS) is system software that manages computer hardware, software resources, and provides common services for computer programs.
Time-sharing operating systems schedule tasks for efficient use of the system and may also in ...
s. As an example,
Unix
Unix (; trademarked as UNIX) is a family of multitasking, multiuser computer operating systems that derive from the original AT&T Unix, whose development started in 1969 at the Bell Labs research center by Ken Thompson, Dennis Ritchie, and ot ...
command uses this system call to retrieve information on files that includes:
* atime: time of last access ()
* mtime:
time
Time is the continued sequence of existence and events that occurs in an apparently irreversible succession from the past, through the present, into the future. It is a component quantity of various measurements used to sequence events, to ...
of last modification ()
* ctime: time of last status change ()
stat
appeared in
Version 1 Unix
The term "Research Unix" refers to early versions of the Unix operating system for DEC PDP-7, PDP-11, VAX and Interdata 7/32 and 8/32 computers, developed in the Bell Labs Computing Sciences Research Center (CSRC).
History
The term ''Resear ...
. It is among the few original Unix
system call
In computing, a system call (commonly abbreviated to syscall) is the programmatic way in which a computer program requests a service from the operating system on which it is executed. This may include hardware-related services (for example, acc ...
s to change, with
Version 4's addition of
group permissions and larger
file size
File size is a measure of how much data a computer file contains or, alternately, how much storage it consumes. Typically, file size is expressed in units of measurement based on the byte. By convention, file size units use either a metric prefix ...
.
stat() functions
The
C POSIX library
The C POSIX library is a specification of a C standard library for POSIX systems. It was developed at the same time as the ANSI C standard. Some effort was made to make POSIX compatible with standard C
ANSI C, ISO C, and Standard C are succes ...
header , found on
POSIX
The Portable Operating System Interface (POSIX) is a family of standards specified by the IEEE Computer Society for maintaining compatibility between operating systems. POSIX defines both the system- and user-level application programming interf ...
and other
Unix-like
A Unix-like (sometimes referred to as UN*X or *nix) operating system is one that behaves in a manner similar to a Unix system, although not necessarily conforming to or being certified to any version of the Single UNIX Specification. A Unix-li ...
operating systems, declares the
stat()
functions, as well as related functions called
fstat()
and
lstat()
. The functions take a
struct stat
buffer argument, which is used to return the file attributes. On success, the functions return zero, and on error, −1 is returned and
errno
errno.h is a header file in the standard library of the C programming language. It defines macros for reporting and retrieving error conditions using the symbol errno (short for "error number").International Standard for Programming Language C ...
is set appropriately.
The
stat()
and
lstat()
functions take a
filename
A filename or file name is a name used to uniquely identify a computer file in a directory structure. Different file systems impose different restrictions on filename lengths.
A filename may (depending on the file system) include:
* name &ndas ...
argument. If the file is a
symbolic link
In computing, a symbolic link (also symlink or soft link) is a file whose purpose is to point to a file or directory (called the "target") by specifying a path thereto.
Symbolic links are supported by POSIX and by most Unix-like operating system ...
,
stat()
returns attributes of the eventual target of the link, while
lstat()
returns attributes of the link itself. The
fstat()
function takes a
file descriptor
In Unix and Unix-like computer operating systems, a file descriptor (FD, less frequently fildes) is a process-unique identifier (handle) for a file or other input/output resource, such as a pipe or network socket.
File descriptors typically have ...
argument instead, and returns attributes of the file that it identifies.
The family of functions was extended to implement
large file support
Large-file support (LFS) is the term frequently applied to the ability to create files larger than either 2 or 4 GiB on 32-bit filesystems.
Details
Traditionally, many operating systems and their underlying file system implementations use ...
. Functions named
stat64()
,
lstat64()
and
fstat64()
return attributes in a
struct stat64
structure, which represents file sizes with a 64-bit type, allowing the functions to work on files 2 GiB and larger (up to 8 EiB). When the
_FILE_OFFSET_BITS
macro is defined to 64, these 64-bit functions are available under the original names.
The functions are defined as:
int stat(const char *filename, struct stat *buf);
int lstat(const char *filename, struct stat *buf);
int fstat(int filedesc, struct stat *buf);
stat structure
This structure is defined in header file as follows, although implementations are free to define additional fields:
struct stat ;
POSIX.1 does not require
st_rdev
,
st_blocks
and
st_blksize
members; these fields are defined as part of XSI option in the Single Unix Specification.
In older versions of POSIX.1 standard, the time-related fields were defined as
st_atime
,
st_mtime
and
st_ctime
, and were of type
time_t
. Since the 2008 version of the standard, these fields were renamed to
st_atim
,
st_mtim
and
st_ctim
, respectively, of type struct
timespec
, since this structure provides a higher resolution time unit. For the sake of compatibility, implementations can define the old names in terms of the
tv_sec
member of
struct timespec
. For example,
st_atime
can be defined as
st_atim.tv_sec
.
The
struct stat
structure includes at least the following members:
*
st_dev
identifier of
device containing file
*
st_ino
inode
The inode (index node) is a data structure in a Unix-style file system that describes a file-system object such as a file or a directory. Each inode stores the attributes and disk block locations of the object's data. File-system object attribute ...
number
*
st_mode
protection
mode
Mode ( la, modus meaning "manner, tune, measure, due measure, rhythm, melody") may refer to:
Arts and entertainment
* '' MO''D''E (magazine)'', a defunct U.S. women's fashion magazine
* ''Mode'' magazine, a fictional fashion magazine which is ...
; see also
Unix permissions
Most file systems include attributes of files and directories that control the ability of users to read, change, navigate, and execute the contents of the file system. In some cases, menu options or functions may be made visible or hidden dependin ...
*
st_nlink
reference count
In computer science, reference counting is a programming technique of storing the number of references, pointers, or handles to a resource, such as an object, a block of memory, disk space, and others.
In garbage collection algorithms, referen ...
of
hard link
In computing, a hard link is a directory entry (in a directory-based file system) that associates a name with a file. Thus, each file must have at least one hard link. Creating additional hard links for a file makes the contents of that file acc ...
s
*
st_uid
user identifier
Unix-like operating systems identify a user by a value called a user identifier, often abbreviated to user ID or UID. The UID, along with the group identifier (GID) and other access control criteria, is used to determine which system resources a us ...
of owner
*
st_gid
group identifier
In Unix-like systems, multiple users can be put into ''groups''. POSIX and conventional Unix file system permissions are organized into three classes, ''user'', ''group'', and ''others''. The use of groups allows additional abilities to be delega ...
of owner
*
st_rdev
device identifier (if
special file
In Unix-like operating systems, a device file or special file is an interface to a device driver that appears in a file system as if it were an ordinary file. There are also special files in DOS, OS/2, and Windows. These special files allow ...
)
*
st_size
total
file size
File size is a measure of how much data a computer file contains or, alternately, how much storage it consumes. Typically, file size is expressed in units of measurement based on the byte. By convention, file size units use either a metric prefix ...
, in bytes
*
st_atime
time of last access
*
st_mtime
time of last modification
*
st_ctime
time of last status change
*
st_blksize
preferred
block
Block or blocked may refer to:
Arts, entertainment and media Broadcasting
* Block programming, the result of a programming strategy in broadcasting
* W242BX, a radio station licensed to Greenville, South Carolina, United States known as ''96.3 ...
size for file system I/O, which can depend upon both the system and the type of file system
*
st_blocks
number of blocks allocated in multiples of
DEV_BSIZE
(usually 512 bytes).
The
st_mode
field is a
bit field
A bit field is a data structure that consists of one or more adjacent bits which have been allocated for specific purposes, so that any single bit or group of bits within the structure can be set or inspected. A bit field is most commonly used to r ...
. It combines the file access
modes
Mode ( la, modus meaning "manner, tune, measure, due measure, rhythm, melody") may refer to:
Arts and entertainment
* '' MO''D''E (magazine)'', a defunct U.S. women's fashion magazine
* ''Mode'' magazine, a fictional fashion magazine which is ...
and also indicates any
special file type. There are many macros to work with the different mode flags and file types.
Criticism of atime
Reading a file changes its eventually requiring a disk ''write,'' which has been criticized as it is inconsistent with a read only file system. File system cache may significantly reduce this activity to one disk write per cache flush.
Linux kernel
The Linux kernel is a free and open-source, monolithic, modular, multitasking, Unix-like operating system kernel. It was originally authored in 1991 by Linus Torvalds for his i386-based PC, and it was soon adopted as the kernel for the GNU ope ...
developer
Ingo Molnár
Ingo Molnár, employed by Red Hat as of May 2013, is a Hungarian Linux hacker. He is known for his contributions to the operating system in terms of security and performance.
Life and career
Molnár studied at Eötvös Loránd University.
Wo ...
publicly criticized the concept and performance impact of atime in 2007, and in 2009, the mount option had become the default, which addresses this criticism. The behavior behind the mount option offers sufficient performance for most purposes and should not break any significant applications, as it has been extensively discussed. Initially, only updated atime if atime < mtime or atime < ctime; that was subsequently modified to update atimes that were 24 hours old or older, so that and Debian's popularity counter (popcon) would behave properly.
Current versions of the Linux kernel support four mount options, which can be specified in
fstab
fstab (after ''file systems table'') is a system file commonly found in the directory /etc on Unix and Unix-like computer systems. In Linux, it is part of the util-linux package. The fstab file typically lists all available disk partitions and ot ...
:
* (formerly , and formerly the default; as of 2.6.30) always update atime, which conforms to the behavior defined by POSIX
* ("relative atime", introduced in 2.6.20 and the default as of 2.6.30) only update atime under certain circumstances: if the previous atime is older than the mtime or ctime, or the previous atime is over 24 hours in the past
* never update atime of directories, but do update atime of other files
* never update atime of any file or directory; implies ; highest performance, but least compatible
* update atime according to specific circumstances laid out below
Current versions of
Linux
Linux ( or ) is a family of open-source Unix-like operating systems based on the Linux kernel, an operating system kernel first released on September 17, 1991, by Linus Torvalds. Linux is typically packaged as a Linux distribution, which ...
,
macOS
macOS (; previously OS X and originally Mac OS X) is a Unix operating system developed and marketed by Apple Inc. since 2001. It is the primary operating system for Apple's Mac computers. Within the market of desktop and lapt ...
,
Solaris
Solaris may refer to:
Arts and entertainment Literature, television and film
* ''Solaris'' (novel), a 1961 science fiction novel by Stanisław Lem
** ''Solaris'' (1968 film), directed by Boris Nirenburg
** ''Solaris'' (1972 film), directed by ...
,
FreeBSD
FreeBSD is a free and open-source Unix-like operating system descended from the Berkeley Software Distribution (BSD), which was based on Research Unix. The first version of FreeBSD was released in 1993. In 2005, FreeBSD was the most popular ...
, and
NetBSD
NetBSD is a free and open-source Unix operating system based on the Berkeley Software Distribution (BSD). It was the first open-source BSD descendant officially released after 386BSD was forked. It continues to be actively developed and is a ...
support a mount option in
/etc/fstab, which causes the atime field never to be updated. Turning off atime updating breaks
POSIX
The Portable Operating System Interface (POSIX) is a family of standards specified by the IEEE Computer Society for maintaining compatibility between operating systems. POSIX defines both the system- and user-level application programming interf ...
compliance, and some applications, such as
mbox
Mbox is a generic term for a family of related file formats used for holding collections of email messages. It was first implemented in Research Unix, Fifth Edition Unix.
All messages in an mbox mailbox are concatenated and stored as plain text ...
-driven "new
mail
The mail or post is a system for physically transporting postcards, letter (message), letters, and parcel (package), parcels. A postal service can be private or public, though many governments place restrictions on private systems. Since the mid ...
" notifications, and some file usage watching utilities, notably
tmpwatch.
The option on
OpenBSD
OpenBSD is a security-focused, free and open-source, Unix-like operating system based on the Berkeley Software Distribution (BSD). Theo de Raadt created OpenBSD in 1995 by forking NetBSD 1.0. According to the website, the OpenBSD project em ...
behaves more like Linux .
Version 4.0 of the
Linux kernel mainline
The Linux kernel is a free and open-source, monolithic, modular, multitasking, Unix-like operating system kernel. It was originally authored in 1991 by Linus Torvalds for his i386-based PC, and it was soon adopted as the kernel for the GNU o ...
, which was released on April 12, 2015, introduced the new mount option . It allows POSIX-style atime updates to be performed in-memory and flushed to disk together with some non-time-related I/O operations on the same file; atime updates are also flushed to disk when some of the
sync system calls are executed, or before the file's in-memory inode is evicted from the filesystem cache. Additionally, it is possible to configure for how long atime modifications can remain unflushed. That way, lazytime retains POSIX compatibility while offering performance improvements.
ctime
It is tempting to believe that originally meant creation time; however, while early Unix did have modification and creation times, the latter was changed to be access time before there was any C structure in which to call anything . The file systems retained just the access time () and modification time () through 6th edition Unix. The timestamp was added in the file system restructuring that occurred with 7th edition Unix, and has always referred to inode change time. It is updated any time file metadata stored in the inode changes, such as
file permissions
Most file systems include attributes of files and directories that control the ability of users to read, change, navigate, and execute the contents of the file system. In some cases, menu options or functions may be made visible or hidden dependin ...
,
file ownership, and
creation and deletion of hard links. In some implementations, is affected by renaming a file: Both original Unix, which implemented a renaming by making a link (updating ) and then unlinking the old name (updating again) and modern Linux tend to do this.
Unlike and , cannot be set to an arbitrary value with , as used by the utility, for example. Instead, when is used, or for any other change to the inode other than an update to caused by
accessing the file, the value is set to the current time.
Time granularity
* provides times accurate to one second.
* Some filesystems provide finer granularity. Solaris 2.1 introduced a microsecond resolution with UFS in 1992 and a nanosecond resolution with ZFS.
* In Linux kernels 2.5.48 and above, the stat structure supports nanosecond resolution for the three file timestamp fields. These are exposed as additional fields in the stat structure.
* The resolution of create time on
FAT filesystem
File Allocation Table (FAT) is a file system developed for personal computers. Originally developed in 1977 for use on floppy disks, it was adapted for use on hard disks and other devices. It is often supported for compatibility reasons by ...
is 10 milliseconds, while resolution of its write time is two seconds, and access time has a resolution of one day thus it acts as the access date.
MSDN: File Times
/ref>
Example
#include
#include
#include
#include
#include
#include
#include
int
main(int argc, char *argv[])
References
IEEE Std 1003.1, 2004, documentation for fstat(2)
Retrieved 2012-06-07.
stat(2) Linux man page
Retrieved 2012-06-07.
*
External links
{{Webarchive, url=https://web.archive.org/web/20170511220018/http://www.hep.wisc.edu/~pinghc/NoteFileSystemInfo.htm , date=May 11, 2017
stat() in PHP
atime and relatime
C POSIX library
POSIX
Unix file system-related software
System calls