Click above to get retro games delivered to your door ever month!

_djstat_fail_bits
=================

Syntax
------

     #include <sys/stat.h>
     
     extern unsigned short   _djstat_fail_bits;

As proper operation of stat: and fstat: depend on      
undocumented DOS features, they could fail in some incompatible
environment or a future DOS version.  If they do, the
`_djstat_fail_bits' variable will have some of its bits set.  Each bit
describes a single feature which was used and failed.  The function
_djstat_describe_lossage: may be called to print a   
human-readable description of the bits which were set by the last call
to `f?stat()'.  This should make debugging `f?stat()' failures in an
unanticipated environment a lot easier.

The following bits are currently defined:

`_STFAIL_SDA'
     Indicates that Get SDA call failed.

`_STFAIL_OSVER'
     Indicates an unsupported DOS version (less than 3.10 for `stat()'
     or less than 2.0 for `fstat()').

`_STFAIL_BADSDA'
     The pointer to SDA was found to be bogus.

`_STFAIL_TRUENAME'
     Indicates that _truename: function call failed.   

`_STFAIL_HASH'
     Indicates that the starting cluster of the file is unavailable,
     and inode number was computed by hashing its name.

`_STFAIL_LABEL'
     The application requested the time stamp of a root dir, but no
     volume label was found.

`_STFAIL_DCOUNT'
     The number of SDA reported is ridiculously large (probbaly an
     unsupported DOS clone).

`_STFAIL_WRITEBIT'
     `fstat()' was asked to get write access bit of a file, but
     couldn't.

`_STFAIL_DEVNO'
     `fstat()' failed to get device number.

`_STFAIL_BADSFT'
     An SFT entry for this file was found by `fstat()', but its contents
     can't be trusted because it didn't match file size and time stamp
     as reported by DOS.

`_STFAIL_SFTIDX'
     The SFT index in Job File Table in program's PSP is negative.

`_STFAIL_SFTNF'
     The file entry was not found in the SFT array.

Below are some explanations of terminology and abbreviations used by the
printed messages, which will further clarify the meaning of the above
bits and their descriptions printed by _djstat_describe_lossage:.   

SDA (Swappable Data 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.  The full pathname of the file is looked up in a
table of files seen earlier (hashing is used to speed the lookup
process).  If found, the inode from the table is returned; this ensures
that a given file will get the same inode number.  Otherwise a new inode
number is invented, recorded in the table and returned to caller.