@node _djstat_flags, stdio @subheading Syntax @example #include extern unsigned short _djstat_flags; @end example This variable contains bits for some fields of @code{struct stat} which are expensive to compute under DOS. Any such computation is only done by @code{stat} (@pxref{stat}) or @code{fstat} (@pxref{fstat}) if the corresponding bit in @code{_djstat_flags} is @emph{cleared}. By default, all the bits are cleared, so applications which don't care, automagically get a full version, possibly at a price of performance. To get the fastest possible version for your application, clear only the bits which you need and set all the others. The following bits are currently defined: @table @code @item _STAT_INODE Causes @code{stat} and @code{fstat} to compute the @code{st_ino} (inode number) field. @item _STAT_EXEC_EXT Tells @code{stat} and @code{fstat} to compute the execute access bit from the file-name extension. @code{stat} and @code{fstat} know about many popular file-name extensions, to speed up the computation of the execute access bit. @item _STAT_EXEC_MAGIC Tells @code{stat} and @code{fstat} to compute the execute access bit from magic signature (the first two bytes of the file), see @ref{_is_executable}, if the file-name extension is not enough for this. Computing the execute access bit from the magic signature is by far the most expensive part of @code{stat} and @code{fstat} (because it requires to read the first two bytes of every file). If your application doesn't care about execute access bit, setting @code{_STAT_EXEC_MAGIC} will significantly speed it up. Note that if @code{_STAT_EXEC_MAGIC} is set, but @code{_STAT_EXEC_EXT} is not, some files which shouldn't be flagged as executables (e.g., COFF @file{*.o} object files) will have their execute bit set, because they have the magic number signature at their beginning. Therefore, only use the above combination if you want to debug the list of extensions provided in @file{is_exec.c} file. @item _STAT_DIRSIZE Causes @code{stat} to compute directory size by counting the number of its entries (unless some friendly network redirector brought a true directory size with it). Also computes the number of subdirectories and sets the number of links @code{st_nlink} field. This computation is also quite expensive, especially for directories with large sub-directories. If your application doesn't care about size of directories and the @code{st_nlink} member, you should set the @code{_STAT_DIRSIZE} bit in @code{_djstat_flags}. @item _STAT_ROOT_TIME Causes @code{stat} to try to get time stamp of root directory from its volume label entry, if there is one. @item _STAT_WRITEBIT Tells @code{fstat} that file's write access bit is required (this needs special treatment only under some versions of Novell Netware). @end table Note that if you set a bit, some failure bits in @code{_djstat_fail_bits} (@pxref{_djstat_fail_bits}) might not be set, because some computations which report failures are only done when they are required. @subheading Portability @portability !ansi, !posix @c ---------------------------------------------------------------------- @node _djstat_fail_bits, stdio @subheading Syntax @example #include extern unsigned short _djstat_fail_bits; @end example As proper operation of @code{stat} (@pxref{stat}) and @code{fstat} (@pxref{fstat}) depend on undocumented DOS features, they could fail in some incompatible environment or a future DOS version. If they do, the @code{_djstat_fail_bits} variable will have some of its bits set. Each bit describes a single feature which was used and failed. The function @ref{_djstat_describe_lossage} may be called to print a human-readable description of the bits which were set by the last call to @code{f?stat}. This should make debugging @code{f?stat} failures in an unanticipated environment a lot easier. The following bits are currently defined: @table @code @item _STFAIL_SDA Indicates that Get SDA call failed. @item _STFAIL_OSVER Indicates an unsupported DOS version (less than 3.10 for @code{stat} or less than 2.0 for @code{fstat}). @item _STFAIL_BADSDA The pointer to SDA was found to be bogus. @item _STFAIL_TRUENAME Indicates that @code{_truename} (@pxref{_truename}) function call failed. @item _STFAIL_HASH Indicates that the starting cluster of the file is unavailable, and inode number was computed by hashing its name. @item _STFAIL_LABEL The application requested the time stamp of a root dir, but no volume label was found. @item _STFAIL_DCOUNT The number of SDA reported is ridiculously large (probably an unsupported DOS clone). @item _STFAIL_WRITEBIT @code{fstat} was asked to get write access bit of a file, but couldn't. @item _STFAIL_DEVNO @code{fstat} failed to get device number. @item _STFAIL_BADSFT An SFT entry for this file was found by @code{fstat}, but its contents can't be trusted because it didn't match file size and time stamp as reported by DOS. @item _STFAIL_SFTIDX The SFT index in Job File Table in program's PSP is negative. @item _STFAIL_SFTNF The file entry was not found in the SFT array. @end table 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 @code{_djstat_describe_lossage} (@pxref{_djstat_describe_lossage}). SDA (@dfn{Swappable Data 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. 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. @subheading Portability @portability !ansi, !posix