fstat

Syntax

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

Description

This function obtains the status of the open file file and stores it in sbuf. See section stat, for the description of members of struct stat.

The st_size member is an signed 32-bit integer type, so it will overflow on FAT32 volumes for files that are larger than 2GB. Therefore, if your program needs to support large files, you should treat the value of st_size as an unsigned value.

For some drives st_blksize has a default value, to improve performance. The floppy drives A: and B: default to a block size of 512 bytes. Network drives default to a block size of 4096 bytes.

Some members of struct stat are very expensive to compute. If your application is a heavy user of fstat and is too slow, you can disable computation of the members your application doesn't need, as described in _djstat_flags.

Return Value

Zero on success, nonzero on failure (and errno set).

Portability

ANSI/ISO C	No
POSIX	1003.2-1992; 1003.1-2001

Example

struct stat s; fstat(fileno(stdin), &s); if (S_ISREG(s.st_mode)) puts("STDIN is a redirected disk file"); else if (S_ISCHR(s.st_mode)) puts("STDIN is a character device");

Bugs

If a file was open in write-only mode, its execute and symlink mode bits might be incorrectly reported as if the file were non-executable or non-symlink. This is because executables and symlinks are only recognized by reading their first few bytes, which cannot be done for files open in write-only mode.

For fstat to return correct info, you should make sure that all the data written to the file has been delivered to the operating system, e.g. by calling both fflush and fsync. Otherwise, the buffering of the library I/O functions and the OS might cause stale info to be returned.

Implementation Notes

Supplying a 100% Unix-compatible fstat function under DOS is an implementation nightmare. The following notes describe some of the obscure points specific to fstats behavior in DJGPP.

1. The `drive' for character devices (like con, /dev/null and others is returned as -1. For drives networked by Novell Netware, it is returned as -2.

2. The starting cluster number of a file serves as its inode number. For files whose starting cluster number is inaccessible (empty files, all files on Windows, files on networked drives, etc.) the st_inode field will be invented in a way which guarantees that no two different files will get the same inode number (thus it is unique). This invented inode will also be different from any real cluster number of any local file. However, only for local, non-empty files/directories the inode is guaranteed to be consistent between stat and fstat function calls. (Note that files on different drives can have identical inode numbers, and thus comparing files for identity should include comparison of the st_dev member.)

3. On all versions of Windows except Windows 3.X, the inode number is invented using the file name. fstat can probably use the file name that was used to open the file, when generating the inode. This is done such that the same inode will be generated irrespective of the actual path used to open the file (e.g.: `foo.txt', `./foo.txt', `../somedir/foo.txt'). If file names cannot be used, fstat always returns different inode numbers for any two files open on different handles, even if the same file is open twice on two different handles.

4. The WRITE access mode bit is set only for the user (unless the file is read-only, hidden or system). EXECUTE bit is set for directories, files which can be executed from the DOS prompt (batch files, .com, .dll and .exe executables) or run by go32-v2.exe. For files which reside on networked drives under Novell Netware, this can sometimes fail, in which case only the read access bit is set.

5. The variable _djstat_flags (see section _djstat_flags) controls what hard-to-get fields of struct stat are needed by the application.