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.
@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
--- /dev/null
+@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
@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
@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
@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.
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
@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.
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
projects / gnulib.git / commitdiff