# <sys/stat.h>

Include the system header <sys/stat.h> to define several macros and a
host of functions for use with file query operations.

> 
> 
> int stat(const char \*path, struct stat \*sb); [POSIX]
> 
> 
> stat
> 
> 
> int stat(const char \*path, struct stat \*sb); [POSIX]

The stat() function obtains information about the file pointed to by
path. Read, write or execute permission of the named file is not
required, but all directories listed in the path name leading to the
file must be searchable.

The sb argument is a pointer to a stat structure as defined by
<sys/stat.h> (shown below) and into which information is placed
concerning the file.

For example:

> 
> 
> struct stat {
> 
> 
> dev\_t st\_dev; /\* device containing the file \*/ ino\_t st\_ino; /\*
> file’s serial number \*/
> 
> 
> mode\_t st\_mode; /\* file’s mode (protection and type) \*/ nlink\_t
> st\_nlink; /\* number of hard links to the file \*/ uid\_t st\_uid; /\*
> user-id of owner \*/
> 
> 
> gid\_t st\_gid; /\* group-id of owner \*/
> 
> 
> dev\_t st\_rdev; /\* device type, for device special file \*/ #if
> defined(\_NETBSD\_SOURCE)
> 
> 
> struct timespec st\_atimespec; /\* time of last access \*/
> 
> 
> struct timespec st\_mtimespec; /\* time of last data modification
> 
> 
> \*/
> 
> 
> struct timespec st\_ctimespec; /\* time of last file status change
> 
> 
> \*/
> 
> 
> #else
> 
> 
> time\_t st\_atime; /\* time of last access \*/ long st\_atimensec; /\*
> nsec of last access \*/
> 
> 
> time\_t st\_mtime; /\* time of last data modification \*/ long
> st\_mtimensec; /\* nsec of last data modification \*/ time\_t st\_ctime;
> /\* time of last file status change \*/ long st\_ctimensec; /\* nsec
> of last file status change \*/
> 
> 
> #endif
> 
> 
> off\_t st\_size; /\* file size, in bytes \*/ blkcnt\_t st\_blocks; /\*
> blocks allocated for file \*/
> 
> 
> blksize\_t st\_blksize; /\* optimal file sys I/O ops blocksize \*/
> uint32\_t st\_flags; /\* user defined flags for file \*/ uint32\_t
> st\_gen; /\* file generation number \*/
> 
> 
> #if defined(\_NETBSD\_SOURCE)
> 
> 
> struct timespec st\_birthtimespec; /\* time of inode creation \*/
> #else
> 
> 
> time\_t st\_birthtime; /\* time of inode creation \*/ long
> st\_birthtimensec; /\* nsec of inode creation \*/
> 
> 
> #endif
> 
> 
> };

