The Open Group Base Specifications Issue 7, 2018 edition
IEEE Std 1003.1-2017 (Revision of IEEE Std 1003.1-2008)
Copyright © 2001-2018 IEEE and The Open Group
A newer edition of this document exists here

#### NAME

> fstat - get file status

#### SYNOPSIS

> ``#include <sys/stat.h>
> int fstat(int` fildes`, struct stat *`buf`);
> ``

#### DESCRIPTION

> The fstat() function shall obtain information about an open file associated with the file descriptor fildes, and shall write it to the area pointed to by buf.

> [SHM] If fildes references a shared memory object, the implementation shall update in the stat structure pointed to by the buf argument the st_uid, st_gid, st_size, and st_mode fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits need be valid. The implementation may update other fields and flags.

> [TYM] If fildes references a typed memory object, the implementation shall update in the stat structure pointed to by the buf argument the st_uid, st_gid, st_size, and st_mode fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits need be valid. The implementation may update other fields and flags.

> The buf argument is a pointer to a stat structure, as defined in <sys/stat.h>, into which information is placed concerning the file.

> For all other file types defined in this volume of POSIX.1-2017, the structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atim, st_ctim, and st_mtim shall have meaningful values and the value of the st_nlink member shall be set to the number of links to the file.

> An implementation that provides additional or alternative file access control mechanisms may, under implementation-defined conditions, cause fstat() to fail.

> The fstat() function shall update any time-related fields (as described in XBD File Times Update), before writing into the stat structure.

#### RETURN VALUE

> Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to indicate the error.

#### ERRORS

> The fstat() function shall fail if:

> [EBADF]
>   The fildes argument is not a valid file descriptor.
> [EIO]
>   An I/O error occurred while reading from the file system.
> [EOVERFLOW]
>   The file size in bytes or the number of blocks allocated to the file or the file serial number cannot be represented correctly in the structure pointed to by buf.

> The fstat() function may fail if:

> [EOVERFLOW]
>   One of the values is too large to store into the structure pointed to by the buf argument.

The following sections are informative.

#### EXAMPLES

> ##### Obtaining File Status Information

> The following example shows how to obtain file status information for a file named /home/cnd/mod1. The structure variable buffer is defined for the stat structure. The /home/cnd/mod1 file is opened with read/write privileges and is passed to the open file descriptor fildes.

>     #include <sys/types.h>
>     #include <sys/stat.h>
>     #include <fcntl.h>

>     struct stat buffer;
>     int         status;
>     ...
>     fildes = open("/home/cnd/mod1", O_RDWR);
>     status = fstat(fildes, &buffer);

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> fstatat

> XBD File Times Update, <sys/stat.h>, <sys/types.h>

#### CHANGE HISTORY

> First released in Issue 1. Derived from Issue 1 of the SVID.

#### Issue 5

> The DESCRIPTION is updated for alignment with the POSIX Realtime Extension.

> Large File Summit extensions are added.

#### Issue 6

> In the SYNOPSIS, the optional include of the <sys/types.h> header is removed.

> The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

> - The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was required for conforming implementations of previous POSIX specifications, it was not required for UNIX applications.

> - The [EIO] mandatory error condition is added.

> - The [EOVERFLOW] mandatory error condition is added. This change is to support large files.

> - The [EOVERFLOW] optional error condition is added.

> The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that shared memory object semantics apply to typed memory objects.

#### Issue 7

> XSH-SD5-ERN-161 is applied, updating the DESCRIPTION to clarify to which file types st_nlink applies.

> Changes are made related to support for finegrained timestamps.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ™ is a Trademark of The IEEE.
Copyright © 2001-2018 IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]