diff options
Diffstat (limited to 'lib/libc/sys/open.2')
| -rw-r--r-- | lib/libc/sys/open.2 | 352 |
1 files changed, 352 insertions, 0 deletions
diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 new file mode 100644 index 0000000..c494388 --- /dev/null +++ b/lib/libc/sys/open.2 @@ -0,0 +1,352 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)open.2 8.2 (Berkeley) 11/16/93 +.\" $FreeBSD$ +.\" +.Dd November 16, 1993 +.Dt OPEN 2 +.Os +.Sh NAME +.Nm open +.Nd open or create a file for reading or writing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn open "const char *path" "int flags" "..." +.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. +The +.Fa flags +argument may indicate the file is to be +created if it does not exist (by specifying the +.Dv O_CREAT +flag). +In this case +.Fn open +requires a third argument +.Fa "mode_t mode" , +and the file is created with mode +.Fa mode +as described in +.Xr chmod 2 +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 +.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 +O_NONBLOCK do not block on open +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_SHLOCK atomically obtain a shared lock +O_EXLOCK atomically obtain an exclusive lock +O_DIRECT eliminate or reduce cache effects +O_FSYNC synchronous writes +O_SYNC synchronous writes +O_NOFOLLOW do not follow symlinks +O_NOCTTY don't assign controlling terminal +.Ed +.Pp +Opening a file with +.Dv O_APPEND +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. +If +.Dv O_EXCL +is set with +.Dv O_CREAT +and the file already +exists, +.Fn open +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, +.Fn open +will fail even if the symbolic +link points to a non-existent name. +If the +.Dv O_NONBLOCK +flag is specified and the +.Fn open +system call would result +in the process being blocked for some reason (e.g., waiting for +carrier on a dialup line), +.Fn open +returns immediately. +The descriptor remains in non-blocking mode for subsequent operations. +.Pp +If +.Dv O_FSYNC +is used in the mask, all writes will +immediately be written to disk, +the kernel will not cache written data +and all writes on the descriptor will not return until +the data to be written completes. +.Pp +.Dv O_SYNC +is a synonym for +.Dv O_FSYNC +required by +.Tn POSIX . +.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 +When opening a file, a lock with +.Xr flock 2 +semantics can be obtained by setting +.Dv O_SHLOCK +for a shared lock, or +.Dv O_EXLOCK +for an exclusive lock. +If creating a file with +.Dv O_CREAT , +the request for the lock will never fail +(provided that the underlying file system supports locking). +.Pp +.Dv O_DIRECT +may be used to minimize or eliminate the cache effects of reading and writing. +The system will attempt to avoid caching the data you read or write. +If it cannot avoid caching the data, +it will minimize the impact the data has on the cache. +Use of this flag can drastically reduce performance if not used with care. +.Pp +.Dv O_NOCTTY +may be used to ensure the OS does not assign this file as the +controlling terminal when it opens a tty device. +This is the default on +.Fx , +but is present for +.Tn POSIX +compatibility. +The +.Fn open +system call will not assign controlling terminals on +.Fx . +.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. +.Pp +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 2 +system calls; see +.Xr close 2 +and +.Xr fcntl 2 . +.Pp +The system imposes a limit on the number of file descriptors +open simultaneously by one process. +The +.Xr getdtablesize 2 +system call 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 255 characters, +or an entire path name exceeded 1023 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 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. +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EMLINK +.Dv O_NOFOLLOW +was specified and the target is a symbolic link. +.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 +The named file is a fifo, no process has +it open for reading, and the arguments specify it is +to be opened for writing. +.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 file system does not support locking. +.It Bq Er EOPNOTSUPP +The named file is a special file mounted through a file system that +does not support access to it (e.g.\& NFS). +.It Bq Er EWOULDBLOCK +.Dv O_NONBLOCK +and one of +.Dv O_SHLOCK +or +.Dv O_EXLOCK +is specified and the file is locked. +.It Bq Er ENOSPC +.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 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 ETXTBSY +The file is a pure procedure (shared text) file that is being +executed and the +.Fn open +system call requests write access. +.It Bq Er EFAULT +The +.Fa path +argument +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). +.It Bq Er EINVAL +An attempt was made to open a descriptor with an illegal combination +of +.Dv O_RDONLY , +.Dv O_WRONLY , +and +.Dv O_RDWR . +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr close 2 , +.Xr dup 2 , +.Xr fhopen 2 , +.Xr getdtablesize 2 , +.Xr getfh 2 , +.Xr lgetfh 2 , +.Xr lseek 2 , +.Xr read 2 , +.Xr umask 2 , +.Xr write 2 , +.Xr fopen 3 +.Sh HISTORY +The +.Fn open +function appeared in +.At v6 . |
