[apple/xnu.git] / bsd / man / man2 / open.2

.\"	$NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $
.\"
.\" 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
.\"
.Dd November 16, 1993
.Dt OPEN 2
.Os BSD 4
.Sh NAME
.Nm open
.Nd open or create a file for reading or writing
.Sh SYNOPSIS
.Fd #include <fcntl.h>
.Ft int
.Fn open "const char *path" "int flags" "mode_t mode"
.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 which case 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 or for data to become available
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
.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, 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),
.Fn open
returns immediately.
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
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
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
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.
.Xr Getdtablesize 2
returns the current system limit.
.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 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 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 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
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 SEE ALSO
.Xr chmod 2 ,
.Xr close 2 ,
.Xr dup 2 ,
.Xr getdtablesize 2 ,
.Xr lseek 2 ,
.Xr read 2 ,
.Xr write 2 ,
.Xr umask 2
.Sh HISTORY
An
.Fn open
function call appeared in 
.At v6 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $
	2	.\"
	3	.\" Copyright (c) 1980, 1991, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. Neither the name of the University nor the names of its contributors
	19	.\" may be used to endorse or promote products derived from this software
	20	.\" without specific prior written permission.
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	23	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	24	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	25	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	26	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	27	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	28	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	29	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	30	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	31	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)open.2 8.2 (Berkeley) 11/16/93
	35	.\"
	36	.Dd November 16, 1993
	37	.Dt OPEN 2
	38	.Os BSD 4
	39	.Sh NAME
	40	.Nm open
	41	.Nd open or create a file for reading or writing
	42	.Sh SYNOPSIS
	43	.Fd #include <fcntl.h>
	44	.Ft int
	45	.Fn open "const char *path" "int flags" "mode_t mode"
	46	.Sh DESCRIPTION
	47	The file name specified by
	48	.Fa path
	49	is opened
	50	for reading and/or writing as specified by the
	51	argument
	52	.Fa flags
	53	and the file descriptor returned to the calling process.
	54	The
	55	.Fa flags
	56	argument may indicate the file is to be
	57	created if it does not exist (by specifying the
	58	.Dv O_CREAT
	59	flag), in which case the file is created with mode
	60	.Fa mode
	61	as described in
	62	.Xr chmod 2
	63	and modified by the process' umask value (see
	64	.Xr umask 2 ) .
