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