+.\"
+.\" Copyright (c) 2010 Apple Inc. All rights reserved.
+.\"
+.\" @APPLE_LICENSE_HEADER_START@
+.\"
+.\" This file contains Original Code and/or Modifications of Original Code
+.\" as defined in and that are subject to the Apple Public Source License
+.\" Version 2.0 (the 'License'). You may not use this file except in
+.\" compliance with the License. Please obtain a copy of the License at
+.\" http://www.opensource.apple.com/apsl/ and read it before using this
+.\" file.
+.\"
+.\" The Original Code and all software distributed under the License are
+.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+.\" Please see the License for the specific language governing rights and
+.\" limitations under the License.
+.\"
+.\" @APPLE_LICENSE_HEADER_END@
+.\"
+.\"
.\" $NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\"
.\" @(#)open.2 8.2 (Berkeley) 11/16/93
.\"
-.Dd November 16, 1993
+.Dd November 10, 2010
.Dt OPEN 2
.Os BSD 4
.Sh NAME
.Nm open
.Nd open or create a file for reading or writing
.Sh SYNOPSIS
+.\" OH??? .Fd #include <sys/stat.h>
.Fd #include <fcntl.h>
.Ft int
-.Fn open "const char *path" "int flags" "mode_t mode"
+.Fo open
+.Fa "const char *path"
+.Fa "int oflag"
+.Fa "..."
+.Fc
.Sh DESCRIPTION
The file name specified by
.Fa path
is opened
-for reading and/or writing as specified by the
-argument
-.Fa flags
-and the file descriptor returned to the calling process.
+for reading and/or writing,
+as specified by the argument
+.Fa oflag ;
+the file descriptor is returned to the calling process.
+.Pp
The
-.Fa flags
-argument may indicate the file is to be
+.Fa oflag
+argument may indicate that the file is to be
created if it does not exist (by specifying the
.Dv O_CREAT
-flag), in which case the file is created with mode
+flag). In this case,
+.Nm
+requires a third argument
+.Fa "mode_t mode" ;
+the file is created with mode
.Fa mode
as described in
.Xr chmod 2
.Pp
The flags specified are formed by
.Em or Ns 'ing
-the following values
+the following values:
.Pp
.Bd -literal -offset indent -compact
O_RDONLY open for reading only
O_APPEND append on each write
O_CREAT create file if it does not exist
O_TRUNC truncate size to 0
-O_EXCL error if create and file exists
+O_EXCL error if O_CREAT and the file exists
O_SHLOCK atomically obtain a shared lock
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
.Dv O_APPEND
-set causes each write on the file
-to be appended to the end. If
+set causes each write on the file to be appended to the end. If
.Dv O_TRUNC
is specified and the
file exists, the file is truncated to zero length.
and the file already
exists,
.Fn open
-returns an error. This may be used to
-implement a simple exclusive access locking mechanism.
+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.
+will fail even if the symbolic link points to a non-existent name.
+.Pp
If the
.Dv O_NONBLOCK
-flag is specified, do not wait for the device or file to be ready or
-available. If the
+flag is specified, do not wait for the device or file
+to be ready or available. If the
.Fn open
call would result
-in the process being blocked for some reason (e.g., waiting for
-carrier on a dialup line),
+in the process being blocked for some reason
+(e.g., waiting for carrier on a dialup line),
.Fn open
returns immediately.
-This flag also has the effect of making all subsequent I/O on the open file non-blocking.
+This flag also has the effect of making all subsequent I/O
+on the open file non-blocking.
.Pp
When opening a file, a lock with
.Xr flock 2
the request for the lock will never fail
(provided that the underlying filesystem supports locking).
.Pp
+If
+.Dv O_NOFOLLOW
+is used in the mask and the target file passed to
+.Fn open
+is a symbolic link then the
+.Fn open
+will fail.
+.Pp
+If
+.Dv O_SYMLINK
+is used in the mask and the target file passed to
+.Fn open
+is a symbolic link then the
+.Fn open
+will be for the symbolic link itself, not what it links to.
+.Pp
+The
+.Dv O_EVTONLY
+flag is only intended for monitoring a file for changes (e.g. kqueue). Note: when
+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.
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.
+The file pointer (used to mark the current position within the file)
+is set to the beginning of the file.
.Pp
-When a new file is created it is given the group of the directory
-which contains it.
+When a new file is created,
+it is given the group of the directory which contains it.
.Pp
The new descriptor is set to remain open across
.Xr execve
.Xr fcntl 2 .
.Pp
The system imposes a limit on the number of file descriptors
-open simultaneously by one process.
+that can be held open simultaneously by one process.
.Xr Getdtablesize 2
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
+.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.
-.It Bq Er ENAMETOOLONG
-A component of a pathname exceeded
-.Dv {NAME_MAX}
-characters, or an entire path name exceeded
-.Dv {PATH_MAX}
-characters.
-.It Bq Er ENOENT
-.Dv O_CREAT
-is not set and the named file does not exist.
-.It Bq Er ENOENT
-A component of the path name that must exist does not exist.
+.\" ===========
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
+.\" ===========
.It Bq Er EACCES
The required permissions (for reading and/or writing)
are denied for the given flags.
+.\" ===========
.It Bq Er EACCES
.Dv O_CREAT
is specified,
the file does not exist,
and the directory in which it is to be created
does not permit writing.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
+.\" ===========
+.It Bq Er EACCES
+.Dv O_TRUNC
+is specified and write permission is denied.
+.\" ===========
+.It Bq Er EAGAIN
+.Fa path
+specifies the slave side of a locked pseudo-terminal device.
+.\" ===========
+.It Bq Er EDQUOT
+.Dv O_CREAT
+is specified,
+the file does not exist,
+and the directory in which the entry for the new file
+is being placed cannot be extended because the
+user's quota of disk blocks on the file system
+containing the directory has been exhausted.
+.\" ===========
+.It Bq Er EDQUOT
+.Dv O_CREAT
+is specified,
+the file does not exist,
+and the user's quota of inodes on the file system
+on which the file is being created has been exhausted.
+.\" ===========
+.It Bq Er EEXIST
+.Dv O_CREAT
+and
+.Dv O_EXCL
+are specified and the file exists.
+.\" ===========
+.It Bq Er EFAULT
+.Fa Path
+points outside the process's allocated address space.
+.\" ===========
+.It Bq Er EINTR
+The
+.Fn open
+operation is interrupted by a signal.
+.\" ===========
+.It Bq Er EINVAL
+The value of
+.Fa oflag
+is not valid.
+.\" ===========
+.It Bq Er EIO
+An I/O error occurs while making the directory entry or
+allocating the inode for
+.Dv O_CREAT .
+.\" ===========
.It Bq Er EISDIR
The named file is a directory, and the arguments specify
-it is to be opened for writing.
-.It Bq Er EROFS
-The named file resides on a read-only file system,
-and the file is to be modified.
+that it is to be opened for writing.
+.\" ===========
+.It Bq Er ELOOP
+Too many symbolic links are encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ===========
.It Bq Er EMFILE
The process has already reached its limit for open file descriptors.
+.\" ===========
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeds
+.Dv {NAME_MAX}
+characters, or an entire path name exceeded
+.Dv {PATH_MAX}
+characters.
+.\" ===========
.It Bq Er ENFILE
The system file table is full.
-.It Bq Er ENXIO
-The named file is a character special or block
-special file, and the device associated with this special file
-does not exist.
-.It Bq Er EINTR
-The
-.Fn open
-operation was interrupted by a signal.
-.It Bq Er EOPNOTSUPP
-.Dv O_SHLOCK
-or
-.Dv O_EXLOCK
-is specified but the underlying filesystem does not support locking.
+.\" ===========
+.It Bq Er ELOOP
+.Dv O_NOFOLLOW
+was specified and the target is a symbolic link.
+.\" ===========
+.It Bq Er ENOENT
+.Dv O_CREAT
+is not set and the named file does not exist.
+.\" ===========
+.It Bq Er ENOENT
+A component of the path name that must exist does not exist.
+.\" ===========
.It Bq Er ENOSPC
.Dv O_CREAT
is specified,
and the directory in which the entry for the new file is being placed
cannot be extended because there is no space left on the file
system containing the directory.
+.\" ===========
.It Bq Er ENOSPC
.Dv O_CREAT
is specified,
the file does not exist,
and there are no free inodes on the file system on which the
file is being created.
-.It Bq Er EDQUOT
-.Dv O_CREAT
-is specified,
-the file does not exist,
-and the directory in which the entry for the new file
-is being placed cannot be extended because the
-user's quota of disk blocks on the file system
-containing the directory has been exhausted.
-.It Bq Er EDQUOT
-.Dv O_CREAT
-is specified,
-the file does not exist,
-and the user's quota of inodes on the file system on
-which the file is being created has been exhausted.
-.It Bq Er EIO
-An I/O error occurred while making the directory entry or
-allocating the inode for
-.Dv O_CREAT .
+.\" ===========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
+.\" ===========
+.It Bq Er ENXIO
+The named file is a character-special or block-special file
+and the device associated with this special file does not exist.
+.\" ===========
+.It Bq Er ENXIO
+O_NONBLOCK and O_WRONLY are set, the file is a FIFO,
+and no process has it open for reading.
+.\" ===========
+.It Bq Er EOPNOTSUPP
+.Dv O_SHLOCK
+or
+.Dv O_EXLOCK
+is specified, but the underlying filesystem does not support locking.
+.\" ===========
+.It Bq Er EOPNOTSUPP
+An attempt is made to open a socket (not currently implemented).
+.\" ===========
+.It Bq Er EOVERFLOW
+The named file is a regular file
+and its size does not fit in an object of type off_t.
+.\" ===========
+.It Bq Er EROFS
+The named file resides on a read-only file system,
+and the file is to be modified.
+.\" ===========
.It Bq Er ETXTBSY
The file is a pure procedure (shared text) file that is being
executed and the
.Fn open
call requests write access.
-.It Bq Er EFAULT
-.Fa Path
-points outside the process's allocated address space.
-.It Bq Er EEXIST
-.Dv O_CREAT
-and
-.Dv O_EXCL
-were specified and the file exists.
-.It Bq Er EOPNOTSUPP
-An attempt was made to open a socket (not currently implemented).
.El
+.Sh COMPATIBILITY
+.Fn open
+on a terminal device (i.e., /dev/console)
+will now make that device a controlling terminal for the process.
+Use the O_NOCTTY flag to open a terminal device
+without changing your controlling terminal.
.Sh SEE ALSO
.Xr chmod 2 ,
.Xr close 2 ,
.Xr getdtablesize 2 ,
.Xr lseek 2 ,
.Xr read 2 ,
-.Xr write 2 ,
-.Xr umask 2
+.Xr umask 2 ,
+.Xr write 2
.Sh HISTORY
An
.Fn open
projects / apple / xnu.git / blobdiff