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, ...
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 attributes 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 attribut ...
. The semantics of vary between
operating system
An operating system (OS) is system software that manages computer hardware, software resources, and provides common daemon (computing), services for computer programs.
Time-sharing operating systems scheduler (computing), schedule tasks for ef ...
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, ...
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 event (philosophy), events that occurs in an apparently irreversible process, irreversible succession from the past, through the present, into the future. It is a component quantity of various me ...
of last modification ()
* ctime: time of last status change ()
stat
appeared in
Version 1 Unix. 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.
stat() functions
The
C POSIX library 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 in ...
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 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,
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 ha ...
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 attribut ...
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 dependi ...
*
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 ac ...
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 u ...
of owner
*
st_gid
group identifier 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 ...
)
*
st_size
total
file size, 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 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. 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 ...
developer
Ingo Molnár 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:
* (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, whi ...
,
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 la ...
,
Solaris,
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 ava ...
support a mount option in
/etc/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 ...
, 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 in ...
compliance, and some applications, such as
mbox-driven "new
mail
The mail or post is a system for physically transporting postcards, letters, and parcels. A postal service can be private or public, though many governments place restrictions on private systems. Since the mid-19th century, national postal sys ...
" 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 e ...
behaves more like Linux .
Version 4.0 of the
Linux kernel mainline, 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,
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 c ...
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