1. stat() functions

2. stat structure

3. {{Anchor|RELATIME|NOATIME|LAZYTIME}}Criticism of atime

4. ctime

5. Time granularity

6. Example

7. References

8. External links

{{Mono|stat()}} is a Unix system call that returns file attributes about an inode. The semantics of {{Mono|stat()}} vary between operating systems. As an example, Unix command {{Mono|ls}} uses this system call to retrieve information on files that includes:

• atime: time of last access ({{Mono|ls -lu}})
• mtime: time of last modification ({{Mono|ls -l}})
• ctime: time of last status change ({{Mono|ls -lc}})

stat() functions

The C POSIX library header {{Mono|sys/stat.h}}, found on POSIX and other Unix-like operating systems, declares the stat() functions, as well as related function 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 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 argument instead, and returns attributes of the file that it identifies.

The family of functions was extended to implement large file support. 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 {{Mono|sys/stat.h}} header file as follows, although implementations are free to define additional fields:{{sfn|Stevens|Rago|2013|p=94}}

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;

};

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.{{sfn|Stevens|Rago|2013|p=94}}

The struct stat structure includes at least the following members:

• st_dev{{snd}} identifier of device containing file
• st_ino{{snd}} inode number
• st_mode{{snd}} protection mode; see also Unix permissions
• st_nlink{{snd}} reference count of hard links
• st_uid{{snd}} user identifier of owner
• st_gid{{snd}} group identifier of owner
• st_rdev{{snd}} device identifier (if special file)
• st_size{{snd}} total file size, in bytes
• st_atime{{snd}} time of last access
• st_mtime{{snd}} time of last modification
• st_ctime{{snd}} time of last status change
• st_blksize{{snd}} preferred block size for file system I/O, which can depend upon both the system and the type of file system^[2]
• st_blocks{{snd}} 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 and also indicates any special file type. There are many macros to work with the different mode flags and file types.

{{Anchor|RELATIME|NOATIME|LAZYTIME}}Criticism of atime

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.

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, Mac OS X, 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 mail" notifications,^[8] and some file usage watching utilities, notably tmpwatch.

The {{Mono|noatime}} option on OpenBSD behaves more like Linux {{Mono|relatime}}.^[9]

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 system calls is 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.^[10][11]

ctime

It is tempting to believe that {{Mono|ctime}} originally meant creation time,^[12], however while early unix did have modification and creation times, that was changed to be access time and modification time before there was any C structure in which to call anything {{Mono|ctime}}. The filesystems 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 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, {{Mono|ctime}} is affected by renaming a file (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}} utility, for example. Instead, when {{Mono|utime()}} is used, or 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.^[13][14]
• The resolution of create time on FAT filesystem 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.^[15]

Example

1. include
2. include
3. include

1. include
2. include
3. include
4. include

int

main(int argc, char *argv[])

struct stat sb;

struct passwd *pwuser;

struct group *grpnam;

if (argc < 2)

{

fprintf(stderr, "Usage: %s: file ...\", 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:\", argv[i]);

printf("\\tinode: %u\", sb.st_ino);

printf("\\towner: %u (%s)\", sb.st_uid, pwuser->pw_name);

printf("\\tgroup: %u (%s)\", sb.st_gid, grpnam->gr_name);

printf("\\tperms: %o\", sb.st_mode & (S_IRWXU | S_IRWXG | S_IRWXO));

printf("\\tlinks: %d\", sb.st_nlink);

printf("\\tsize: %ld\", 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("\");

}

return 0;

}

References

• IEEE Std 1003.1, 2004, documentation for fstat(2). Retrieved 2012-06-07.
• stat(2) Linux man page. Retrieved 2012-06-07.
• {{cite book|last1=W. Richard|first1=Stevens|last2=Stephen A.|first2=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}}

External links

• An example showing how to use stat()
• stat() in Perl
• stat() in PHP
• atime and relatime

• Stagg, David
• Stagger (disambiguation)
• Staggered via
• Stagger Lee (play)
• Stagger Lee (Play)
• Staggerwing Beech
• Stagg High School
• Stagg High School (disambiguation)
• Stagg H.S.
• Staggins, Nicholas
• Stagg, Richard
• Stagg's
• Staggs-Huffaker Building
• Staggs, Steve
• Stagg Street Recordings
• Staggs–Huffaker Building
• Stagg, Tom
• Stag Hill Campus
• Stag Hill, Guildford
• Stag Hill, University of Surrey
• Staghorn cholla moth
• Stag horn fern
• Stag-horn fern
• Staghorn hakea
• Stag horn hakea