The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

#### 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 only 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 only 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.

> The structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime shall have meaningful values for all other file types defined in this volume of IEEE Std 1003.1-2001. The value of the member st_nlink 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 the Base Definitions volume of IEEE Std 1003.1-2001, Section 4.7, 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

> lstat(), stat(), the Base Definitions volume of IEEE Std 1003.1-2001, <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.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]