struct stat

Data structure for information about a file or directory

Synopsis:

#include <sys/stat.h>

struct stat {
#if __OFF_BITS__ == 64
        ino_t                   st_ino;
        off_t                   st_size;
#elif __OFF_BITS__ == 32
# if defined(__LITTLEENDIAN__)
        ino_t                   st_ino;
        ino_t                   st_ino_hi;
        off_t                   st_size;
        off_t                   st_size_hi;
# elif defined(__BIGENDIAN__)
        ino_t                   st_ino_hi;
        ino_t                   st_ino;
        off_t                   st_size_hi;
        off_t                   st_size;
# else
#  error endian not configured for system
# endif
#else
# error __OFF_BITS__ value is unsupported
#endif
        _CSTD dev_t             st_dev;
        _CSTD dev_t             st_rdev;
        uid_t                   st_uid;
        gid_t                   st_gid;
        _CSTD time_t    st_mtime;
        _CSTD time_t    st_atime;
        _CSTD time_t    st_ctime;
        _CSTD mode_t    st_mode;
        nlink_t                 st_nlink;
        blksize_t               st_blocksize;
        int32_t                 st_nblocks;
        blksize_t               st_blksize;
#if __OFF_BITS__ == 64
        blkcnt_t                st_blocks;
#elif __OFF_BITS__ == 32
# if defined(__LITTLEENDIAN__)
        blkcnt_t                st_blocks;
        blkcnt_t                st_blocks_hi;
# elif defined(__BIGENDIAN__)
        blkcnt_t                st_blocks_hi;
        blkcnt_t                st_blocks;
# else
#  error endian not configured for system
# endif
#else
# error __OFF_BITS__ value is unsupported
#endif
};
#endif

#ifdef __EXT_LF64SRC
struct stat64 {
        ino64_t                 st_ino;
        off64_t                 st_size;
        _CSTD dev_t             st_dev;
        _CSTD dev_t             st_rdev;
        uid_t                   st_uid;
        gid_t                   st_gid;
        _CSTD time_t    st_mtime;
        _CSTD time_t    st_atime;
        _CSTD time_t    st_ctime;
        _CSTD mode_t    st_mode;
        nlink_t                 st_nlink;
        blksize_t               st_blocksize;
        int32_t                 st_nblocks;
        blksize_t               st_blksize;
        blkcnt64_t              st_blocks;
};
#endif

Description:

The stat structure is used to store information about a file or directory. The members include:

st_ino

The file serial number for the object.

st_size

The meaning of this field depends on the object's type:

For a:	This field is:
Regular file	The size of the object, in bytes
Symbolic link	The length, in bytes, of the pathname contained in the symbolic link
Shared memory object	The length, in bytes
Typed memory object	The length, in bytes

st_dev

The ID of the device that contains the file. A device ID consists of:

a major number in the range 0 through 63
a minor number in the range 0 through 1023

These macros manipulate device IDs:

major( device ): Extract the major number from a device ID.
minor( device ): Extract the minor number from a device ID.
makedev( node, major, minor): Build a device ID from the given numbers. Currently, the node argument isn't used and must be zero.

st_rdev

The device ID, if the object is a character- or block-special file. This includes major and minor numbers, just like st_dev.

For special named files (S_IFNAM), the subtype is encoded in st_rdev:

_S_INSEM — semaphore subtype
_S_INSHD — shared data subtype
_S_INMQ — message queue subtype
_S_INTMO — typed memory object
_S_QNX_SPECIAL — QNX special type

st_uid

The user ID of the object.

st_gid

The group ID of the object.

st_mtime

The time that the data was last modified.

st_atime

The time of the last access.

st_ctime

The time that the file status last changed.

st_mode

Flags that identify the following:

file type
presence of an extended Access Control List (QNX Neutrino 6.6 or later)
set-on-execution behavior
access permissions

Three-digit octal modes include the access permissions; some utilities, such as find, use six-digit octal modes that include the rest:

Name	Octal value	Meaning
S_IFBLK	`060000`	Block special file
S_IFCHR	`020000`	Character special file
S_IFDIR	`040000`	Directory
S_IFIFO	`010000`	FIFO special file
S_IFLNK	`120000`	Symbolic link
S_IFNAM	`050000`	Special named file
S_IFREG	`100000`	Regular file
S_IFSOCK	`140000`	Socket
_S_ACL_EXT	`200000`	(QNX Neutrino 6.6 or later) The file has an extended ACL. For more information, see "Access Control Lists (ACLs)" in the Working with Files chapter of the QNX Neutrino User's Guide, and the Working with ACLs chapter of the QNX Neutrino Programmer's Guide.
S_ISUID	`004000`	Set user ID on execution. The process's effective user ID is set to the file's owner when the file is run as a program. On a regular file, this bit should be cleared on any write.
S_ISGID	`002000`	Set group ID on execution. The process's effective group ID is set to the file's group when the file is run as a program. On a regular file, this bit should be cleared on any write.
S_ISVTX	`001000`	Sticky bit
S_IRUSR	`000400`	Owner has read permission
S_IWUSR	`000200`	Owner has write permission
S_IXUSR	`000100`	Owner has execute/search permission
S_IRWXU	`000700`	Owner has read, write, and execute/search permissions; a bitwise inclusive OR of S_IRUSR, S_IWUSR and S_IXUSR
S_IRGRP	`000040`	Group has read permission
S_IWGRP	`000020`	Group has write permission
S_IXGRP	`000010`	Group has execute/search permission
S_IRWXG	`000070`	Group has read, write, and execute/search permissions; a bitwise inclusive OR of S_IRGRP, S_IWGRP and S_IXGRP
S_IROTH	`000004`	Others have read permission
S_IWOTH	`000002`	Others have write permission
S_IXOTH	`000001`	Others have execute/search permission
S_IRWXO	`000007`	Others have read, write, and execute/search permissions; a bitwise inclusive OR of S_IROTH, S_IWOTH and S_IXOTH

S_IFMT is a mask that isolates the file-type bits. For information about macros that you can use to check the file type, see "Macros," below.

The following bits define miscellaneous permissions used by other implementations:

Bit	Equivalent
S_IEXEC	S_IXUSR
S_IREAD	S_IRUSR
S_IWRITE	S_IWUSR

st_nlink

The number of hard links to the object.

st_blocksize

The block size, in bytes.

st_nblocks

The number of blocks (of size st_blocksize) that the object is using.

st_blksize

The preferred I/O block size for the object.

st_blocks

The number of 512-bytes blocks that the object is using.

Macros

The following macros test whether a file is of a specified type. The value m supplied to the macros is the value of the st_mode field of a stat structure. The macros evaluate to a nonzero value if the test is true, and zero if the test is false.

S_ISBLK(m): Test for block special file.
S_ISCHR(m): Test for character special file.
S_ISDIR(m): Test for directory file.
S_ISFIFO(m): Test for FIFO.
S_ISLNK(m): Test for symbolic link.
S_ISNAM(m): Test for special named file.
S_ISREG(m): Test for regular file.
S_ISSOCK(m): Test for socket.

These macros test whether a file is of the specified type. The value of the buf argument supplied to the macros is a pointer to a stat structure. The macro evaluates to a nonzero value if the specified object is implemented as a distinct file type and the specified file type is contained in the stat structure referenced by the pointer buf. Otherwise, the macro evaluates to zero.

S_TYPEISMQ(buf): Test for message queue.
S_TYPEISSEM(buf): Test for semaphore.
S_TYPEISSHM(buf): Test for shared memory object.

Classification:

POSIX 1003.1 with QNX Neutrino extensions