@node stat, io
@subheading Syntax

@example
#include <sys/stat.h>

int stat(const char *file, struct stat *sbuf);
@end example

@subheading Description

This function obtains the status of the file @var{file} and stores
it in @var{sbuf}, which has this structure:

@smallexample
struct  stat @{
        time_t   st_atime;     /* time of last access       */
        time_t   st_ctime;     /* time of file's creation   */
        dev_t    st_dev;       /* The drive number (0 = a:) */
        gid_t    st_gid;       /* what getgid() returns */
        ino_t    st_ino;       /* starting cluster or unique identifier */
        mode_t   st_mode;      /* file mode - S_IF* and S_IRUSR/S_IWUSR */
        time_t   st_mtime;     /* time that the file was last written */
        nlink_t  st_nlink;     /* 2 + number of subdirs, or 1 for files */
        off_t    st_size;      /* size of file in bytes */
        off_t    st_blksize;   /* the size of transfer buffer */
        uid_t    st_uid;       /* what getuid() returns */
@};
@end smallexample

The @code{st_atime}, @code{st_ctime} and @code{st_mtime} have different
values only when long file names are supported (e.g. on Windows 9X);
otherwise, they all have the same value: the time that the file was last
written@footnote{
Even when long file names @emph{are} supported, the three time values
returned by @code{stat} might be identical if the file was last written
by a program which used legacy DOS functions that don't know about long
file names.}.  Most Windows 9X VFAT filesystems only support the date of
the file's last access (the time is set to zero); therefore, the DJGPP
implementation of @code{stat} sets the @code{st_atime} member to the
same value as @code{st_mtime} if the time part of @code{st_atime}
returned by the filesystem is zero (to prevent the situation where the
file appears to have been created @emph{after} it was last accessed,
which doesn't look good).

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

@subheading Return Value

Zero on success, nonzero on failure (and @var{errno} set).

@subheading Portability

@portability !ansi, posix

@subheading Example

@example
struct stat s;
stat("data.txt", &s);
if (S_ISDIR(s.st_mode))
  printf("is directory\n");
@end example

@subheading Implementation Notes

Supplying a 100% Unix-compatible @code{stat} function under DOS is an
implementation nightmare.  The following notes describe some of the
obscure points specific to @code{stat}s behavior in DJGPP.

1. The @samp{drive} for character devices (like @code{con}, @code{/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, files on
Windows 9X, on networked drives, etc.) the @code{st_inode} field will be
@emph{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
on plain DOS, and only for local, non-empty files/directories the inode
is guaranteed to be consistent between @code{stat} and @code{fstat}
function calls.

3. 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 @code{go32-v2}.

4. Size of directories is reported as the number of its files (sans `.' and
`..' entries) multiplied by 32 bytes (the size of directory entry).  On FAT
filesystems that support the LFN API (such as Windows 9X), the reported
size of the directory accounts for additional space used to store the long
file names.

5. Time stamp for root directories is taken from the volume label entry,
if that's available; otherwise, it is reported as 1-Jan-1980.

6. The variable @code{_djstat_flags} (@pxref{_djstat_flags}) controls
what hard-to-get fields of @code{struct stat} are needed by the
application.

7. @code{stat} should not be used to get an up-to-date info about a file
which is open and has been written to, because @code{stat} will only
return correct data after the file is closed.  Use @code{fstat}
(@pxref{fstat}) while the file is open.  Alternatively, you can call
@code{fflush} and @code{fsync} to make the OS flush all the file's data
to the disk, before calling @code{stat}.

8. The number of links @code{st_nlink} is always 1 for files other than
directories.  For directories, it is the number of subdirectories plus
2.  This is so that programs written for Unix that depend on this to
optimize recursive traversal of the directory tree, will still work.