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@
 .\" 
 .\"
 .\" @APPLE_LICENSE_HEADER_START@
 .\" 


@@ -56,11 +56,11 @@
 .\"
 .\"     @(#)open.2     8.2 (Berkeley) 11/16/93
 .\"
 .\"
 .\"     @(#)open.2     8.2 (Berkeley) 11/16/93
 .\"

-.Dd October 7, 2008
+.Dd November 10, 2010

 .Dt OPEN 2
 .Os BSD 4
 .Sh NAME
 .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>
 .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
 .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
 .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,
 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
 .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
 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
 .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_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
 .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
 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
 .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
 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.
 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.
 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
 .El
 .Sh COMPATIBILITY
 .Fn open


@@ -380,3 +442,6 @@ An
 .Fn open
 function call appeared in 
 .At v6 .
 .Fn open
 function call appeared in 
 .At v6 .

+The
+.Fn openat
+function was introduced in OS X 10.10