fstat(), fstat64() — Get status information about a file


Standards / Extensions C or C++ Dependencies
Single UNIX Specification, Version 3


#include <sys/stat.h>

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

int fstat64 (int fildes, struct stat64 *info);

Compile requirement: Use of the fstat64() function requires the long long data type. For more information on how to make the long long data type available, see z/OS XL C/C++ Language Reference.

General description

Gets status information about the file specified by the open file descriptor fildes and stores it in the area of memory indicated by the info argument. The status information is returned in a stat or stat64 structure, as defined in the sys/stat.h header file. The elements of this structure are described in stat(), stat64() — Get file information.

The fstat64() function behaves exactly like fstat() except fstat64() uses structure stat64 instead of struct stat to support time beyond 03:14:07 UTC on January 19, 2038.

Note: Environment variable _EDC_EOVERFLOW can be used to control behavior of fstat() with respect to detecting an EOVERFLOW condition for z/OS® UNIX files. By default, fstat() will not set EOVERFLOW when the file size can not be represented correctly in structure pointed to by info. When _EDC_EOVERFLOW is set to YES, fstat() will check for an overflow condition.

Large file support for z/OS UNIX files: fstat64() automatically supports large z/OS UNIX files for both AMODE 31 and AMODE 64 C/C++ applications, which means there is no need for _LARGE_FILES feature test macro to be defined. As for fstat(), the automatic support is only for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with the option LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable fstat() to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.

Returned value

If successful, fstat() returns 0.

If unsuccessful, fstat() returns -1 and sets errno to one of the following values:
Error Code
fildes is not a valid open file descriptor.
info contains a NULL.
Added for XPG4.2: An I/O error occurred while reading from the file system.

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

Note: The fstat() function might fail with error code EOVERFLOW if large file support is not enabled. The environment variable _EDC_EOVERFLOW controls this behavior. If _EDC_EOVERFLOW is set to YES the new behavior will take place. The default for _EDC_EOVERFLOW is NO.


CELEBF47 This example gets status information for the file called temp.file.
/* CELEBF47 */
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <stdio.h>
#include <time.h>

main() {
  char fn[]="temp.file";
  struct stat info;
  int fd;

  if ((fd = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    if (fstat(fd, &info) != 0)
      perror("fstat() error");
    else {
      puts("fstat() returned:");
      printf("  inode:   %d\n",   (int) info.st_ino);
      printf(" dev id:   %d\n",   (int) info.st_dev);
      printf("   mode:   %08x\n",       info.st_mode);
      printf("  links:   %d\n",         info.st_nlink);
      printf("    uid:   %d\n",   (int) info.st_uid);
      printf("    gid:   %d\n",   (int) info.st_gid);
      printf("created:   %s",           ctime(&info.st_createtime));


fstat() returned the following output:

  inode:   3057
 dev id:   1
   mode:   03000080
  links:   1
    uid:   25
    gid:   500
created:   Fri Jun 16 16:03:16 2006

Related information