xnu-4903.270.47.tar.gz

[apple/xnu.git] / bsd / man / man2 / open.2

diff --git a/bsd/man/man2/open.2 b/bsd/man/man2/open.2
index 2d121402db54249b9675bd41029bb003e94dcc6d..40a94d7d16d12c7e800d79966d362788a2906a87 100644 (file)
--- a/bsd/man/man2/open.2
+++ b/bsd/man/man2/open.2
@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2008 Apple Inc.  All rights reserved.
+.\" Copyright (c) 2010 Apple Inc.  All rights reserved.
 .\"
 .\" @APPLE_LICENSE_HEADER_START@
 .\" 
@@ -56,11 +56,11 @@
 .\"
 .\"     @(#)open.2     8.2 (Berkeley) 11/16/93
 .\"
-.Dd October 7, 2008
+.Dd November 10, 2010
 .Dt OPEN 2
 .Os BSD 4
 .Sh NAME
-.Nm open
+.Nm open , openat
 .Nd open or create a file for reading or writing
 .Sh SYNOPSIS
 .\" OH??? .Fd #include <sys/stat.h>
@@ -71,6 +71,8 @@
 .Fa "int oflag"
 .Fa "..."
 .Fc
+.Ft int
+.Fn openat "int fd" "const char *path" "int oflag" "..."
 .Sh DESCRIPTION
 The file name specified by
 .Fa path
@@ -86,8 +88,10 @@ argument may indicate that the file is to be
 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 an additional argument
 .Fa "mode_t mode" ;
 the file is created with mode
 .Fa mode
@@ -96,7 +100,36 @@ as described in
 and modified by the process' umask value (see
 .Xr umask 2 ) .
 .Pp
-The flags specified are formed by
+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 oflag
+argument and the optional fourth argument correspond exactly to
+the arguments for
+.Fn open .
+If
+.Fn openat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+argument, the current working directory is used
+and the behavior is identical to a call to
+.Fn open .
+.Pp
+The flags specified
+for the
+.Fa oflag
+argument are formed by
 .Em or Ns 'ing
 the following values:
 .Pp
@@ -114,6 +147,7 @@ O_EXLOCK    atomically obtain an exclusive lock
 O_NOFOLLOW     do not follow symlinks
 O_SYMLINK      allow open of symlinks
 O_EVTONLY      descriptor requested for event notifications only
+O_CLOEXEC      mark as close-on-exec
 .Ed
 .Pp
 Opening a file with
@@ -133,7 +167,9 @@ returns an error.
 This may be used to implement a simple exclusive-access locking mechanism.
 If
 .Dv O_EXCL
-is set and the last component of the pathname is a symbolic link,
+is set with
+.Dv O_CREAT
+and the last component of the pathname is a symbolic link,
 .Fn open
 will fail even if the symbolic link points to a non-existent name.
 .Pp
@@ -184,6 +220,15 @@ flag is only intended for monitoring a file for changes (e.g. kqueue). Note: whe
 this flag is used, the opened file will not prevent an unmount 
 of the volume that contains the file.
 .Pp
+The
+.Dv O_CLOEXEC
+flag causes the file descriptor to be marked as close-on-exec,
+setting the
+.Dv FD_CLOEXEC
+flag.  The state of the file descriptor flags can be inspected
+using the F_GETFD fcntl.  See
+.Xr fcntl 2 .
+.Pp
 If successful,
 .Fn open
 returns a non-negative integer, termed a file descriptor.
@@ -359,6 +404,23 @@ The file is a pure procedure (shared text) file that is being
 executed and the
 .Fn open
 call requests write access.
+.It Bq Eq 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 searching.
+.It Bq Eq ENOTDIR
+The
+.Fa path
+argument is not an absolute path and
+.Fa fd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
 .El
 .Sh COMPATIBILITY
 .Fn open
@@ -380,3 +442,6 @@ An
 .Fn open
 function call appeared in 
 .At v6 .
+The
+.Fn openat
+function was introduced in OS X 10.10