Editing Stat (system call)

{{Short description|Unix system call for querying file metadata}}
{{Lowercase title}}
{{Use mdy dates|date=May 2015}}
[[File:Coreutils stat screenshot.png|thumb|<code>stat</code> command line]]
'''{{code|stat()}}''' is a [[Unix]] [[system call]] that queries the [[file system]] for [[metadata]] about a [[computer file|file]] (including [[Unix file type|special files]] such as [[computer directory|directories]]). The metadata contains many fields including [[Unix file type|type]], [[file size|size]], ownership, [[File-system permissions|permission]]s and [[Unix time|timestamps]]. 

For example, the [[ls|{{code|ls}}]] command uses this system call to retrieve timestamps:
* mtime: when last modified ({{code|ls -l}})
* atime: when last accessed ({{code|ls -lu}})
* ctime: when last status changed ({{code|ls -lc}})

{{code|stat()}} appeared in [[Research Unix#Versions|Version 1 Unix]]. It is among the few original Unix [[system call]]s to change, with [[Research Unix#Versions|Version 4]]'s addition of [[group permissions]] and larger [[file size]].<ref>{{cite tech report |first1=M. D. |last1=McIlroy |authorlink1=Doug McIlroy |year=1987 |url=http://www.cs.dartmouth.edu/~doug/reader.pdf |title=A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 |series=CSTR |number=139 |institution=Bell Labs}}</ref> 

Since at least 2004, the same-named [[shell (computing)|shell]] [[command (computing)|command]] <code>stat</code> has been available for [[Linux]] to expose features of the system call via a [[command-line interface]].<ref>[http://web.archive.org/web/20060430100656/http://mailman.linuxchix.org/pipermail/courses/2004-March/001425.html tee, file, stat, find- correction - linuxchix.org - Wed Mar 10 11:04:07 EST 2004 (archived on April 30, 2006)]</ref><!--Source doesn't state whether it was pre-installed, therefore worded as "available for"; not "available in".-->

==Functions==
The [[C POSIX library]] header {{Mono|sys/stat.h}}, found on [[POSIX]] and other [[Unix-like]] [[operating system]]s, declares <code>stat()</code> and related functions. 

<syntaxhighlight lang="c">
int stat(const char *path, struct stat *buf);
int lstat(const char *path, struct stat *buf);
int fstat(int filedesc, struct stat *buf);
</syntaxhighlight>

Each function accepts a pointer to a <code>struct stat</code> buffer which the function loads with information about the specified file. As typical for system calls, each function returns 0 on success, or on failure, sets [[errno]] to indicate the failure condition and returns −1.

The <code>stat()</code> and <code>lstat()</code> functions accept a [[Path (computing)|path]] argument that specifies a file. If the path identifies a [[symbolic link]], <code>stat()</code> returns attributes of the link target, whereas <code>lstat()</code> returns attributes of the link itself. The <code>fstat()</code> function accepts a [[file descriptor]] argument instead of a path, and returns attributes of the file that it identifies.

The functions was extended to support [[large file support|large files]]. Functions <code>stat64()</code>, <code>lstat64()</code> and <code>fstat64()</code> load information into <code>struct stat64</code> buffer, which supports 64-bit sizes; allowing them to work with files 2&nbsp;GiB and larger (up to 8&nbsp;EiB). When the <code>_FILE_OFFSET_BITS</code> [[C macro|macro]] is defined to 64, the 64-bit functions are available as the original names.

==Data structure==
The metadata structure is defined in the {{Mono|sys/stat.h}} header. The following shows the base fields, but an implementation is free to define additional fields:{{sfn|Stevens|Rago|2013|p=94}}

<syntaxhighlight lang="c">
struct stat {
	mode_t			st_mode;
	ino_t			st_ino;
	dev_t			st_dev;
	dev_t			st_rdev;
	nlink_t			st_nlink;
	uid_t			st_uid;
	gid_t			st_gid;
	off_t			st_size;
	struct timespec	st_atim;
	struct timespec	st_mtim;
	struct timespec st_ctim;
	blksize_t		st_blksize;
	blkcnt_t		st_blocks;
};
</syntaxhighlight>

POSIX.1 does not require <code>st_rdev</code>, <code>st_blocks</code> and <code>st_blksize</code> 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 <code>st_atime</code>, <code>st_mtime</code> and <code>st_ctime</code>, and were of type <code>time_t</code>.  Since the 2008 version of the standard, these fields were renamed to <code>st_atim</code>, <code>st_mtim</code> and <code>st_ctim</code>, respectively, of type struct <code>timespec</code>, since this structure provides a higher resolution time unit. For the sake of compatibility, implementations can define the old names in terms of the <code>tv_sec</code> member of <code>struct timespec</code>. For example, <code>st_atime</code> can be defined as <code>st_atim.tv_sec</code>.{{sfn|Stevens|Rago|2013|p=94}}

Fields include:

{{Div col|colwidth=30em}}
* <code>st_dev</code>{{snd}} identifier of [[device file|device]] containing file
* <code>st_ino</code>{{snd}} [[inode]] number
* <code>st_mode</code>{{snd}} a [[bit field]] containing file access [[Unix file types#Representations|modes]] and [[Unix file types|special file type]]; see [[Unix permissions]]
* <code>st_nlink</code>{{snd}} [[reference count]] of [[hard link]]s
* <code>st_uid</code>{{snd}} [[user identifier]] of owner
* <code>st_gid</code>{{snd}} [[group identifier]] of owner
* <code>st_rdev</code>{{snd}} device identifier (if [[special file]])
* <code>st_size</code>{{snd}} total [[file size]], in bytes
* <code>st_atime</code>{{snd}} time of last access
* <code>st_mtime</code>{{snd}} time of last modification
* <code>st_ctime</code>{{snd}} time of last status change
* <code>st_blksize</code>{{snd}} preferred [[Block (data storage)|block]] size for file system I/O, which can depend upon both the system and the type of file system<ref>{{cite web |url=http://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/stat.h.html |work=The Open Group Base Specifications Issue 6&mdash;IEEE Std 1003.1, 2004 Edition |title=<sys/stat.h> |publisher=The Open Group |year=2004 }}</ref>
* <code>st_blocks</code>{{snd}} number of blocks allocated in multiples of <code>DEV_BSIZE</code> (usually 512&nbsp;bytes).
{{div col end}}
<!--
[Editor: The following might be useful information, but it way off topic for stat().]
== {{Anchor|RELATIME|NOATIME|LAZYTIME}}Criticism of atime ==
{{undue weight section|date=March 2015}}
Reading a file changes its {{Mono|atime}} 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]] developer [[Ingo Molnár]] publicly criticized the concept and performance impact of atime in 2007,<ref>Kernel Trap: [http://kerneltrap.org/node/14148 Linux: Replacing atime With relatime], by Jeremy, August 7, 2007</ref><ref>[https://lwn.net/Articles/244829/ Once upon atime], LWN, by Jonathan Corbet, August 8, 2007</ref> and in 2009, the {{Mono|relatime}} [[mount (Unix)|mount]] option had become the default, which addresses this criticism.<ref>[http://kernelnewbies.org/Linux_2_6_30 Linux kernel 2.6.30], Linux Kernel Newbies</ref> The behavior behind the {{Mono|relatime}} mount option offers sufficient performance for most purposes and should not break any significant applications, as it has been extensively discussed.<ref>[https://lwn.net/Articles/326471/ That massive filesystem thread], LWN, by Jonathan Corbet, March 31, 2009</ref> Initially, {{Mono|relatime}} only updated atime if atime&nbsp;< mtime or atime&nbsp;< ctime; that was subsequently modified to update atimes that were 24 hours old or older, so that {{Mono|tmpwatch}} and Debian's popularity counter (popcon) would behave properly.<ref>[https://archive.today/20120720170552/http://valerieaurora.wordpress.com/2009/03/27/relatime-recap/ Relatime Recap], Valerie Aurora</ref>

Current versions of the Linux kernel support four mount options, which can be specified in [[fstab]]:
* {{Mono|strictatime}} (formerly {{Mono|atime}}, and formerly the default; {{Mono|strictatime}} as of 2.6.30){{snd}} always update atime, which conforms to the behavior defined by POSIX
* {{Mono|relatime}} ("relative atime", introduced in 2.6.20 and the default as of 2.6.30){{snd}} 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
* {{Mono|nodiratime}}{{snd}} never update atime of directories, but do update atime of other files
* {{Mono|noatime}}{{snd}} never update atime of any file or directory; implies {{Mono|nodiratime}}; highest performance, but least compatible
* {{Mono|lazytime}}{{snd}} update atime according to specific circumstances laid out below

Current versions of [[Linux]], [[macOS]], [[Solaris (operating system)|Solaris]], [[FreeBSD]], and [[NetBSD]] support a {{Mono|noatime}} mount option in [[/etc/fstab]], which causes the atime field never to be updated. Turning off atime updating breaks [[POSIX]] compliance, and some applications, such as [[mbox]]-driven "new [[Email|mail]]" notifications,<ref>http://www.mail-archive.com/mutt-users@mutt.org/msg24912.html "the shell's $MAIL monitor ... depends on atime, pronouncing new email with atime($MAIL) < mtime($MAIL)"</ref> and some file usage watching utilities, notably [[tmpwatch]].

The {{Mono|noatime}} option on [[OpenBSD]] behaves more like Linux {{Mono|relatime}}.<ref>{{cite web
 | url = https://man.openbsd.org/mount.2#MNT_NOATIME
 | title = mount(2) - OpenBSD manual pages
 | date = April 27, 2018 | accessdate = September 26, 2018
 | website = openbsd.org
}}</ref>

Version 4.0 of the [[Linux kernel mainline]], which was released on April 12, 2015, introduced the new mount option {{Mono|lazytime}}. 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 (Unix)|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.<ref>{{cite web
 | url = http://kernelnewbies.org/Linux_4.0#head-3e847edbcf4c617048c905b6972979f7bb7547a3
 | title = Linux kernel 4.0, Section 1.5. 'lazytime' option for better update of file timestamps
 | date = May 1, 2015 | accessdate = May 2, 2015
 | website = kernelnewbies.org
}}</ref><ref>{{cite web
 | url = https://lwn.net/Articles/621046/
 | title = Introducing lazytime
 | date = November 19, 2014 | accessdate = May 2, 2015
 | author = Jonathan Corbet | publisher = [[LWN.net]]
}}</ref>

== ctime ==
It is tempting to believe that {{Mono|ctime}} originally meant creation time;<ref>{{Cite web|url=https://www.bell-labs.com/usr/dmr/www/cacm.html|title = BSTJ version of C.ACM Unix paper}}</ref> 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 {{Mono|ctime}}. The file systems retained just the access time ({{Mono|atime}}) and modification time ({{Mono|mtime}}) through 6th edition Unix. The {{Mono|ctime}} timestamp was added in the file system restructuring that occurred with [[Version 7 Unix]], and has always referred to inode change time. It is updated any time file metadata stored in the inode changes, such as [[chmod|file permissions]], [[chown|file ownership]], and [[hard link|creation and deletion of hard links]]. POSIX also mandates {{Mono|ctime}} (last status change) update with nonzero [[write (system call)|{{Mono|write()}}]] (file modification).<ref>{{Cite web|url=https://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html|title=pwrite, write - write on a file|quote=Upon successful completion, where nbyte is greater than 0, write() shall mark for update the last data modification and last file status change timestamps}}</ref> In some implementations, {{Mono|ctime}} is affected by renaming a file, despite filenames not being stored in inodes: Both original Unix, which implemented a renaming by making a link (updating {{Mono|ctime}}) and then unlinking the old name (updating {{Mono|ctime}} again) and modern Linux tend to do this.

Unlike {{Mono|atime}} and {{Mono|mtime}}, {{Mono|ctime}} cannot be set to an arbitrary value with {{Mono|utime()}}, as used by the {{Mono|[[touch (command)|touch]]}} utility, for example. Instead, when {{Mono|utime()}} is used, or for any other change to the inode other than an update to {{Mono|atime}} caused by
accessing the file, the {{Mono|ctime}} value is set to the current time.

== Time granularity ==
* {{Mono|[[time_t]]}} provides times accurate to one second.
* Some filesystems provide finer granularity. Solaris 2.1 introduced a microsecond resolution with UFS in 1992{{citation needed|date=February 2015}} and a nanosecond resolution with ZFS.{{citation needed|date=February 2015}}
* 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.<ref>{{cite web |url=http://man7.org/linux/man-pages/man2/stat.2.html |title=stat(2) - Linux manual page |accessdate=February 27, 2015 |publisher=man7.org }}</ref><ref>{{citation |url=http://www.sourceware.org/ml/libc-alpha/2002-12/msg00011.html |publisher=mail archive of the libc-alpha mailing list for the glibc project.  |title=struct stat.h with nanosecond resolution |author=Andreas Jaeger |date=December 2, 2002  }}</ref>
* The resolution of create time on [[FAT filesystem]] is 10&nbsp;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.<ref>[http://msdn.microsoft.com/en-us/library/windows/desktop/ms724290%28v=vs.85%29.aspx MSDN: File Times]</ref>
-->

== Example ==
{{confusing|section|date=January 2023}}

An example [[C (programming language)|C]] application that logs information about each path passed via the command-line. It uses {{mono|stat()}} to query the system for the information.

<syntaxhighlight lang="c">
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

#include <sys/types.h>
#include <pwd.h>
#include <grp.h>
#include <sys/stat.h>

int main(int argc, char *argv[])
{
	struct stat sb;
	struct passwd *pwuser;
	struct group *grpnam;

	if (argc < 2)
	{
		fprintf(stderr, "Usage: %s: file ...\n", argv[0]);
		exit(EXIT_FAILURE);
	}

	for (int i = 1; i < argc; i++)
	{
		if (-1 == stat(argv[i], &sb))
		{
			perror("stat()");
			exit(EXIT_FAILURE);
		}

		if (NULL == (pwuser = getpwuid(sb.st_uid)))
		{
			perror("getpwuid()");
			exit(EXIT_FAILURE);
		}

		if (NULL == (grpnam = getgrgid(sb.st_gid)))
		{
			perror("getgrgid()");
			exit(EXIT_FAILURE);
		}

		printf("%s:\n", argv[i]);
		printf("\tinode: %u\n", sb.st_ino);
		printf("\towner: %u (%s)\n", sb.st_uid, pwuser->pw_name);
		printf("\tgroup: %u (%s)\n", sb.st_gid, grpnam->gr_name);
		printf("\tperms: %o\n", sb.st_mode & (S_IRWXU | S_IRWXG | S_IRWXO));
		printf("\tlinks: %d\n", sb.st_nlink);
		printf("\tsize: %ld\n", sb.st_size); /* you may use %lld */
		printf("\tatime: %s", ctime(&sb.st_atim.tv_sec));
		printf("\tmtime: %s", ctime(&sb.st_mtim.tv_sec));
		printf("\tctime: %s", ctime(&sb.st_ctim.tv_sec));

		printf("\n");
	}

	return 0;
}

</syntaxhighlight>

==References==
{{reflist|30em}}

==External links ==
* [http://kerneltrap.org/node/14148 atime and relatime]
* [http://www.opengroup.org/onlinepubs/009695399/functions/fstat.html IEEE Std 1003.1, 2004, documentation for fstat(2)]. Retrieved 2012-06-07.
* [http://perldoc.perl.org/functions/stat.html stat() in Perl]
* [http://www.php.net/manual/en/function.stat.php stat() in PHP]
* [http://linux.die.net/man/2/stat stat(2) Linux man page]. Retrieved 2012-06-07.
*{{cite book|first1=W. Richard|last1=Stevens|first2=Stephen A.|last2=Rago|title=Advanced Programming in the UNIX Environment|date=May 24, 2013|publisher=[[Addison-Wesley Professional]]|isbn=978-0321637734|edition=Third|url=http://www.kohala.com/start/apue.html|accessdate=27 February 2015}}

[[Category:C POSIX library]]
[[Category:POSIX]]
[[Category:Unix file system-related software]]
[[Category:System calls]]