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, 58 insertions, 6 deletions

diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2
index 7e9ea5dfb50..45b4ee28d8f 100644
--- a/lib/libc/sys/open.2
+++ b/lib/libc/sys/open.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: open.2,v 1.38 2011/07/12 18:41:38 matthew Exp $
+.\"	$OpenBSD: open.2,v 1.39 2011/07/18 23:04:40 matthew Exp $
 .\"	$NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
@@ -30,16 +30,19 @@
 .\"
 .\"     @(#)open.2	8.2 (Berkeley) 11/16/93
 .\"
-.Dd $Mdocdate: July 12 2011 $
+.Dd $Mdocdate: July 18 2011 $
 .Dt OPEN 2
 .Os
 .Sh NAME
-.Nm open
+.Nm open ,
+.Nm openat
 .Nd open or create a file for reading or writing
 .Sh SYNOPSIS
 .Fd #include <fcntl.h>
 .Ft int
 .Fn open "const char *path" "int flags" "mode_t mode"
+.Ft int
+.Fn openat "int fd" "const char *path" "int flags" "mode_t mode"
 .Sh DESCRIPTION
 The file name specified by
 .Fa path
@@ -62,7 +65,8 @@ and modified by the process' umask value (see
 .Pp
 The flags specified are formed by bitwise-inclusive
 .Tn OR Ns 'ing
-the following values.
+the following values defined in
+.In fcntl.h .
 Exactly one of the first three values (file access modes) must be specified:
 .Pp
 .Bl -tag -width O_DIRECTORY -offset indent -compact
@@ -185,6 +189,30 @@ The system imposes a limit on the number of file descriptors
 open simultaneously by one process.
 .Xr getdtablesize 3
 returns the current system limit.
+.Pp
+The
+.Fn openat
+function is equivalent to
+.Fn open
+except that where
+.Fa path
+specifies a relative path,
+the file to be opened is determined relative to
+the directory associated with file descriptor
+.Fa fd
+instead of the current working directory.
+.Pp
+If
+.Fn openat
+is passed the special value
+.Dv AT_FDCWD
+(defined in
+.In fcntl.h )
+in the
+.Fa fd
+parameter, the current working directory is used
+and the behavior is identical to a call to
+.Fn open .
 .Sh RETURN VALUES
 If successful,
 .Fn open
@@ -193,7 +221,11 @@ Otherwise, a value of \-1 is returned and
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
-The named file is opened unless:
+The
+.Fn open
+and
+.Fn openat
+functions will fail if:
 .Bl -tag -width Er
 .It Bq Er ENOTDIR
 A component of the path prefix is not a directory.
@@ -324,6 +356,20 @@ An attempt was made to open a socket (not currently implemented).
 An attempt was made to open a terminal device that requires exclusive
 access and the specified device has already be opened.
 .El
+.Pp
+Additionally, the
+.Fn openat
+function 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
 .Sh SEE ALSO
 .Xr chflags 2 ,
 .Xr chmod 2 ,
@@ -338,7 +384,9 @@ access and the specified device has already be opened.
 .Sh STANDARDS
 The
 .Fn open
-function conforms to
+and
+.Fn openat
+functions conform to
 .St -p1003.1-2008 .
 .Pp
 .Dv POSIX
@@ -362,6 +410,10 @@ An
 .Fn open
 function call appeared in
 .At v2 .
+The
+.Fn openat
+function call appeared in
+.Ox 5.0 .
 .Sh CAVEATS
 The
 .Dv O_TRUNC