BSD 4_4 release

[unix-history] / usr / src / lib / libc / sys / open.2

diff --git a/usr/src/lib/libc/sys/open.2 b/usr/src/lib/libc/sys/open.2
index 811503a..45adf9b 100644 (file)
--- a/usr/src/lib/libc/sys/open.2
+++ b/usr/src/lib/libc/sys/open.2
@@ -1,18 +1,44 @@
-.\" Copyright (c) 1980, 1991 Regents of the University of California.
-.\" All rights reserved.
+.\" Copyright (c) 1980, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\" %sccs.include.redist.man%
+.\" 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.

 .\"
 .\"

-.\"     @(#)open.2     6.7 (Berkeley) %G%
+.\" 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.

 .\"
 .\"

-.Dd 
+.\"     @(#)open.2     8.1 (Berkeley) 6/4/93
+.\"
+.Dd June 4, 1993

 .Dt OPEN 2
 .Os BSD 4
 .Sh NAME
 .Nm open
 .Nd open or create a file for reading or writing
 .Sh SYNOPSIS
 .Dt OPEN 2
 .Os BSD 4
 .Sh NAME
 .Nm open
 .Nd open or create a file for reading or writing
 .Sh SYNOPSIS

-.Fd #include <sys/file.h>
+.Fd #include <fcntl.h>

 .Ft int
 .Fn open "const char *path" "int flags" "mode_t mode"
 .Sh DESCRIPTION
 .Ft int
 .Fn open "const char *path" "int flags" "mode_t mode"
 .Sh DESCRIPTION


@@ -43,11 +69,13 @@ the following values
 O_RDONLY       open for reading only
 O_WRONLY       open for writing only
 O_RDWR         open for reading and writing
 O_RDONLY       open for reading only
 O_WRONLY       open for writing only
 O_RDWR         open for reading and writing

-O_NDELAY       do not block on open
+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_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

 .Ed
 .Pp
 Opening a file with
 .Ed
 .Pp
 Opening a file with


@@ -74,7 +102,7 @@ a symbolic link,
 will fail even if the symbolic
 link points to a non-existent name.
 If the
 will fail even if the symbolic
 link points to a non-existent name.
 If the

-.Dv O_NDELAY
+.Dv O_NONBLOCK

 flag is specified and the
 .Fn open
 call would result
 flag is specified and the
 .Fn open
 call would result


@@ -85,13 +113,28 @@ returns immediately.
 The first time the process attempts to perform I/O on the open
 file it will block (not currently implemented).
 .Pp
 The first time the process attempts to perform I/O on the open
 file it will block (not currently implemented).
 .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 filesystem supports locking).
+.Pp

 If successful,
 .Fn open
 If successful,
 .Fn open

-returns a non-negative integer, termed a
-file descriptor.  It returns -1 on failure.
+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
 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
 system calls; see
 The new descriptor is set to remain open across
 .Xr execve
 system calls; see


@@ -108,8 +151,6 @@ The named file is opened unless:
 .Bl -tag -width Er
 .It Bq Er ENOTDIR
 A component of the path prefix is not a directory.
 .Bl -tag -width Er
 .It Bq Er ENOTDIR
 A component of the path prefix is not a directory.

-.It Bq Er EINVAL
-The pathname contains a character with the high-order bit set.

 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded 255 characters,
 or an entire path name exceeded 1023 characters.
 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded 255 characters,
 or an entire path name exceeded 1023 characters.


@@ -145,6 +186,15 @@ The system file table is full.
 The named file is a character special or block
 special file, and the device associated with this special file
 does not exist.
 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
+.Nm
+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 ENOSPC
 .Dv O_CREAT
 is specified,
 .It Bq Er ENOSPC
 .Dv O_CREAT
 is specified,


@@ -162,7 +212,7 @@ file is being created.
 .Dv O_CREAT
 is specified,
 the file does not exist,
 .Dv O_CREAT
 is specified,
 the file does not exist,

-and the directory in which the entry for the new fie
+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.
 is being placed cannot be extended because the
 user's quota of disk blocks on the file system
 containing the directory has been exhausted.