stat(5)

NAME

stat: stat.h — data returned by the stat() function

SYNOPSIS

#include <sys/stat.h>

DESCRIPTION

The <sys/stat.h> header defines the structure of the data returned by the functions fstat(), lstat(), and stat(). The structure stat contains at least the following members:

`dev_t`	`st_dev`	ID of device containing file
`ino_t`	`st_ino`	file serial number
`mode_t`	`st_mode`	mode of file (see below)
`nlink_t`	`st_nlink`	number of links to the file
`uid_t`	`st_uid`	user ID of file
`gid_t`	`st_gid`	group ID of file
`dev_t`	`st_rdev`	device ID (if file is character or block special)
`off_t`	`st_size`	file size in bytes (if file is a regular file)
`time_t`	`st_atime`	time of last access
`time_t`	`st_mtime`	time of last data modification
`time_t`	`st_ctime`	time of last status change
`long`	`st_blksize`	a file-system-specific preferred I/O block size for this object. In some filesystem types, this may vary from file to file
`long`	`st_blocks`	number of blocks of a filesystem-specific size allocated for this object

File serial number and device ID taken together uniquely identify the file within the system. The dev_t, ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t types are defined as described in <sys/types.h>. Times are given in seconds since the Epoch.

The following symbolic names for the values of st_mode are also defined:

File type

`S_IFMT`	type of file
`S_IFBLK`	block special
`S_IFCHR`	character special
`S_IFIFO`	FIFO special
`S_IFREG`	regular
`S_IFDIR`	directory
`S_IFLNK`	symbolic link

File mode bits

`S_IRWXU`	read, write, execute/search by owner
`S_IRUSR`	read permission, owner
`S_IWUSR`	write permission, owner
`S_IXUSR`	execute/search permission, owner
`S_IRWXG`	read, write, execute/search by group
`S_IRGRP`	read permission, group
`S_IWGRP`	write permission, group
`S_IXGRP`	execute/search permission, group
`S_IRWXO`	read, write, execute/search by others
`S_IROTH`	read permission, others
`S_IWOTH`	write permission, others
`S_IXOTH`	execute/search permission, others
`S_ISUID`	set-user-ID on execution
`S_ISGID`	set-group-ID on execution
`S_ISVTX`	on directories, restricted deletion flag

The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, S_IWOTH, S_IXOTH, S_ISUID, S_ISGlD and S_ISVTX are unique. S_IRWXU is the bitwise OR of S_IRUSR, S_IWUSR, and S_IXUSR. S_IRWXG is the bitwise OR of S_IRGRP, S_IWGRP, and S_IXGRP. S_IRWXO is the bitwise OR of S_IROTH, S_IWOTH, and S_IXOTH.

Implementations may OR other implementation-dependent bits into S_IRWXU, S_IRWXG, and S_IRWXO, but they will not overlap any of the other bits defined in this document. The file permission bits are defined to be those corresponding to the bitwise inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO.

The following macros will test whether a file is of the specified type. The value m supplied to the macros is the value of st_mode from a stat structure. The macro evaluates to a non-zero value if the test is true, 0 if the test is false.

`S_ISBLK(m)`	Test for a block special file.
`S_ISCHR(m)`	Test for a character special file.
`S_ISDIR(m)`	Test for a directory.

`S_ISFIFO(m)`	Test for a pipe or FIFO special file.
`S_ISREG(m)`	Test for a regular file.
`S_ISLNK(m)`	Test for a symbolic link.

The following are declared as functions and may also be defined as macros:

`int`	chmod(const char *path, mode_t mode);
`int`	lstat(const char path, struct stat buf);
`int`	mkdir(const char *path, mode_t mode);
`int`	mkfifo(const char *path, mode_t mode);
`int`	mknod(const char *path, mode_t mode, dev_t dev);
`int`	stat(const char path, struct stat buf);
`mode_t`	umask(mode_t cmask);

APPLICATION USAGE

Use of the macros is recommended for determining the type of a file.

