lstat

Syntax

#include <sys/stat.h> int lstat(const char *file, struct stat *sbuf);

Description

This function obtains the status of the file file and stores it in sbuf. If file is a symbolic link, then lstat returns information about the symbolic link. To get information about the target of a symbolic link, use stat (see section stat) instead.

sbuf has this structure:

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 */ blksize_t st_blksize; /* block size in bytes*/ uid_t st_uid; /* what getuid() returns */ dev_t st_rdev; /* The drive number (0 = a:) */ };

The st_atime, st_ctime and 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(1). 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 lstat sets the st_atime member to the same value as st_mtime if the time part of st_atime returned by the filesystem is zero (to prevent the situation where the file appears to have been created after it was last accessed, which doesn't look good).

The st_size member is an signed 32-bit integer type, so it will overflow on FAT32 volumes for files that are larger than 2GB. Therefore, if your program needs to support large files, you should treat the value of st_size as an unsigned value.

For some drives st_blksize has a default value, to improve performance. The floppy drives A: and B: default to a block size of 512 bytes. Network drives default to a block size of 4096 bytes.

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

Return Value

Zero on success, nonzero on failure (and errno set).

Portability

ANSI/ISO C	No
POSIX	No

Example

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

Implementation Notes

Supplying a 100% Unix-compatible lstat function under DOS is an implementation nightmare. The following notes describe some of the obscure points specific to lstats behavior in DJGPP.

1. The `drive' for character devices (like con, /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 st_inode field will be 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 stat, fstat and lstat function calls. (Note that two files whose names are identical but for the drive letter, will get the same invented inode, since each filesystem has its own independent inode numbering, and comparing files for identity should include the value of st_dev.)

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 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 _djstat_flags (see section _djstat_flags) controls what hard-to-get fields of struct stat are needed by the application.

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

8. The number of links 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.