--- 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