]> Savannah Git Hosting - gnulib.git/commitdiff
doc: cover st_ino issues once; add OpenVMS etc.
authorPaul Eggert <eggert@cs.ucla.edu>
Sat, 31 Dec 2011 21:38:25 +0000 (13:38 -0800)
committerPaul Eggert <eggert@cs.ucla.edu>
Sat, 31 Dec 2011 21:38:50 +0000 (13:38 -0800)
* doc/posix-functions/stat.texi (stat):
* doc/posix-functions/lstat.texi (lstat):
* doc/posix-functions/fstatat.texi (fstatat):
* doc/posix-functions/fstat.texi (fstat):
Move general 'struct stat' stuff to sys_stat.texi,
leaving behind a pointer.
* doc/posix-headers/sys_stat.texi (sys/stat.h):
Merge duplicate info about 'struct stat' problems into here.
Mention issues with OpenVMS, GNU/Linux NFS, NetApp, ClearCase,
and suggest partial workarounds.

ChangeLog
doc/posix-functions/fstat.texi
doc/posix-functions/fstatat.texi
doc/posix-functions/lstat.texi
doc/posix-functions/stat.texi
doc/posix-headers/sys_stat.texi

index e6065e52cf81eed0e8340827382bdce6059468fd..b380dfb38b11fdf5d1a82707f639b74a9516d3de 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2011-12-31  Paul Eggert  <eggert@cs.ucla.edu>
 
+       doc: cover st_ino issues once; add OpenVMS etc.
+       * doc/posix-functions/stat.texi (stat):
+       * doc/posix-functions/lstat.texi (lstat):
+       * doc/posix-functions/fstatat.texi (fstatat):
+       * doc/posix-functions/fstat.texi (fstat):
+       Move general 'struct stat' stuff to sys_stat.texi,
+       leaving behind a pointer.
+       * doc/posix-headers/sys_stat.texi (sys/stat.h):
+       Merge duplicate info about 'struct stat' problems into here.
+       Mention issues with OpenVMS, GNU/Linux NFS, NetApp, ClearCase,
+       and suggest partial workarounds.
+
        same-inode: port to OpenVMS
        * lib/same-inode.h (SAME_INODE): Port to OpenVMS by checking all
        three st_ino values.
index 31b4365de0c6e4b441e7fcee952168fd836f969b..0f5b8609381076dd708d275b2b4bb97ff658f92e 100644 (file)
@@ -20,6 +20,8 @@ report the size of files or block devices larger than 2 GB.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+@xref{sys/stat.h}, for general portability problems with @code{struct stat}.
+@item
 On Cygwin, @code{fstat} applied to the file descriptors 0 and 1, returns
 different @code{st_ino} values, even if standard input and standard output
 are not redirected and refer to the same terminal.
index fcb2b3052cfa46259834f7c75699573b2d6f84ad..8b8604f46f1bc5a0b45f73ead59622766da98311 100644 (file)
@@ -30,9 +30,5 @@ Solaris 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
-On Windows platforms (excluding Cygwin), @code{st_ino} is always 0.
-@item
-On some file systems, @code{st_size} contains bogus information for
-symlinks; use the gnulib module areadlink-with-size for a better way
-to get symlink contents.
+@xref{sys/stat.h}, for general portability problems with @code{struct stat}.
 @end itemize
index 8ffa66f5cd1edb060d30dce28852ada1387208be..6f5cfc25c2dd6ccd4ef944f97c8efb9f90ad58e8 100644 (file)
@@ -28,15 +28,5 @@ On Windows platforms (excluding Cygwin), symlinks are not supported, so
 Portability problems not fixed by Gnulib:
 @itemize
 @item
-On Windows platforms (excluding Cygwin), @code{st_ino} is always 0.
-@item
-Because of the definition of @code{struct stat}, it is not possible to
-portably replace @code{stat} via an object-like macro.  Therefore,
-expressions such as @code{(islnk ? lstat : stat) (name, buf)} are not
-portable, and should instead be written @code{islnk ? lstat (name,
-buf) : stat (name, buf)}.
-@item
-On some file systems, @code{st_size} contains bogus information for
-symlinks; use the gnulib module areadlink-with-size for a better way
-to get symlink contents.
+@xref{sys/stat.h}, for general portability problems with @code{struct stat}.
 @end itemize
index 09c383931c8efffaa4776d341e71f153ea4d07ef..f92d3a6855539a753e3d261e99c3dd00c6bbfb44 100644 (file)
@@ -25,11 +25,11 @@ mingw, MSVC 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+@xref{sys/stat.h}, for general portability problems with @code{struct stat}.
+@item
 Cygwin's @code{stat} function sometimes sets @code{errno} to @code{EACCES} when
 @code{ENOENT} would be more appropriate.
 @item
-On Windows platforms (excluding Cygwin), @code{st_ino} is always 0.
-@item
 Because of the definition of @code{struct stat}, it is not possible to
 portably replace @code{stat} via an object-like macro.  Therefore,
 expressions such as @code{(islnk ? lstat : stat) (name, buf)} are not
index 47b29f7930e1f0e4780e63a9d4e4f2c4261b9d8a..bd644f6007116dad9f0839894d5335053aae1c3d 100644 (file)
@@ -36,4 +36,40 @@ Portability problems not fixed by Gnulib:
 @item
 The macro @code{S_IFBLK} is missing on some platforms:
 MSVC 9.
+@item
+On Windows platforms (excluding Cygwin), @code{st_ino} is always 0.
+@item
+On OpenVMS, @code{st_ino} is an array of three @code{ino_t} values,
+not a single value.
+@item
+To partially work around the previous two problems, you can test for
+nonzero @code{st_ino} and use the Gnulib @code{same-inode} module to
+compare nonzero values.  For example, @code{(a.st_ino && SAME_INODE
+(a, b))} is true if the @code{struct stat} values @code{a} and
+@code{b} are known to represent the same file, @code{(a.st_ino &&
+!SAME_INODE (a, b))} is true if they are known to represent different
+files, and @code{!a.st_ino} is true if it is not known whether they
+represent different files.
+@item
+On some platforms, two different files may have the same @code{st_dev}
+and @code{st_ino} values, even when @code{st_ino} is nonzero:
+@itemize
+@item
+GNU/Linux NFS servers that export all local file systems as a single
+NFS file system, if a local @code{st_dev} exceeds 255, or if a local
+@code{st_ino} exceeds 16777215.
+@item
+Network Appliance NFS servers in snapshot directories; see Network
+Appliance bug #195.
+@item
+ClearCase MVFS; see bug id ATRia04618.
+@end itemize
+One partial workaround is to compare other file metadata such as
+@code{st_mode} and @code{st_mtime} to detect this bug, but this
+approach does not work on files whose metadata are being changed by
+other programs.
+@item
+On some file systems, @code{st_size} contains bogus information for
+symlinks; use the Gnulib module @code{areadlink-with-size} for a
+better way to get symlink contents.
 @end itemize