CHANGE HISTORY

First released in Issue 1.

Derived from Issue 1 of the SVID.

Issue 4

The following changes are incorporated for alignment with the ISO POSIX-1 standard:

The function declarations in this header are expanded to full ISO C prototypes.
The DESCRIPTION section is expanded to indicate (a) how files are uniquely identified within the system, (b) that times are given in units of seconds since the Epoch, (c) rules governing the definition and use of the file mode bits, and (d) usage of the file type test macros.

Other changes are incorporated as follows:

Reference to the header <sys/types.h> is added for the definitions of dev_t, ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t. This has been marked as an extension.
References to the S_IREAD, S_IWRITE, S_IEXEC file and S_ISVTX modes are removed.
The descriptions of the members of the stat structure in the DESCRIPTION section are corrected.

Issue 4, Version 2

The following changes are incorporated for X/OPEN UNIX conformance:

The st_blksize and st_blocks members are added to the stat structure.
The S_IFLINK value of S_IFMT is defined.
The S_ISVTX file mode bit and the S_ISLNK file type test macro is defined.
The fchmod(), lstat(), and mknod() functions are added to the list of functions declared in this header.

stat HP-UX EXTENSIONS

NAME (HP-UX)

stat.h - file-specific information

DESCRIPTION

The contents of the stat structure include the following members:

ushort st_fstype;: /*Type of filesystem this file */
: /* is in; see vfsmount(2) */
dev_t#st_realdev;: /* Real device number of device */
: /* containing the inode for this file */

The following symbolic names for the values of the st_mode field are defined as indicated:

File type

`S_IFMT`	`0170000`	type of file
`S_IFSOCK`	`0140000`	socket
`S_IFLNK`	`0120000`	symbolic link
`S_IFNWK`	`0110000`	network special
`S_IFREG`	`0100000`	regular (ordinary)
`S_IFBLK`	`0060000`	block special
`S_IFDIR`	`0040000`	directory
`S_IFCHR`	`0020000`	character special
`S_IFIFO`	`0010000`	FIFO special (named pipe)

File mode bits: miscellaneous

`S_CDF`	`0004000`	directory is a context-dependent file
`S_ISUID`	`0004000`	set user id on execution
`S_ISGID`	`0002000`	set group id on execution
`S_ENFMT`	`0002000`	set file-locking mode to enforced
`S_ISVTX`	`0001000`	save swapped text even after use

File mode bits: permissions

`S_IRWXU`	`0000700`	owner's file access permission bits
`S_IRUSR`	`0000400`	read access permission for owner
`S_IWUSR`	`0000200`	write access permission for owner
`S_IXUSR`	`0000100`	execute/search access permission for owner
`S_IRWXG`	`0000070`	group's file access permission bits
`S_IRGRP`	`0000040`	read access permission for group
`S_IWGRP`	`0000020`	write access permission for group
`S_IXGRP`	`0000010`	execute/search access permission for group
`S_IRWXO`	`0000007`	others' access permission bits
`S_IROTH`	`0000004`	read access permission for others
`S_IWOTH`	`0000002`	write access permission for others
`S_IXOTH`	`0000001`	execute/search access permission for others

File mode bits: obsolete permission names

`S_IREAD`	`0000400`	read access permission for owner
`S_IWRITE`	`0000200`	write access permission for owner
`S_IEXEC`	`0000100`	execute/search access permission for owner

File type test macros

`S_ISCDF(m)`	test for a context-dependent file
`S_ISNWK(m)`	test for a network special
`S_ISSOCK(m)`	test for a socket

STANDARDS CONFORMANCE

<sys/stat.h>: AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

stat(5)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

DESCRIPTION

APPLICATION USAGE

SEE ALSO

CHANGE HISTORY

Issue 4

Issue 4, Version 2

stat HP-UX EXTENSIONS

NAME (HP-UX)

DESCRIPTION

SEE ALSO

STANDARDS CONFORMANCE