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, 51 insertions, 3 deletions

diff --git a/lib/libc/sys/mknod.2 b/lib/libc/sys/mknod.2
index 2ae76c5b63e..dca64d12ee0 100644
--- a/lib/libc/sys/mknod.2
+++ b/lib/libc/sys/mknod.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mknod.2,v 1.12 2007/05/31 19:19:33 jmc Exp $
+.\"	$OpenBSD: mknod.2,v 1.13 2011/07/18 23:04:40 matthew Exp $
 .\"	$NetBSD: mknod.2,v 1.6 1995/02/27 12:34:33 cgd Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
@@ -30,16 +30,20 @@
 .\"
 .\"     @(#)mknod.2	8.1 (Berkeley) 6/4/93
 .\"
-.Dd $Mdocdate: May 31 2007 $
+.Dd $Mdocdate: July 18 2011 $
 .Dt MKNOD 2
 .Os
 .Sh NAME
-.Nm mknod
+.Nm mknod ,
+.Nm mknodat
 .Nd make a special file node
 .Sh SYNOPSIS
 .Fd #include <sys/stat.h>
+.Fd #include <fcntl.h>
 .Ft int
 .Fn mknod "const char *path" "mode_t mode" "dev_t dev"
+.Ft int
+.Fn mknodat "int fd" "const char *path" "mode_t mode" "dev_t dev"
 .Sh DESCRIPTION
 The device special file
 .Fa path
@@ -66,6 +70,30 @@ is ignored.
 .Pp
 .Fn mknod
 requires superuser privileges.
+.Pp
+The
+.Fn mknodat
+function is equivalent to
+.Fn mknod
+except that where
+.Fa path
+specifies a relative path,
+the newly created device special file is created relative to
+the directory associated with file descriptor
+.Fa fd
+instead of the current working directory.
+.Pp
+If
+.Fn mknodat
+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 mknod .
 .Sh RETURN VALUES
 Upon successful completion a value of 0 is returned.
 Otherwise, a value of \-1 is returned and
@@ -73,6 +101,8 @@ Otherwise, a value of \-1 is returned and
 is set to indicate the error.
 .Sh ERRORS
 .Fn mknod
+and
+.Fn mknodat
 will fail and the file will be not created if:
 .Bl -tag -width Er
 .It Bq Er ENOTDIR
@@ -120,6 +150,20 @@ The process is running within an alternate root directory, as
 created by
 .Xr chroot 2 .
 .El
+Additionally,
+.Fn mknodat
+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
 .Sh SEE ALSO
 .Xr chmod 2 ,
 .Xr chroot 2 ,
@@ -130,3 +174,7 @@ A
 .Fn mknod
 function call appeared in
 .At v6 .
+The
+.Fn mknodat
+function appeared in
+.Ox 5.0 .