struct stat

Description:

The stat structure is used to store information about a file or directory. There are several forms of the stat structure:

struct __stat_t32_2001

Includes 32-bit time_t fields, but not the nanosecond-resolution timestamps. This is what earlier versions of the OS supported and is the default for 32-bit architectures.

struct __stat_t32_2008

Includes 32-bit time_t fields, and the nanosecond-resolution timestamps.

struct __stat_t64_2008

Includes 64-bit time_t fields, and the nanosecond-resolution timestamps. This is the default for 64-bit architectures.

The members include:

ino_t st_ino

The field is of long int type and represents the file serial number for the object.

off_t st_size

The field is of long int type and its meaning 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

dev_t 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.

dev_t 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

uid_t st_uid

The user ID of the object.

gid_t st_gid

The group ID of the object.

time_t st_mtime, time_t st_atime, time_t st_ctime

(POSIX 2001) The time that the data was last modified, accessed, or the file status was changed, respectively, expressed as the number of seconds since January 1, 1970.

struct timespec st_mtim, struct timespec st_atim, struct timespec st_ctim

(POSIX 2008 only) The time that the data was last modified, accessed, or the file status was changed, respectively, expressed as the number of seconds and nanoseconds since January 1, 1970. For backwards compatibility, st_mtime, st_atime, and st_ctime correspond to the tv_sec field of st_mtim, st_atim, and st_ctim.

mode_t st_mode

Flags that identify the following:

• file type
• presence of an extended Access Control List
• 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	The file has an extended ACL. For more information, see Access Control Lists (ACLs) in the Working with Files chapter of the QNX OS User's Guide, and the Working with ACLs chapter of the QNX OS Programmer's Guide.
_S_TRUST_EXT	400000	The resource manager claims that the file is trusted (pathtrust). However, to ensure proper pathtrust behavior, don't test these bits. Instead, use the fchecktrust() function to verify if a file is trusted. For more information, refer to Pathtrust in the QNX OS System Security 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

nlink_t st_nlink

The number of hard links to the object.

blksize_t st_blocksize

The block size, in bytes.

int32_t st_nblocks

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

blksize_t st_blksize

The preferred I/O block size for the object.

blkcnt_t st_blocks

The field is of long int type and represents the number of 512-byte 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.

S_ISTRUSTED(m)

Test for pathtrust. However, to ensure proper pathtrust behavior, don't use this macro. Instead, use the fchecktrust() function to verify if a file is trusted.

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 OS extensions