sys/stat.h
==========

POSIX specification:
 https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html

Gnulib module: sys_stat

Portability problems fixed by Gnulib module sys_stat:

  * The type mode_t is not defined on some platforms: MSVC 14.

  * Some macros, such as S_IFMT or S_IFIFO, are missing on some platforms.

  * The macros S_ISBLK, S_ISCHR, S_ISDIR, S_ISFIFO, S_ISLNK, S_ISREG, S_ISSOCK are broken on some platforms.

  * Some platforms define macros, such as S_ISDOOR, that are not defined on other platforms.

  * The functions lstat and mkdir are not declared on some platforms: mingw, MSVC 14.

  * The macros UTIME_NOW and UTIME_OMIT are missing on some platforms.

  * On some platforms, struct stat does not include st_atim, st_mtim, or st_ctim members.  Use the gnulib module stat-time for accessors to portably get at subsecond resolution.

Portability problems fixed by Gnulib module sys_stat, together with module windows-stat-inodes:

  * On Windows platforms (excluding Cygwin), st_ino is always 0.

On platforms where off_t is a 32-bit type, struct stat cannot represent the size of files or block devices 2 GiB or lager and may not work correctly on directories 2 GiB or larger. Also, on platforms where ino_t is a 32-bit type, struct stat cannot represent larger inode numbers. See Large File Support, for how to address these problems.

See Avoiding the year 2038 problem, for portability issues with the time_t components of struct stat.

Portability problems not fixed by Gnulib:

  * The macro S_IFBLK is missing on some platforms: MSVC 14.

  * On OpenVMS, st_ino is an array of three ino_t values, not a single value. b are known to represent the same file.

  * On some platforms, two different files may have the same st_dev and st_ino values, even when st_ino is nonzero:

       * GNU/Linux NFS servers that export all local file systems as a single NFS file system, if a local st_dev exceeds 255, or if a local st_ino exceeds 16777215.

       * Network Appliance NFS servers in snapshot directories; see Network Appliance bug #195.

       * ClearCase MVFS; see bug id ATRia04618.

  * On some file systems, st_size contains bogus information for symlinks; use the Gnulib module areadlink-with-size for a better way to get symlink contents.

To partially work around porting problems with Microsoft Windows and OpenVMS, you can use the Gnulib same-inode module to test whether two struct stat objects are known to represent the same file. For example, psame_inode (&a, &b) is true if the struct stat objects a and b are known to represent the same file.

Another partial workaround is to compare other file metadata such as st_mode and st_mtime on platforms where st_dev and st_ino not uniquely identify a file.  However, this does not work reliably on files whose metadata are being changed by other programs, or where the metadata happen to be equal.