add openat(2) man page

Dragonfly-bug: <http://bugs.dragonflybsd.org/issue1435>
Obtained-from:   FreeBSD

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 3186983..2e5528c 100644 (file)
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -164,4 +164,5 @@ MLINKS+=varsym.2 varsym_get.2 \
        varsym.2 varsym_set.2
 MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2
 MLINKS+=write.2 pwrite.2 write.2 pwritev.2 write.2 writev.2
+MLINKS+=open.2 openat.2
 .endif

diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2
index 074368c..5e84d13 100644 (file)
--- a/lib/libc/sys/open.2
+++ b/lib/libc/sys/open.2
@@ -33,11 +33,11 @@
 .\" $FreeBSD: src/lib/libc/sys/open.2,v 1.11.2.9 2001/12/14 18:34:01 ru Exp $
 .\" $DragonFly: src/lib/libc/sys/open.2,v 1.3 2005/07/29 23:16:04 hsu Exp $
 .\"
-.Dd November 16, 1993
+.Dd July 24, 2009
 .Dt OPEN 2
 .Os
 .Sh NAME
-.Nm open
+.Nm open , openat
 .Nd open or create a file for reading or writing
 .Sh LIBRARY
 .Lb libc
@@ -45,6 +45,8 @@
 .In fcntl.h
 .Ft int
 .Fn open "const char *path" "int flags" "..."
+.Ft int
+.Fn openat "int fd" "const char *path" "int flags" "..."
 .Sh DESCRIPTION
 The file name specified by
 .Fa path
@@ -61,8 +63,10 @@ created if it does not exist (by specifying the
 .Dv O_CREAT
 flag).
 In this case
-.Nm
-requires a third argument
+.Fn open
+and
+.Fn openat
+require a third argument
 .Fa "mode_t mode" ,
 and the file is created with mode
 .Fa mode
@@ -71,6 +75,32 @@ as described in
 and modified by the process' umask value (see
 .Xr umask 2 ) .
 .Pp
+The
+.Fn openat
+function is equivalent to the
+.Fn open
+function except in the case where the
+.Fa path
+specifies a relative path.
+In this case the file to be opened is determined relative to the directory
+associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+The
+.Fa flag
+parameter and the optional fourth parameter correspond exactly to
+the parameters of
+.Fn open .
+If
+.Fn openat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used
+and the behavior is identical to a call to
+.Fn open .
+.Pp
 The flags specified are formed by
 .Em or Ns 'ing
 the following values
@@ -165,7 +195,9 @@ Use of this flag can drastically reduce performance if not used with care.
 .Pp
 If successful,
 .Fn open
-returns a non-negative integer, termed a file descriptor.
+and
+.Fn openat
+return a non-negative integer, termed a file descriptor.
 It returns -1 on failure.
 The file pointer used to mark the current position within the
 file is set to the beginning of the file.
@@ -187,15 +219,23 @@ returns the current system limit.
 .Sh RETURN VALUES
 If successful,
 .Fn open
-returns a non-negative integer, termed a file descriptor.
-It returns -1 on failure, and sets
+and
+.Fn openat
+return a non-negative integer, termed a file descriptor.
+They return -1 on failure, and set
 .Va errno
 to indicate the error.
 .Sh ERRORS
 The named file is opened unless:
 .Bl -tag -width Er
 .It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
+A component of the path prefix is not a directory or the
+.Fa path
+argument is not an absolute path and the
+.Fa fd
+arugment is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded 255 characters,
 or an entire path name exceeded 1023 characters.
@@ -322,3 +362,18 @@ An
 .Fn open
 function call appeared in
 .At v6 .
+An
+.Fn openat
+function call appeared first in Solaris and was ported to 
+.Dx 2.3 .
+.Sh BUGS
+The Open Group Extended API Set 2 specification requires that the test
+for whether
+.Fa fd
+is searchable is based on whether
+.Fa fd
+is open for searching, not whether the underlying directory currently
+permits searches.
+The present implementation of the
+.Fa openat
+checks the current permissions of directory instead.