Mercurial > hg > octave-kai > gnulib-hg
changeset 12155:a12f708060ff
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 <ebb9@byu.net>
author | Eric Blake <ebb9@byu.net> |
---|---|
date | Wed, 07 Oct 2009 11:58:54 -0600 |
parents | 70f5bc44922b |
children | 3c7d1f073266 |
files | ChangeLog doc/glibc-functions/futimes.texi doc/glibc-functions/futimesat.texi doc/glibc-functions/lutimes.texi doc/gnulib.texi doc/posix-functions/futimens.texi doc/posix-functions/utime.texi doc/posix-functions/utimensat.texi doc/posix-functions/utimes.texi |
diffstat | 9 files changed, 110 insertions(+), 6 deletions(-) [+] |
line wrap: on
line diff
--- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,20 @@ 2009-10-10 Eric Blake <ebb9@byu.net> + 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.
--- a/doc/glibc-functions/futimes.texi +++ b/doc/glibc-functions/futimes.texi @@ -12,5 +12,9 @@ @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
new file mode 100644 --- /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
--- a/doc/glibc-functions/lutimes.texi +++ b/doc/glibc-functions/lutimes.texi @@ -12,5 +12,14 @@ @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
--- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -5482,12 +5482,14 @@ @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
--- a/doc/posix-functions/futimens.texi +++ b/doc/posix-functions/futimens.texi @@ -15,5 +15,20 @@ @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.
--- a/doc/posix-functions/utime.texi +++ b/doc/posix-functions/utime.texi @@ -15,4 +15,12 @@ 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
--- a/doc/posix-functions/utimensat.texi +++ b/doc/posix-functions/utimensat.texi @@ -15,5 +15,26 @@ @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.
--- a/doc/posix-functions/utimes.texi +++ b/doc/posix-functions/utimes.texi @@ -16,6 +16,15 @@ 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