diff options
Diffstat (limited to 'man2/open.2')
| -rw-r--r-- | man2/open.2 | 448 |
1 files changed, 448 insertions, 0 deletions
diff --git a/man2/open.2 b/man2/open.2 new file mode 100644 index 000000000..47490f860 --- /dev/null +++ b/man2/open.2 @@ -0,0 +1,448 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1994-08-21 by Michael Haardt +.\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl> +.\" Modified 1996-05-13 by Thomas Koenig +.\" Modified 1996-12-20 by Michael Haardt +.\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl> +.\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk> +.\" Modified 1999-06-03 by Michael Haardt +.\" Modified 2002-05-07 by Michael Kerrisk <mtk16@ext.canterbury.ac.nz> +.\" Modified 2004-06-23 by Michael Kerrisk <mtk16@ext.canterbury.ac.nz> +.\" +.TH OPEN 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +open, creat \- open and possibly create a file or device +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/stat.h> +.B #include <fcntl.h> +.sp +.BI "int open(const char *" pathname ", int " flags ); +.BI "int open(const char *" pathname ", int " flags ", mode_t " mode ); +.BI "int creat(const char *" pathname ", mode_t " mode ); +.fi +.SH DESCRIPTION +The +.B open() +system call is used to convert a pathname into a file descriptor +(a small, non-negative integer for use in subsequent I/O as with +.BR read ", " write ", etc.)." +When the call is successful, the file descriptor returned will be +the lowest file descriptor not currently open for the process. +This call creates a new open file, not shared with any other process. +(But shared open files may arise via the +.BR fork (2) +system call.) +The new file descriptor is set to remain open across exec functions +(see +.BR fcntl (2)). +The file offset is set to the beginning of the file. + +The parameter +.I flags +is one of +.BR O_RDONLY ", " O_WRONLY " or " O_RDWR +which request opening the file read-only, write-only or read/write, +respectively, +.RI bitwise- or 'd +with zero or more of the following: +.TP +.B O_CREAT +If the file does not exist it will be created. +The owner (user ID) of the file is set to the effective user ID +of the process. The group ownership (group ID) is set either to +the effective group ID of the process or to the group ID of the +parent directory (depending on filesystem type and mount options, +and the mode of the parent directory, see, e.g., the mount options +.I bsdgroups +and +.I sysvgroups +of the ext2 filesystem, as described in +.BR mount (8)). +.TP +.B O_EXCL +When used with +.BR O_CREAT , +if the file already exists it is an error and the +.B open +will fail. In this context, a symbolic link exists, regardless +of where its points to. +.B O_EXCL +is broken on NFS file systems, programs which rely on it for performing +locking tasks will contain a race condition. The solution for performing +atomic file locking using a lockfile is to create a unique file on the same +fs (e.g., incorporating hostname and pid), use +.BR link (2) +to make a link to the lockfile. If \fBlink()\fP returns 0, the lock is +successful. Otherwise, use +.BR stat (2) +on the unique file to check if its link count has increased to 2, +in which case the lock is also successful. +.TP +.B O_NOCTTY +If +.I pathname +refers to a terminal device \(em see +.BR tty (4) +\(em it will not become the process's controlling terminal even if the +process does not have one. +.TP +.B O_TRUNC +If the file already exists and is a regular file and the open mode allows +writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0. +If the file is a FIFO or terminal device file, the O_TRUNC +flag is ignored. Otherwise the effect of O_TRUNC is unspecified. +.TP +.B O_APPEND +The file is opened in append mode. Before each +.BR write , +the file pointer is positioned at the end of the file, +as if with +.BR lseek . +.B O_APPEND +may lead to corrupted files on NFS file systems if more than one process +appends data to a file at once. This is because NFS does not support +appending to a file, so the client kernel has to simulate it, which +can't be done without a race condition. +.TP +.BR O_NONBLOCK " or " O_NDELAY +When possible, the file is opened in non-blocking mode. Neither the +.B open +nor any subsequent operations on the file descriptor which is +returned will cause the calling process to wait. +For the handling of FIFOs (named pipes), see also +.BR fifo (4). +This mode need not have any effect on files other than FIFOs. +.TP +.B O_SYNC +The file is opened for synchronous I/O. Any +.BR write s +on the resulting file descriptor will block the calling process until +the data has been physically written to the underlying hardware. +.I See RESTRICTIONS below, though. +.TP +.B O_NOFOLLOW +If \fIpathname\fR is a symbolic link, then the open fails. This is a +FreeBSD extension, which was added to Linux in version 2.1.126. +Symbolic links in earlier components of the pathname will still be +followed. The headers from glibc 2.0.100 and later include a +definition of this flag; \fIkernels before 2.1.126 will ignore it if +used\fR. +.TP +.B O_DIRECTORY +If \fIpathname\fR is not a directory, cause the open to fail. This +flag is Linux-specific, and was added in kernel version 2.1.126, to +avoid denial-of-service problems if \fBopendir\fR(3) is called on a +FIFO or tape device, but should not be used outside of the +implementation of \fBopendir\fR. +.TP +.B O_DIRECT +Try to minimize cache effects of the I/O to and from this file. +In general this will degrade performance, but it is useful in +special situations, such as when applications do their own caching. +File I/O is done directly to/from user space buffers. +The I/O is synchronous, i.e., at the completion of the +.BR read (2) +or +.BR write (2) +system call, data is guaranteed to have been transferred. +Under Linux 2.4 transfer sizes, and the alignment of user buffer +and file offset must all be multiples of the logical block size +of the file system. Under Linux 2.6 alignment to 512-byte boundaries +suffices. +.\" Alignment should satisfy requirements for the underlying device +.\" There may be coherency problems. +.br +A semantically similar interface for block devices is described in +.BR raw (8). +.TP +.B O_ASYNC +Generate a signal (SIGIO by default, but this can be changed via +.BR fcntl (2)) +when input or output becomes possible on this file descriptor. +This feature is only available for terminals, pseudo-terminals, and +sockets. See +.BR fcntl (2) +for further details. +.TP +.B O_LARGEFILE +(LFS) +Allow files whose sizes cannot be represented in an +.B off_t +(but can be represented in an +.BR off64_t ) +to be opened. +.PP +Some of these optional flags can be altered using +.B fcntl +after the file has been opened. + +The argument +.I mode +specifies the permissions to use in case a new file is created. It is +modified by the process's +.BR umask +in the usual way: the permissions of the created file are +.BR "(mode & ~umask)" . +Note that this mode only applies to future accesses of the +newly created file; the +.B open +call that creates a read-only file may well return a read/write +file descriptor. +.PP +The following symbolic constants are provided for +.IR mode : +.TP +.B S_IRWXU +00700 user (file owner) has read, write and execute permission +.TP +.B S_IRUSR (S_IREAD) +00400 user has read permission +.TP +.B S_IWUSR (S_IWRITE) +00200 user has write permission +.TP +.B S_IXUSR (S_IEXEC) +00100 user has execute permission +.TP +.B S_IRWXG +00070 group has read, write and execute permission +.TP +.B S_IRGRP +00040 group has read permission +.TP +.B S_IWGRP +00020 group has write permission +.TP +.B S_IXGRP +00010 group has execute permission +.TP +.B S_IRWXO +00007 others have read, write and execute permission +.TP +.B S_IROTH +00004 others have read permission +.TP +.B S_IWOTH +00002 others have write permisson +.TP +.B S_IXOTH +00001 others have execute permission +.PP +.I mode +must be specified when +.B O_CREAT +is in the +.IR flags , +and is ignored otherwise. + +.B creat +is equivalent to +.B open +with +.I flags +equal to +.BR O_CREAT|O_WRONLY|O_TRUNC . +.SH "RETURN VALUE" +.BR open " and " creat +return the new file descriptor, or \-1 if an error occurred (in which case, +.I errno +is set appropriately). +Note that +.B open +can open device special files, but +.B creat +cannot create them - use +.BR mknod (2) +instead. +.LP +On NFS file systems with UID mapping enabled, \fBopen\fP may return a file +descriptor but e.g. \fBread\fP(2) requests are denied with \fBEACCES\fP. +This is because the client performs \fBopen\fP by checking the permissions, +but UID mapping is performed by the server upon read and write requests. + +If the file is newly created, its atime, ctime, mtime fields are set +to the current time, and so are the ctime and mtime fields of the +parent directory. +Otherwise, if the file is modified because of the O_TRUNC flag, +its ctime and mtime fields are set to the current time. + +.SH ERRORS +.TP +.B EACCES +The requested access to the file is not allowed, or search permission +is denied for one of the directories in the path prefix of +.IR pathname , +or the file did not exist yet and write access to the parent directory +is not allowed. +(See also +.BR path_resolution (2).) +.TP +.B EEXIST +.I pathname +already exists and +.BR O_CREAT " and " O_EXCL +were used. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EISDIR +.I pathname +refers to a directory and the access requested involved writing +(that is, +.B O_WRONLY +or +.B O_RDWR +is set). +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname , +or \fBO_NOFOLLOW\fR was specified but +.I pathname +was a symbolic link. +.TP +.B EMFILE +The process already has the maximum number of files open. +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B ENODEV +.I pathname +refers to a device special file and no corresponding device exists. +(This is a Linux kernel bug - in this situation ENXIO must be returned.) +.TP +.B ENOENT +O_CREAT is not set and the named file does not exist. +Or, a directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +.I pathname +was to be created but the device containing +.I pathname +has no room for the new file. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory, or \fBO_DIRECTORY\fR was specified and +.I pathname +was not a directory. +.TP +.B ENXIO +O_NONBLOCK | O_WRONLY is set, the named file is a FIFO and +no process has the file open for reading. +Or, the file is a device special file and no corresponding device exists. +.TP +.B EOVERFLOW +.I pathname +refers to a regular file, too large to be opened - see O_LARGEFILE above. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem and write access was +requested. +.TP +.B ETXTBSY +.I pathname +refers to an executable image which is currently being executed and +write access was requested. +.SH NOTE +Under Linux, the O_NONBLOCK flag indicates that one wants to open +but does not necessarily have the intention to read or write. +This is typically used to open devices in order to get a file descriptor +for use with +.BR ioctl (2). +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3. +The +.B O_NOFOLLOW +and +.B O_DIRECTORY +flags are Linux-specific. +One may have to define the +.B _GNU_SOURCE +macro to get their definitions. +.LP +The (undefined) effect of +.B O_RDONLY | O_TRUNC +various among implementations. On many systems the file is actually +truncated. +.\" Linux 2.0, 2.5: truncate +.\" Solaris 5.7, 5.8: truncate +.\" Irix 6.5: truncate +.\" Tru64 5.1B: truncate +.\" HP-UX 11.22: truncate +.\" FreeBSD 4.7: truncate +.LP +The +.B O_DIRECT +flag was introduced in SGI IRIX, where it has alignment restrictions +similar to those of Linux 2.4. IRIX has also a fcntl(2) call to +query appropriate alignments, and sizes. FreeBSD 4.x introduced +a flag of same name, but without alignment restrictions. +Support was added under Linux in kernel version 2.4.10. +Older Linux kernels simply ignore this flag. +.SH BUGS +"The thing that has always disturbed me about O_DIRECT is that the whole +interface is just stupid, and was probably designed by a deranged monkey +on some serious mind-controlling substances." -- Linus +.SH RESTRICTIONS +There are many infelicities in the protocol underlying NFS, affecting +amongst others +.BR O_SYNC " and " O_NDELAY . + +POSIX provides for three different variants of synchronised I/O, +corresponding to the flags \fBO_SYNC\fR, \fBO_DSYNC\fR and +\fBO_RSYNC\fR. Currently (2.1.130) these are all synonymous under Linux. +.SH "SEE ALSO" +.BR close (2), +.BR fcntl (2), +.BR link (2), +.BR mknod (2), +.BR mount (2), +.BR path_resolution (2), +.BR read (2), +.BR socket (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR write (2), +.BR fopen (3), +.BR fifo (4) |