stat (system call)

The C POSIX library header {{Mono|sys/stat.h}}, found on POSIX and other Unix-like operating systems, declares stat() and related functions.

int stat(const char *path, struct stat *buf);

int lstat(const char *path, struct stat *buf);

int fstat(int filedesc, struct stat *buf);

Each function accepts a pointer to a struct stat 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 stat() and lstat() functions accept a path argument that specifies a file. If the path identifies a symbolic link, stat() returns attributes of the link target, whereas lstat() returns attributes of the link itself. The fstat() 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 files. Functions stat64(), lstat64() and fstat64() load information into struct stat64 buffer, which supports 64-bit sizes; allowing them to work with files 2 GiB and larger (up to 8 EiB). When the _FILE_OFFSET_BITS macro is defined to 64, the 64-bit functions are available as the original names.

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}}

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}}

Fields include:

{{Div col|colwidth=30em}}

• st_dev{{snd}} identifier of device containing file
• st_ino{{snd}} inode number
• st_mode{{snd}} a bit field containing file access modes and special file type; see 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{{cite web |url=http://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/stat.h.html |work=The Open Group Base Specifications Issue 6—IEEE Std 1003.1, 2004 Edition |title= |publisher=The Open Group |year=2004 }}
• st_blocks{{snd}} number of blocks allocated in multiples of DEV_BSIZE (usually 512 bytes).

{{div col end}}

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

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

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 ...\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;

}

{{reflist|30em}}

• [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