_djstat_describe_lossage

Syntax

#include <stdio.h> void _djstat_describe_lossage(FILE *fp);

Description

Accesses the global variable _djstat_fail_bits (see section _djstat_fail_bits) and prints to the stream given by fp a human-readable description of the undocumented DOS features which the last call to stat() or fstat() failed to use. (If fp is zero, the function prints to stderr.) If the last call to f?stat() didn't set any failure bits, an "all's well" message is printed. This function is designed to help in debugging these functions in hostile environments (like DOS clones) and in adapting them to the future DOS versions. If you ever have any strange results returned by f?stat(), please call this function and post the diagnostics it printed to the DJGPP mailing list.

The diagnostic messages this function prints are almost self-explanatory. Some explanations of terminology and abbreviations used by the printed messages will further clarify them.

SDA (Swappable DOS Area) -- this is an internal DOS structure. stat() uses it to get the full directory entry (including the starting cluster number) of a file. The pointer to SDA found by stat() is trusted only if we find the pathname of our file at a specific offset in that SDA.

SFT (System File Table) -- another internal DOS structure, used in file operations. fstat() uses it to get full information on a file given its handle. An SFT entry which is found by fstat() is only trusted if it contains files size and time stamp like those returned by DOS functions 57h and 42h. Novell NetWare 3.x traps DOS file operations in such a way they never get to SFT, so some failure messages refer specifically to Novell.

Hashing -- the fall-back method of returning a unique inode number for each file. It is used whenever the starting cluster of a file couldn't be reliably determined.

Return Value

None.

Portability

ANSI/ISO C	No
POSIX	No

Example

if (stat(path, &stat_buf)) _djstat_describe_lossage((FILE *)0);