@node _djstat_describe_lossage, stdio
@subheading Syntax

@example
#include <stdio.h>

void _djstat_describe_lossage(FILE *fp);
@end example

@subheading Description

Accesses the global variable @ref{_djstat_fail_bits} and prints to the
stream given by @var{fp} a human-readable description of the undocumented
DOS features which the last call to @code{stat()} or @code{fstat()} failed
to use.  (If @var{fp} is zero, the function prints to stderr.)  If the
last call to @code{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 @code{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 (@dfn{Swappable DOS Area}) -- this is an internal DOS structure.
@code{stat()} uses it to get the full directory entry (including the
starting cluster number) of a file.  The pointer to SDA found by
@code{stat()} is trusted only if we find the pathname of our file at a
specific offset in that SDA.

  SFT (@dfn{System File Table}) -- another internal DOS structure, used
in file operations.  @code{fstat()} uses it to get full information on a
file given its handle.  An SFT entry which is found by @code{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.

@subheading Return Value

None.

@subheading Portability

@portability !ansi, !posix

@subheading Example

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