[Table 11-7](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_posix_sys-stat.html#_bookmark673) lists the time-related fields of the
struct stat.

> 
> 
> **Table 11-7 stat time-related fields**

| **Field** | **Description** |
| --- | --- |
| st\_atime | Time when file data was last accessed.<br><br><br><br>> <br>> <br>> Changed by the mknod, utimes, and read system calls. |
| st\_mtime | Time when file data was last modified.<br><br><br><br>> <br>> <br>> Changed by the mknod, utimes, and write system calls. |
| st\_ctime | - Time when file status was last changed (file metadata<br>    - modification).<br><br><br>Changed by the chflags, chmod, chown, link, mknod, rename,<br>unlink, utimes, and write system calls. |
| st\_birthtime | Time when the inode was created. |

> 
> 
> If \_NETBSD\_SOURCE is defined, the time-related fields are defined
> as:
> 
> 
> #if defined(\_NETBSD\_SOURCE)
> 
> 
> #define st\_atime st\_atimespec.tv\_sec
> 
> 
> #define st\_atimensec st\_atimespec.tv\_nsec
> 
> 
> #define st\_mtime st\_mtimespec.tv\_sec
> 
> 
> #define st\_mtimensec st\_mtimespec.tv\_nsec
> 
> 
> #define st\_ctime st\_ctimespec.tv\_sec
> 
> 
> #define st\_ctimensec st\_ctimespec.tv\_nsec
> 
> 
> #define st\_birthtime st\_birthtimespec.tv\_sec #define st\_birthtimensec
> st\_birthtimespec.tv\_nsec #endif

[Table 11-8](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_posix_sys-stat.html#_bookmark674) lists the size-related fields of the
struct stat.

> 
> 
> **Table 11-8 stat size-related fields**

| **Field** | **Description** |
| --- | --- |
| st\_size | The size of the file in bytes.<br><br><br><br>> <br>> <br>> A directory will be a multiple of the size of the dirent<br>structure. Some file systems (notably ZFS) return the number of<br>entries in the directory instead of the size in bytes. |
| st\_blksize | The optimal input/output block size for the file. |
| st\_blocks | - The actual number of blocks allocated for the file in 512-byte<br>    - units.<br><br><br>Because short symbolic links are stored in the inode, this<br>number might be zero. |

The status information word st\_mode has the following bits:

| #define | S\_IFMT | 0170000 |  | /\* | type of file \*/ |
| --- | --- | --- | --- | --- | --- |
| #define |  | S\_IFIFO | 0010000 | /\* | named pipe (fifo) \*/ |
| #define |  | S\_IFCHR | 0020000 | /\* | character special \*/ |
| #define |  | S\_IFDIR | 0040000 | /\* | directory \*/ |
| #define |  | S\_IFBLK | 0060000 | /\* | block special \*/ |
| #define |  | S\_IFREG | 0100000 | /\* | regular \*/ |
| #define |  | S\_IFLNK | 0120000 | /\* | symbolic link \*/ |
| #define |  | S\_IFSOCK | 0140000 | /\* | socket \*/ |
| #define |  | S\_IFWHT | 0160000 | /\* | whiteout \*/ |

> 
> 
> #define S\_ISUID 0004000 /\* set user id on execution \*/
> 
> 
> #define S\_ISGID 0002000 /\* set group id on execution \*/ #define
> S\_ISVTX 0001000 /\* save swapped text even after use \*/ #define
> S\_IRUSR 0000400 /\* read permission, owner \*/
> 
> 
> #define S\_IWUSR 0000200 /\* write permission, owner \*/
> 
> 
> #define S\_IXUSR 0000100 /\* execute/search permission, owner \*/
> #define S\_IRGRP 0000040 /\* read permission, group \*/
> 
> 
> #define S\_IWGRP 0000020 /\* write permission, group \*/
> 
> 
> #define S\_IXGRP 0000010 /\* execute/search permission, group \*/
> #define S\_IROTH 0000004 /\* read permission, other \*/
> 
> 
> #define S\_IWOTH 0000002 /\* write permission, other \*/
> 
> 
> #define S\_IXOTH 0000001 /\* execute/search permission, other \*/

The status information word st\_flags has the following bits:

> 
> 
> #define UF\_NODUMP 0x00000001 /\* do not dump file \*/ #define
> UF\_IMMUTABLE 0x00000002 /\* file may not be changed \*/
> 
> 
> #define UF\_APPEND 0x00000004 /\* writes file may only append \*/
> #define UF\_OPAQUE 0x00000008 /\* directory is opaque wrt union \*/
> #define SF\_ARCHIVED 0x00010000 /\* file is archived \*/
> 
> 
> #define SF\_IMMUTABLE 0x00020000 /\* file may not be changed \*/
> #define SF\_APPEND 0x00040000 /\* writes file may only append \*/

Upon successful completion a value of 0 is returned. Otherwise, a value
of -1 is returned and

errno is set to indicate the error.

Last Published: Oct 06, 2026

[Previous Topic
rindex](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/c_posix_strings.md) Next Topic

<sys time.h=""></sys>