xref: /openbsd/lib/libc/sys/open.2 (revision e5dd7070) 
1.\"	$OpenBSD: open.2,v 1.49 2015/01/19 15:54:11 millert Exp $
2.\"	$NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $
3.\"
4.\" Copyright (c) 1980, 1991, 1993
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"     @(#)open.2	8.2 (Berkeley) 11/16/93
32.\"
33.Dd $Mdocdate: January 19 2015 $
34.Dt OPEN 2
35.Os
36.Sh NAME
37.Nm open ,
38.Nm openat
39.Nd open or create a file for reading or writing
40.Sh SYNOPSIS
41.In fcntl.h
42.Ft int
43.Fn open "const char *path" "int flags" ...
44.Ft int
45.Fn openat "int fd" "const char *path" "int flags" ...
46.Sh DESCRIPTION
47The file name specified by
48.Fa path
49is opened
50for reading and/or writing as specified by the
51argument
52.Fa flags
53and the file descriptor returned to the calling process.
54The
55.Fa flags
56argument may indicate the file is to be
57created if it does not exist (by specifying the
58.Dv O_CREAT
59flag), in which case the file is created with a mode
60specified by an additional argument of type
61.Vt mode_t
62as described in
63.Xr chmod 2
64and modified by the process' umask value (see
65.Xr umask 2 ) .
66.Pp
67The
68.Fa flags
69specified are a bitwise OR of the following values.
70Exactly one of the first three values (file access modes) must be specified:
71.Pp
72.Bl -tag -width O_DIRECTORY -offset indent -compact
73.It Dv O_RDONLY
74Open for reading only.
75.It Dv O_WRONLY
76Open for writing only.
77.It Dv O_RDWR
78Open for reading and writing.
79.El
80.Pp
81Any combination of the following flags may additionally be used:
82.Pp
83.Bl -tag -width O_DIRECTORY -offset indent -compact
84.It Dv O_NONBLOCK
85Do not block on open or for data to become available.
86.It Dv O_APPEND
87Append on each write.
88.It Dv O_CREAT
89Create file if it does not exist.
90An additional argument of type
91.Vt mode_t
92must be supplied to the call.
93.It Dv O_TRUNC
94Truncate size to 0.
95.It Dv O_EXCL
96Error if
97.Dv O_CREAT
98is set and file exists.
99.It Dv O_SYNC
100Perform synchronous I/O operations.
101.It Dv O_SHLOCK
102Atomically obtain a shared lock.
103.It Dv O_EXLOCK
104Atomically obtain an exclusive lock.
105.It Dv O_NOFOLLOW
106If last path element is a symlink, don't follow it.
107.It Dv O_CLOEXEC
108Set
109.Dv FD_CLOEXEC
110(the close-on-exec flag)
111on the new file descriptor.
112.It Dv O_DIRECTORY
113Error if
114.Fa path
115does not name a directory.
116.El
117.Pp
118Opening a file with
119.Dv O_APPEND
120set causes each write on the file
121to be appended to the end.
122If
123.Dv O_TRUNC
124and a writing mode are specified and the
125file exists, the file is truncated to zero length.
126If
127.Dv O_EXCL
128is set with
129.Dv O_CREAT
130and the file already
131exists,
132.Fn open
133returns an error.
134This may be used to implement a simple exclusive access locking mechanism.
135If either of
136.Dv O_EXCL
137or
138.Dv O_NOFOLLOW
139are set and the last component of the pathname is
140a symbolic link,
141.Fn open
142will fail even if the symbolic
143link points to a non-existent name.
144If the
145.Dv O_NONBLOCK
146flag is specified, do not wait for the device or file to be ready or
147available.
148If the
149.Fn open
150call would result
151in the process being blocked for some reason (e.g., waiting for
152carrier on a dialup line),
153.Fn open
154returns immediately.
155This flag also has the effect of making all subsequent I/O on the open file
156non-blocking.
157If the
158.Dv O_SYNC
159flag is set, all I/O operations on the file will be done synchronously.
160.Pp
161A FIFO should either be opened with
162.Dv O_RDONLY
163or with
164.Dv O_WRONLY .
165The behavior for opening a FIFO with
166.Dv O_RDWR
167is undefined.
168.Pp
169When opening a file, a lock with
170.Xr flock 2
171semantics can be obtained by setting
172.Dv O_SHLOCK
173for a shared lock, or
174.Dv O_EXLOCK
175for an exclusive lock.
176If creating a file with
177.Dv O_CREAT ,
178the request for the lock will never fail
179(provided that the underlying filesystem supports locking).
180.Pp
181If
182.Fn open
183is successful, the file pointer used to mark the current position within
184the file is set to the beginning of the file.
185.Pp
186When a new file is created it is given the group of the directory
187which contains it.
188.Pp
189The new descriptor is set to remain open across
190.Xr execve 2
191system calls; see
192.Xr close 2
193and
194.Xr fcntl 2 .
195.Pp
196The system imposes a limit on the number of file descriptors
197open simultaneously by one process.
198.Xr getdtablesize 3
199returns the current system limit.
200.Pp
201The
202.Fn openat
203function is equivalent to
204.Fn open
205except that where
206.Fa path
207specifies a relative path,
208the file to be opened is determined relative to
209the directory associated with file descriptor
210.Fa fd
211instead of the current working directory.
212.Pp
213If
214.Fn openat
215is passed the special value
216.Dv AT_FDCWD
217(defined in
218.In fcntl.h )
219in the
220.Fa fd
221parameter, the current working directory is used
222and the behavior is identical to a call to
223.Fn open .
224.Sh RETURN VALUES
225If successful,
226.Fn open
227returns a non-negative integer, termed a file descriptor.
228Otherwise, a value of \-1 is returned and
229.Va errno
230is set to indicate the error.
231.Sh ERRORS
232The
233.Fn open
234and
235.Fn openat
236functions will fail if:
237.Bl -tag -width Er
238.It Bq Er ENOTDIR
239A component of the path prefix is not a directory.
240.It Bq Er ENOTDIR
241.Dv O_DIRECTORY
242is specified and
243.Fa path
244does not name a directory.
245.It Bq Er ENAMETOOLONG
246A component of a pathname exceeded
247.Dv NAME_MAX
248characters, or an entire pathname (including the terminating NUL)
249exceeded
250.Dv PATH_MAX
251bytes.
252.It Bq Er ENOENT
253.Dv O_CREAT
254is not set and the named file does not exist.
255.It Bq Er ENOENT
256A component of the path name that must exist does not exist.
257.It Bq Er EACCES
258Search permission is denied for a component of the path prefix.
259.It Bq Er EACCES
260The required permissions (for reading and/or writing)
261are denied for the given
262.Fa flags .
263.It Bq Er EACCES
264.Dv O_CREAT
265is specified,
266the file does not exist,
267and the directory in which it is to be created
268does not permit writing.
269.It Bq Er ELOOP
270Too many symbolic links were encountered in translating the pathname,
271or the
272.Dv O_NOFOLLOW
273flag was specified and the target is a symbolic link.
274.It Bq Er EISDIR
275The named file is a directory, and the arguments specify
276it is to be opened for writing.
277.It Bq Er EINVAL
278The
279.Fa flags
280specified for opening the file are not valid.
281.It Bq Er EROFS
282The named file resides on a read-only file system,
283and the file is to be modified.
284.It Bq Er EMFILE
285The process has already reached its limit for open file descriptors.
286.It Bq Er ENFILE
287The system file table is full.
288.It Bq Er ENXIO
289The named file is a character special or block
290special file, and the device associated with this special file
291does not exist.
292.It Bq Er ENXIO
293The named file is a FIFO, the
294.Dv O_NONBLOCK
295and
296.Dv O_WRONLY
297flags are set, and no process has the file open for reading.
298.It Bq Er EINTR
299The
300.Fn open
301operation was interrupted by a signal.
302.It Bq Er EOPNOTSUPP
303.Dv O_SHLOCK
304or
305.Dv O_EXLOCK
306is specified but the underlying filesystem does not support locking.
307.It Bq Er EWOULDBLOCK
308.Dv O_NONBLOCK
309and one of
310.Dv O_SHLOCK
311or
312.Dv O_EXLOCK
313is specified and the file is already locked.
314.It Bq Er ENOSPC
315.Dv O_CREAT
316is specified,
317the file does not exist,
318and the directory in which the entry for the new file is being placed
319cannot be extended because there is no space left on the file
320system containing the directory.
321.It Bq Er ENOSPC
322.Dv O_CREAT
323is specified,
324the file does not exist,
325and there are no free inodes on the file system on which the
326file is being created.
327.It Bq Er EDQUOT
328.Dv O_CREAT
329is specified,
330the file does not exist,
331and the directory in which the entry for the new file
332is being placed cannot be extended because the
333user's quota of disk blocks on the file system
334containing the directory has been exhausted.
335.It Bq Er EDQUOT
336.Dv O_CREAT
337is specified,
338the file does not exist,
339and the user's quota of inodes on the file system on
340which the file is being created has been exhausted.
341.It Bq Er EIO
342An I/O error occurred while making the directory entry or
343allocating the inode for
344.Dv O_CREAT .
345.It Bq Er ETXTBSY
346The file is a pure procedure (shared text) file that is being
347executed and the
348.Fn open
349call requests write access.
350.It Bq Er EFAULT
351.Fa path
352points outside the process's allocated address space.
353.It Bq Er EEXIST
354.Dv O_CREAT
355and
356.Dv O_EXCL
357were specified and the file exists.
358.It Bq Er EPERM
359The file named by
360.Fa path
361is flagged append-only but
362.Dv O_APPEND
363was not specified in
364.Fa flags .
365.It Bq Er EOPNOTSUPP
366An attempt was made to open a socket (not currently implemented).
367.It Bq Er EBUSY
368An attempt was made to open a terminal device that requires exclusive
369access and the specified device has already be opened.
370.El
371.Pp
372Additionally, the
373.Fn openat
374function will fail if:
375.Bl -tag -width Er
376.It Bq Er EBADF
377The
378.Fa path
379argument specifies a relative path and the
380.Fa fd
381argument is neither
382.Dv AT_FDCWD
383nor a valid file descriptor.
384.It Bq Er ENOTDIR
385The
386.Fa path
387argument specifies a relative path and the
388.Fa fd
389argument is a valid file descriptor but it does not reference a directory.
390.It Bq Er EACCES
391The
392.Fa path
393argument specifies a relative path but search permission is denied
394for the directory which the
395.Fa fd
396file descriptor references.
397.El
398.Sh SEE ALSO
399.Xr chflags 2 ,
400.Xr chmod 2 ,
401.Xr close 2 ,
402.Xr dup 2 ,
403.Xr flock 2 ,
404.Xr lseek 2 ,
405.Xr read 2 ,
406.Xr umask 2 ,
407.Xr write 2 ,
408.Xr getdtablesize 3
409.Sh STANDARDS
410The
411.Fn open
412and
413.Fn openat
414functions conform to
415.St -p1003.1-2008 .
416.Pp
417.Dv POSIX
418specifies three different flavors for synchronous I/O:
419.Dv O_SYNC ,
420.Dv O_DSYNC ,
421and
422.Dv O_RSYNC .
423In
424.Ox ,
425these are all equivalent.
426.Pp
427The
428.Dv O_SHLOCK
429and
430.Dv O_EXLOCK
431flags are non-standard extensions and should not be used if portability
432is of concern.
433.Sh HISTORY
434An
435.Fn open
436system call first appeared in
437.At v1 .
438The
439.Fa flags
440argument has been supported since
441.Bx 4.2 .
442Before that, a dedicated
443.Fn creat
444system call had to be used to create new files;
445it appeared in
446.At v1 ,
447was deprecated in
448.Bx 4.3 Reno ,
449and removed in
450.Ox 5.0 .
451.Pp
452The
453.Fn openat
454system call has been available since
455.Ox 5.0 .
456.Sh CAVEATS
457The
458.Dv O_TRUNC
459flag requires that one of
460.Dv O_RDWR
461or
462.Dv O_WRONLY
463also be specified, else
464.Er EINVAL
465is returned.
466