แก้ไข

แชร์ผ่าน

_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32

  • บทความ

Gets information about an open file.

Syntax

int _fstat(
   int fd,
   struct _stat *buffer
);
int _fstat32(
   int fd,
   struct _stat32 *buffer
);
int _fstat64(
   int fd,
   struct _stat64 *buffer
);
int _fstati64(
   int fd,
   struct _stati64 *buffer
);
int _fstat32i64(
   int fd,
   struct _stat32i64 *buffer
);
int _fstat64i32(
   int fd,
   struct _stat64i32 *buffer
);

Parameters

fd
File descriptor of the open file.

buffer
Pointer to the structure to store results.

Return value

Returns 0 if the file-status information is obtained. A return value of -1 indicates an error. If the file descriptor is invalid or buffer is NULL, the invalid parameter handler is invoked, as described in Parameter validation. If execution is allowed to continue, errno is set to EBADF for an invalid file descriptor, or to EINVAL if buffer is NULL.

Remarks

The _fstat function obtains information about the open file associated with fd and stores it in the structure pointed to by buffer. The _stat structure, defined in SYS\Stat.h, contains the following fields.

Field Meaning
st_atime Time of the last file access.
st_ctime Time of the creation of the file.
st_dev If a device, fd; otherwise 0.
st_mode Bit mask for file-mode information. The _S_IFCHR bit is set if fd refers to a device. The _S_IFREG bit is set if fd refers to an ordinary file. The read/write bits are set according to the file's permission mode. _S_IFCHR and other constants are defined in SYS\Stat.h.
st_mtime Time of the last modification of the file.
st_nlink Always 1 on non-NTFS file systems.
st_rdev If a device, fd; otherwise 0.
st_size Size of the file in bytes.

If fd refers to a device, the st_atime, st_ctime, st_mtime, and st_size fields aren't meaningful.

Because Stat.h uses the _dev_t type, which is defined in Types.h, you must include Types.h before Stat.h in your code.

_fstat64, which uses the _stat64 structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas the other functions only represent dates through 23:59:59 January 18, 2038, UTC. The lower bound of the date range for all these functions is Midnight, January 1, 1970.

Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file lengths. The first numerical suffix (32 or 64) indicates the size of the time type used; the second suffix is either i32 or i64, indicating whether the file size is represented as a 32-bit or 64-bit integer.

Unless _USE_32BIT_TIME_T is defined, _fstat is equivalent to _fstat64i32, and _stat contains a 64-bit time. When _USE_32BIT_TIME_T is defined, _fstat uses a 32-bit time, and _stat contains a 32-bit time. The same is true for _fstati64.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Time type and file length type variations of _stat

Functions _USE_32BIT_TIME_T defined? Time type File length type
_fstat Not defined 64-bit 32-bit
_fstat Defined 32-bit 32-bit
_fstat32 Not affected by the macro definition 32-bit 32-bit
_fstat64 Not affected by the macro definition 64-bit 64-bit
_fstati64 Not defined 64-bit 64-bit
_fstati64 Defined 32-bit 64-bit
_fstat32i64 Not affected by the macro definition 32-bit 64-bit
_fstat64i32 Not affected by the macro definition 64-bit 32-bit

Requirements

Function Required header
_fstat <sys/stat.h> and <sys/types.h>
_fstat32 <sys/stat.h> and <sys/types.h>
_fstat64 <sys/stat.h> and <sys/types.h>
_fstati64 <sys/stat.h> and <sys/types.h>
_fstat32i64 <sys/stat.h> and <sys/types.h>
_fstat64i32 <sys/stat.h> and <sys/types.h>

For more compatibility information, see Compatibility.

Example

// crt_fstat.c
// This program uses _fstat to report
// the size of a file named F_STAT.OUT.

#include <io.h>
#include <fcntl.h>
#include <time.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <share.h>

int main( void )
{
   struct _stat buf;
   int fd, result;
   char buffer[] = "A line to output";
   char timebuf[26];
   errno_t err;

   _sopen_s( &fd,
             "f_stat.out",
             _O_CREAT | _O_WRONLY | _O_TRUNC,
             _SH_DENYNO,
             _S_IREAD | _S_IWRITE );
   if( fd != -1 )
      _write( fd, buffer, strlen( buffer ) );

   // Get data associated with "fd":
   result = _fstat( fd, &buf );

   // Check if statistics are valid:
   if( result != 0 )
   {
      if (errno == EBADF)
        printf( "Bad file descriptor.\n" );
      else if (errno == EINVAL)
        printf( "Invalid argument to _fstat.\n" );
   }
   else
   {
      printf( "File size     : %ld\n", buf.st_size );
      err = ctime_s(timebuf, 26, &buf.st_mtime);
      if (err)
      {
         printf("Invalid argument to ctime_s.");
         exit(1);
      }
      printf( "Time modified : %s", timebuf );
   }
   _close( fd );
}

File size     : 16
Time modified : Wed May 07 15:25:11 2003

See also

File handling
_access, _waccess
_chmod, _wchmod
_filelength, _filelengthi64
_stat, _wstat functions