From: Eric Blake Date: Wed, 7 Oct 2009 17:58:54 +0000 (-0600) Subject: doc: mention timestamp portability issues X-Git-Tag: v0.1~5332 X-Git-Url: http://erislabs.org.uk/gitweb/?a=commitdiff_plain;h=75de3afee5e99c73676c59fb03b1f506b828e3e3;p=gnulib.git doc: mention timestamp portability issues * doc/glibc-functions/lutimes.texi (lutimes): Refer to utimensat instead. * doc/posix-functions/utime.texi (utime): Likewise. * doc/posix-functions/utimes.texi (utimes): Likewise. * doc/glibc-functions/futimes.texi (futimes): Refer to futimens instead. * doc/posix-functions/futimens.texi (futimens): Mention utimens module. * doc/posix-functions/utimensat.texi (utimensat): Likewise. Mention weakness with symlink timestamps. * doc/glibc-functions/futimesat.texi (futimesat): New file; refer to utimensat/futimens instead. * doc/gnulib.texi (Glibc sys/time.h): Include new file. Signed-off-by: Eric Blake --- diff --git a/ChangeLog b/ChangeLog index f2427e466..8a34a5be9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,20 @@ 2009-10-10 Eric Blake + doc: mention timestamp portability issues + * doc/glibc-functions/lutimes.texi (lutimes): Refer to utimensat + instead. + * doc/posix-functions/utime.texi (utime): Likewise. + * doc/posix-functions/utimes.texi (utimes): Likewise. + * doc/glibc-functions/futimes.texi (futimes): Refer to futimens + instead. + * doc/posix-functions/futimens.texi (futimens): Mention utimens + module. + * doc/posix-functions/utimensat.texi (utimensat): Likewise. + Mention weakness with symlink timestamps. + * doc/glibc-functions/futimesat.texi (futimesat): New file; refer + to utimensat/futimens instead. + * doc/gnulib.texi (Glibc sys/time.h): Include new file. + test-dup2: enhance test * tests/test-dup2.c (main): Also check AT_FDCWD. diff --git a/doc/glibc-functions/futimes.texi b/doc/glibc-functions/futimes.texi index e53b6ed15..0df4706b9 100644 --- a/doc/glibc-functions/futimes.texi +++ b/doc/glibc-functions/futimes.texi @@ -12,5 +12,9 @@ Portability problems not fixed by Gnulib: @itemize @item This function is missing on some platforms: -AIX 5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, mingw, Interix 3.5, BeOS. +AIX 5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, mingw, Interix +3.5, BeOS. +@item +This function cannot set full timestamp resolution. Use +@code{futimens(fd,times)} instead. @end itemize diff --git a/doc/glibc-functions/futimesat.texi b/doc/glibc-functions/futimesat.texi new file mode 100644 index 000000000..dbd3d1de3 --- /dev/null +++ b/doc/glibc-functions/futimesat.texi @@ -0,0 +1,21 @@ +@node futimesat +@subsection @code{futimesat} +@findex futimesat + +Gnulib module: --- + +Portability problems fixed by Gnulib: +@itemize +@end itemize + +Portability problems not fixed by Gnulib: +@itemize +@item +This function is missing on some platforms: +glibc 2.3.6, MacOS X 10.3, FreeBSD 6.0, NetBSD 3.0, OpenBSD 3.8, AIX +5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 8, Cygwin 1.5.x, mingw, +Interix 3.5, BeOS. +@item +This function cannot set full timestamp resolution. Use +@code{file ? utimensat(fd,file,times,0) : futimens(fd,times)} instead. +@end itemize diff --git a/doc/glibc-functions/lutimes.texi b/doc/glibc-functions/lutimes.texi index 96308e0c1..2971c99ec 100644 --- a/doc/glibc-functions/lutimes.texi +++ b/doc/glibc-functions/lutimes.texi @@ -12,5 +12,14 @@ Portability problems not fixed by Gnulib: @itemize @item This function is missing on some platforms: -MacOS X 10.3, OpenBSD 3.8, AIX 5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, mingw, Interix 3.5, BeOS. +MacOS X 10.3, OpenBSD 3.8, AIX 5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, +Solaris 10, mingw, Interix 3.5, BeOS. +@item +This function cannot set full timestamp resolution. Use +@code{utimensat(AT_FDCWD,file,times,AT_SYMLINK_NOFOLLOW)} instead. +@item +The mere act of using @code{lstat} modifies the access time of +symlinks on some platforms, so @code{lutimes} can only effectively +change modification time: +Cygwin. @end itemize diff --git a/doc/gnulib.texi b/doc/gnulib.texi index b3085d4ad..8566eb333 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -5482,12 +5482,14 @@ This list of functions is sorted according to the header that declares them. @menu * adjtime:: * futimes:: +* futimesat:: * lutimes:: * settimeofday:: @end menu @include glibc-functions/adjtime.texi @include glibc-functions/futimes.texi +@include glibc-functions/futimesat.texi @include glibc-functions/lutimes.texi @include glibc-functions/settimeofday.texi diff --git a/doc/posix-functions/futimens.texi b/doc/posix-functions/futimens.texi index 0fb593510..2a1a77918 100644 --- a/doc/posix-functions/futimens.texi +++ b/doc/posix-functions/futimens.texi @@ -15,5 +15,20 @@ Portability problems not fixed by Gnulib: @item This function is missing on some platforms: glibc 2.3.6, MacOS X 10.3, FreeBSD 6.0, NetBSD 3.0, OpenBSD 3.8, AIX -5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, Cygwin 1.5.x, mingw, Interix 3.5, BeOS. +5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, Cygwin 1.5.x, mingw, +Interix 3.5, BeOS. +@item +This function returns a bogus value instead of failing with +@code{ENOSYS} on some platforms: +Linux kernel 2.6.21. +@item +When using @code{UTIME_OMIT} or @code{UTIME_NOW}, some systems require +the @code{tv_sec} argument to be 0, and don't necessarily handle all +file permissions in the manner required by POSIX: +Linux kernel 2.6.25. +@item +Some platforms lack the ability to change the timestamps of a file +descriptor, so this function can fail with @code{ENOSYS}. @end itemize + +The gnulib module utimens provides a similar interface. diff --git a/doc/posix-functions/utime.texi b/doc/posix-functions/utime.texi index 9b5a7eeaf..d14685c1b 100644 --- a/doc/posix-functions/utime.texi +++ b/doc/posix-functions/utime.texi @@ -15,4 +15,12 @@ file's timestamp to the current time. Portability problems not fixed by Gnulib: @itemize +@item +This function cannot set full timestamp resolution. Use +@code{utimensat(AT_FDCWD,file,times,0)} instead. +@item +On some platforms, the prototype for @code{utime} omits @code{const} +for the second argument. Fortunately, the argument is not modified, +so it is safe to cast away const: +mingw. @end itemize diff --git a/doc/posix-functions/utimensat.texi b/doc/posix-functions/utimensat.texi index 23a5582ad..1dcfe8c11 100644 --- a/doc/posix-functions/utimensat.texi +++ b/doc/posix-functions/utimensat.texi @@ -15,5 +15,26 @@ Portability problems not fixed by Gnulib: @item This function is missing on some platforms: glibc 2.3.6, MacOS X 10.3, FreeBSD 6.0, NetBSD 3.0, OpenBSD 3.8, AIX -5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, Cygwin 1.5.x, mingw, Interix 3.5, BeOS. +5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, Cygwin 1.5.x, mingw, +Interix 3.5, BeOS. +@item +This function returns a bogus value instead of failing with +@code{ENOSYS} on some platforms: +Linux kernel 2.6.21. +@item +When using @code{UTIME_OMIT} or @code{UTIME_NOW}, some systems require +the @code{tv_sec} argument to be 0, and don't necessarily handle all +file permissions in the manner required by POSIX: +Linux kernel 2.6.25. +@item +On some platforms, timestamps of symbolic links cannot be modified, so +this function fails with @code{ENOSYS} if passed the flag +@code{AT_SYMLINK_NOFOLLOW}. +@item +The mere act of using @code{lstat} modifies the access time of +symlinks on some platforms, so @code{utimensat} with +@code{AT_SYMLINK_NOFOLLOW} can only effectively change modification time: +Cygwin. @end itemize + +The gnulib module utimens provides a similar interface. diff --git a/doc/posix-functions/utimes.texi b/doc/posix-functions/utimes.texi index 8ab90d91d..5f6cb7b74 100644 --- a/doc/posix-functions/utimes.texi +++ b/doc/posix-functions/utimes.texi @@ -16,6 +16,15 @@ Portability problems not fixed by Gnulib: This function is missing on some platforms: mingw, Interix 3.5, BeOS. @item -This function is marked as ``legacy'' in POSIX. Better use @code{utime} -instead. +This function cannot set full timestamp resolution. In particular, +some platforms incorrectly round rather than truncate. Use +@code{utimensat(AT_FDCWD,file,times,0)} instead. +@item +On some platforms, @code{utimes (file, NULL)} fails to set the +file's timestamp to the current time: +glibc 2.3.3. +@item +On some platforms, @code{utimes} failed on read-only files when +@code{utime} worked fine. +glibc 2.2.5. @end itemize