fstat() — Get status information about a file

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1 XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _POSIX_SOURCE
#include <sys/stat.h>

int fstat(int fildes, struct stat *info);

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 structure, as defined in the sys/stat.h header file. The elements of this structure are described in stat() — Get file information.

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: Large z/OS UNIX files are supported automatically 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 this function 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: Description
EBADF: fildes is not a valid open file descriptor.
EINVAL: info contains a NULL.
EIO: Added for XPG4.2: 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 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.

Example

CELEBF47

⁄* CELEBF47

   This example gets status information for the file called temp.file.

 *⁄
#define _POSIX_SOURCE
#include <fcntl.h>
#include <sys⁄types.h>
#include <sys⁄stat.h>
#include <unistd.h>
#undef _POSIX_SOURCE
#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));
    }
    close(fd);
    unlink(fn);
  }
}

Output

fstat() returned:
  inode:   3057
 dev id:   1
   mode:   03000080
  links:   1
    uid:   25
    gid:   500
created:   Fri Jun 16 16:03:16 2001