xnu-7195.101.1.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 80c29362615167b1fe1454fc3a482f9beb0b3610..35078abc52a582ef69c8fbffb7dbf4800b5c0ac4 100644 (file)
--- a/bsd/man/man2/open.2
+++ b/bsd/man/man2/open.2
@@ -60,7 +60,7 @@
 .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,14 +100,48 @@ as described in
 and modified by the process' umask value (see
 .Xr umask 2 ) .
 .Pp
-The flags specified are formed by
-.Em or Ns 'ing
-the following values:
+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 must include exactly one of the following file access modes:
 .Pp
 .Bd -literal -offset indent -compact
 O_RDONLY       open for reading only
 O_WRONLY       open for writing only
 O_RDWR         open for reading and writing
+.Ed
+.Pp
+In addition any combination of the following values can be
+.Em or Ns 'ed in
+.Fa oflag:
+.Pp
+.Bd -literal -offset indent -compact
 O_NONBLOCK     do not block on open or for data to become available
 O_APPEND       append on each write
 O_CREAT                create file if it does not exist
@@ -115,6 +153,7 @@ 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
+O_NOFOLLOW_ANY do not follow symlinks in the entire path.
 .Ed
 .Pp
 Opening a file with
@@ -196,6 +235,14 @@ flag.  The state of the file descriptor flags can be inspected
 using the F_GETFD fcntl.  See
 .Xr fcntl 2 .
 .Pp
+If
+.Dv O_NOFOLLOW_ANY
+is used in the mask and any component of the path passed to
+.Fn open
+is a symbolic link then the
+.Fn open
+will fail.
+.Pp
 If successful,
 .Fn open
 returns a non-negative integer, termed a file descriptor.
@@ -215,6 +262,8 @@ and
 .Pp
 The system imposes a limit on the number of file descriptors
 that can be held open simultaneously by one process.
+.Pp
+A file's metadata can be updated even if the file was opened in read-only mode.
 .Xr Getdtablesize 2
 returns the current system limit.
 .Sh RETURN VALUES
@@ -316,6 +365,11 @@ The system file table is full.
 .Dv O_NOFOLLOW
 was specified and the target is a symbolic link.
 .\" ===========
+.\" ===========
+.It Bq Er ELOOP
+.Dv O_NOFOLLOW_ANY
+was specified and and a component of the path is a symbolic link.
+.\" ===========
 .It Bq Er ENOENT
 .Dv O_CREAT
 is not set and the named file does not exist.
@@ -371,6 +425,25 @@ 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.
+.It Bq Eq EILSEQ
+The filename does not match the encoding rules.
 .El
 .Sh COMPATIBILITY
 .Fn open
@@ -392,3 +465,6 @@ An
 .Fn open
 function call appeared in 
 .At v6 .
+The
+.Fn openat
+function was introduced in OS X 10.10