Add (rough draft) documentation for fdopendir(3) and the 15 new

XXXat(2) system calls from POSIX 2008.  Editing will be done in tree.

General style discussed with jmc@, schwarze@, and deraadt@
ok jmc@

1 files changed, 106 insertions, 3 deletions

diff --git a/lib/libc/sys/utimes.2 b/lib/libc/sys/utimes.2
index 7d79f17d791..d33961ada79 100644
--- a/lib/libc/sys/utimes.2
+++ b/lib/libc/sys/utimes.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: utimes.2,v 1.10 2009/12/29 16:12:28 sobrado Exp $
+.\"	$OpenBSD: utimes.2,v 1.11 2011/07/18 23:04:40 matthew Exp $
 .\"	$NetBSD: utimes.2,v 1.9 1996/04/23 10:34:16 mycroft Exp $
 .\"
 .\" Copyright (c) 1990, 1993
@@ -30,11 +30,14 @@
 .\"
 .\"     @(#)utimes.2	8.1 (Berkeley) 6/4/93
 .\"
-.Dd $Mdocdate: December 29 2009 $
+.Dd $Mdocdate: July 18 2011 $
 .Dt UTIMES 2
 .Os
 .Sh NAME
-.Nm utimes
+.Nm utimes ,
+.Nm futimens ,
+.Nm utimensat ,
+.Nm futimens
 .Nd set file access and modification times
 .Sh SYNOPSIS
 .Fd #include <sys/time.h>
@@ -42,6 +45,12 @@
 .Fn utimes "const char *file" "const struct timeval *times"
 .Ft int
 .Fn futimes "int fd" "const struct timeval *times"
+.Fd #include <sys/stat.h>
+.Fd #include <fcntl.h>
+.Ft int
+.Fn utimensat "int fd" "const char *file" "const struct timespec times[2]" "int flag"
+.Ft int
+.Fn futimes "int fd" "const struct timespec times[2]"
 .Sh DESCRIPTION
 The access and modification times of the file named by
 .Fa path
@@ -68,6 +77,68 @@ The caller must be the owner of the file or be the superuser.
 .Pp
 In either case, the inode-change-time of the file is set to the current
 time.
+.Pp
+The
+.Fn utimensat
+and
+.Fn futimens
+are equivalent to
+.Fn utimes
+and
+.Fn futimes ,
+respectively, with the following differences.
+.Pp
+Both
+.Fn utimensat
+and
+.Fn futimens
+take two timespec values instead of two timeval values.
+Further, either of the
+.Fa tv_nsec
+fields can be set to one of the following special values defined in
+.In sys/stat.h :
+.Pp
+.Bl -tag -width UTIME_OMIT -offset indent -compact
+.It Dv UTIME_NOW
+Set the respective timestamp to the greatest value supported
+that is not greater than the current time.
+.It Dv UTIME_OMIT
+Do change the respective timestamp.
+.El
+.Pp
+Additionally, if the
+.Fa path
+argument to
+.Fn utimensat
+specifies a relative path,
+the file whose timestamps are changed is determined relative to
+the directory associated with file descriptor
+.Fa fd
+instead of the current working directory.
+.Pp
+If
+.Fn utimensat
+is passed the special value
+.Dv AT_FDCWD
+(defined in
+.In fcntl.h )
+in the
+.Fa fd
+parameter, the current working directory is used.
+.Pp
+Values for
+.Fa flag
+are constructed by bitwise-inclusive
+.Tn OR Ns 'ing
+of flags from the following list defined in
+.In fcntl.h :
+.Pp
+.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact
+.It Dv AT_SYMLINK_NOFOLLOW
+If
+.Fa path
+names a symbolic link, then the timestamps of the symbolic link are changed.
+.El
 .Sh RETURN VALUES
 Upon successful completion, a value of 0 is returned.
 Otherwise, a value of \-1 is returned and
@@ -75,6 +146,8 @@ Otherwise, a value of \-1 is returned and
 is set to indicate the error.
 .Sh ERRORS
 .Fn utimes
+and
+.Fn utimensat
 will fail if:
 .Bl -tag -width Er
 .It Bq Er EACCES
@@ -116,7 +189,23 @@ does not match the owner of the file and is not the superuser.
 The file system containing the file is mounted read-only.
 .El
 .Pp
+Additionally,
+.Fn utimensat
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa path
+argument does not specify an absolute path and the
+.Fa fd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor open for reading.
+.El
+.Pp
 .Fn futimes
+and
+.Fn futimens
 will fail if:
 .Bl -tag -width Er
 .It Bq Er EBADF
@@ -148,6 +237,14 @@ The file system containing the file is mounted read-only.
 .Sh SEE ALSO
 .Xr stat 2 ,
 .Xr utime 3
+.Sh STANDARDS
+The
+.Fn utimes ,
+.Fn utimensat ,
+and
+.Fn futimens
+functions conform to
+.St -p1003.1-2008 .
 .Sh HISTORY
 The
 .Fn utimes
@@ -157,3 +254,9 @@ The
 .Fn futimes
 function call appeared in
 .Nx 1.2 .
+The
+.Fn utimensat
+and
+.Fn futimens
+function calls appeared in
+.Ox 5.0 .