65	.Pp
66	The flags specified are formed by
67	.Em or Ns 'ing
68	the following values
69	.Pp
70	.Bd -literal -offset indent -compact
71	O_RDONLY open for reading only
72	O_WRONLY open for writing only
73	O_RDWR open for reading and writing
74	O_NONBLOCK do not block on open or for data to become available
75	O_APPEND append on each write
76	O_CREAT create file if it does not exist
77	O_TRUNC truncate size to 0
78	O_EXCL error if create and file exists
79	O_SHLOCK atomically obtain a shared lock
80	O_EXLOCK atomically obtain an exclusive lock
81	.Ed
82	.Pp
83	Opening a file with
84	.Dv O_APPEND
85	set causes each write on the file
86	to be appended to the end. If
87	.Dv O_TRUNC
88	is specified and the
89	file exists, the file is truncated to zero length.
90	If
91	.Dv O_EXCL
92	is set with
93	.Dv O_CREAT
94	and the file already
95	exists,
96	.Fn open
97	returns an error. This may be used to
98	implement a simple exclusive access locking mechanism.
99	If
100	.Dv O_EXCL
101	is set and the last component of the pathname is
102	a symbolic link,
103	.Fn open
104	will fail even if the symbolic
105	link points to a non-existent name.
106	If the
107	.Dv O_NONBLOCK
108	flag is specified, do not wait for the device or file to be ready or
109	available. If the
110	.Fn open
111	call would result
112	in the process being blocked for some reason (e.g., waiting for
113	carrier on a dialup line),
114	.Fn open
115	returns immediately.
116	This flag also has the effect of making all subsequent I/O on the open file non-blocking.
117	.Pp
118	When opening a file, a lock with
119	.Xr flock 2
120	semantics can be obtained by setting
121	.Dv O_SHLOCK
122	for a shared lock, or
123	.Dv O_EXLOCK
124	for an exclusive lock.
125	If creating a file with
126	.Dv O_CREAT ,
127	the request for the lock will never fail
128	(provided that the underlying filesystem supports locking).
129	.Pp
130	If successful,
131	.Fn open
132	returns a non-negative integer, termed a file descriptor.
133	It returns -1 on failure.
134	The file pointer used to mark the current position within the
135	file is set to the beginning of the file.
136	.Pp
137	When a new file is created it is given the group of the directory
138	which contains it.
139	.Pp
140	The new descriptor is set to remain open across
141	.Xr execve
142	system calls; see
143	.Xr close 2
144	and
145	.Xr fcntl 2 .
146	.Pp
147	The system imposes a limit on the number of file descriptors
148	open simultaneously by one process.
149	.Xr Getdtablesize 2
150	returns the current system limit.
151	.Sh ERRORS
152	The named file is opened unless:
153	.Bl -tag -width Er
154	.It Bq Er ENOTDIR
155	A component of the path prefix is not a directory.
156	.It Bq Er ENAMETOOLONG
157	A component of a pathname exceeded
158	.Dv {NAME_MAX}
159	characters, or an entire path name exceeded
160	.Dv {PATH_MAX}
161	characters.
162	.It Bq Er ENOENT
163	.Dv O_CREAT
164	is not set and the named file does not exist.
165	.It Bq Er ENOENT
166	A component of the path name that must exist does not exist.
167	.It Bq Er EACCES
168	Search permission is denied for a component of the path prefix.
169	.It Bq Er EACCES
170	The required permissions (for reading and/or writing)
171	are denied for the given flags.
172	.It Bq Er EACCES
173	.Dv O_CREAT
174	is specified,
175	the file does not exist,
176	and the directory in which it is to be created
177	does not permit writing.
178	.It Bq Er ELOOP
179	Too many symbolic links were encountered in translating the pathname.
180	.It Bq Er EISDIR
181	The named file is a directory, and the arguments specify
182	it is to be opened for writing.
183	.It Bq Er EROFS
184	The named file resides on a read-only file system,
185	and the file is to be modified.
186	.It Bq Er EMFILE
187	The process has already reached its limit for open file descriptors.
188	.It Bq Er ENFILE
189	The system file table is full.
190	.It Bq Er ENXIO
191	The named file is a character special or block
192	special file, and the device associated with this special file
193	does not exist.
194	.It Bq Er EINTR
195	The
196	.Fn open
197	operation was interrupted by a signal.
198	.It Bq Er EOPNOTSUPP
199	.Dv O_SHLOCK
200	or
201	.Dv O_EXLOCK
202	is specified but the underlying filesystem does not support locking.
203	.It Bq Er ENOSPC
204	.Dv O_CREAT
205	is specified,
206	the file does not exist,
207	and the directory in which the entry for the new file is being placed
208	cannot be extended because there is no space left on the file
209	system containing the directory.
210	.It Bq Er ENOSPC
211	.Dv O_CREAT
212	is specified,
213	the file does not exist,
214	and there are no free inodes on the file system on which the
215	file is being created.
216	.It Bq Er EDQUOT
217	.Dv O_CREAT
218	is specified,
219	the file does not exist,
220	and the directory in which the entry for the new file
221	is being placed cannot be extended because the
222	user's quota of disk blocks on the file system
223	containing the directory has been exhausted.
224	.It Bq Er EDQUOT
225	.Dv O_CREAT
226	is specified,
227	the file does not exist,
228	and the user's quota of inodes on the file system on
229	which the file is being created has been exhausted.
230	.It Bq Er EIO
231	An I/O error occurred while making the directory entry or
232	allocating the inode for
233	.Dv O_CREAT .
234	.It Bq Er ETXTBSY
235	The file is a pure procedure (shared text) file that is being
236	executed and the
237	.Fn open
238	call requests write access.
239	.It Bq Er EFAULT
240	.Fa Path
241	points outside the process's allocated address space.
242	.It Bq Er EEXIST
243	.Dv O_CREAT
244	and
245	.Dv O_EXCL
246	were specified and the file exists.
247	.It Bq Er EOPNOTSUPP
248	An attempt was made to open a socket (not currently implemented).
249	.El
250	.Sh SEE ALSO
251	.Xr chmod 2 ,
252	.Xr close 2 ,
253	.Xr dup 2 ,
254	.Xr getdtablesize 2 ,
255	.Xr lseek 2 ,
256	.Xr read 2 ,
257	.Xr write 2 ,
258	.Xr umask 2
259	.Sh HISTORY
260	An
261	.Fn open
262	function call appeared in
263	.At v6 .