From: Paul Eggert Date: Sat, 31 Dec 2011 21:38:25 +0000 (-0800) Subject: doc: cover st_ino issues once; add OpenVMS etc. X-Git-Tag: v0.1~1328 X-Git-Url: http://erislabs.org.uk/gitweb/?a=commitdiff_plain;h=55c6e4b6fe65fdfd5154228209a5c9828bb8ec9d;p=gnulib.git 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. --- diff --git a/ChangeLog b/ChangeLog index e6065e52c..b380dfb38 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,17 @@ 2011-12-31 Paul Eggert + 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. diff --git a/doc/posix-functions/fstat.texi b/doc/posix-functions/fstat.texi index 31b4365de..0f5b86093 100644 --- a/doc/posix-functions/fstat.texi +++ b/doc/posix-functions/fstat.texi @@ -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. diff --git a/doc/posix-functions/fstatat.texi b/doc/posix-functions/fstatat.texi index fcb2b3052..8b8604f46 100644 --- a/doc/posix-functions/fstatat.texi +++ b/doc/posix-functions/fstatat.texi @@ -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 diff --git a/doc/posix-functions/lstat.texi b/doc/posix-functions/lstat.texi index 8ffa66f5c..6f5cfc25c 100644 --- a/doc/posix-functions/lstat.texi +++ b/doc/posix-functions/lstat.texi @@ -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 diff --git a/doc/posix-functions/stat.texi b/doc/posix-functions/stat.texi index 09c383931..f92d3a685 100644 --- a/doc/posix-functions/stat.texi +++ b/doc/posix-functions/stat.texi @@ -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 diff --git a/doc/posix-headers/sys_stat.texi b/doc/posix-headers/sys_stat.texi index 47b29f793..bd644f600 100644 --- a/doc/posix-headers/sys_stat.texi +++ b/doc/posix-headers/sys_stat.texi @@ -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