In several standard headers, harmonize checks for legacy defines etc.
[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.
dc71b7ab 12.\" 3. Neither the name of the University nor the names of its contributors
984263bc
MD
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" @(#)open.2 8.2 (Berkeley) 11/16/93
29.\" $FreeBSD: src/lib/libc/sys/open.2,v 1.11.2.9 2001/12/14 18:34:01 ru Exp $
3a0c0554 30.\" $DragonFly: src/lib/libc/sys/open.2,v 1.3 2005/07/29 23:16:04 hsu Exp $
984263bc 31.\"
f3b0543f 32.Dd July 31, 2012
984263bc
MD
33.Dt OPEN 2
34.Os
35.Sh NAME
95c2ffe9 36.Nm open , openat
984263bc
MD
37.Nd open or create a file for reading or writing
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
41.In fcntl.h
42.Ft int
43.Fn open "const char *path" "int flags" "..."
95c2ffe9
NT
44.Ft int
45.Fn openat "int fd" "const char *path" "int flags" "..."
984263bc
MD
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
3a0c0554
JH
53and the lowest unused file descriptor in the process' file descriptor table
54is returned.
984263bc
MD
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
95c2ffe9
NT
62.Fn open
63and
64.Fn openat
65require a third argument
984263bc
MD
66.Fa "mode_t mode" ,
67and the file is created with mode
68.Fa mode
69as described in
70.Xr chmod 2
71and modified by the process' umask value (see
72.Xr umask 2 ) .
73.Pp
95c2ffe9
NT
74The
75.Fn openat
76function is equivalent to the
77.Fn open
78function except in the case where the
79.Fa path
80specifies a relative path.
81In this case the file to be opened is determined relative to the directory
82associated with the file descriptor
83.Fa fd
84instead of the current working directory.
85The
86.Fa flag
87parameter and the optional fourth parameter correspond exactly to
88the parameters of
89.Fn open .
90If
91.Fn openat
92is passed the special value
93.Dv AT_FDCWD
94in the
95.Fa fd
96parameter, the current working directory is used
97and the behavior is identical to a call to
98.Fn open .
99.Pp
984263bc
MD
100The flags specified are formed by
101.Em or Ns 'ing
102the following values
103.Pp
104.Bd -literal -offset indent -compact
105O_RDONLY open for reading only
106O_WRONLY open for writing only
107O_RDWR open for reading and writing
108O_NONBLOCK do not block on open
109O_APPEND append on each write
110O_CREAT create file if it does not exist
111O_TRUNC truncate size to 0
112O_EXCL error if create and file exists
113O_SHLOCK atomically obtain a shared lock
114O_EXLOCK atomically obtain an exclusive lock
115O_DIRECT eliminate or reduce cache effects
116O_FSYNC synchronous writes
117O_NOFOLLOW do not follow symlinks
f3b0543f 118O_DIRECTORY error if file is not a directory
6e4ea98e 119O_CLOEXEC set FD_CLOEXEC upon open
984263bc
MD
120.Ed
121.Pp
122Opening a file with
123.Dv O_APPEND
124set causes each write on the file
125to be appended to the end.
126If
127.Dv O_TRUNC
128is specified and the
129file exists, the file is truncated to zero length.
130If
131.Dv O_EXCL
132is set with
133.Dv O_CREAT
134and the file already
135exists,
136.Fn open
137returns an error.
138This may be used to
139implement a simple exclusive access locking mechanism.
140If
141.Dv O_EXCL
142is set and the last component of the pathname is
143a symbolic link,
144.Fn open
145will fail even if the symbolic
146link points to a non-existent name.
147If the
148.Dv O_NONBLOCK
149flag is specified and the
150.Fn open
151call would result
152in the process being blocked for some reason (e.g., waiting for
153carrier on a dialup line),
154.Fn open
155returns immediately.
156The first time the process attempts to perform I/O on the open
157file it will block (not currently implemented).
158.Pp
159If
160.Dv O_FSYNC
161is used in the mask, all writes will
162immediately be written to disk,
163the kernel will not cache written data
164and all writes on the descriptor will not return until
165the data to be written completes.
166.Pp
167If
168.Dv O_NOFOLLOW
169is used in the mask and the target file passed to
170.Fn open
171is a symbolic link then the
172.Fn open
173will fail.
174.Pp
175When opening a file, a lock with
176.Xr flock 2
177semantics can be obtained by setting
178.Dv O_SHLOCK
179for a shared lock, or
180.Dv O_EXLOCK
181for an exclusive lock.
182If creating a file with
183.Dv O_CREAT ,
184the request for the lock will never fail
185(provided that the underlying filesystem supports locking).
186.Pp
187.Dv O_DIRECT
188may be used to minimize or eliminate the cache effects of reading and writing.
189The system will attempt to avoid caching the data you read or write.
190If it cannot avoid caching the data,
191it will minimize the impact the data has on the cache.
192Use of this flag can drastically reduce performance if not used with care.
193.Pp
f3b0543f
AH
194.Dv O_DIRECTORY
195may be used to ensure the resulting file descriptor refers to a directory.
196This flag can be used to prevent applications with elevated privileges
197from opening files which are even unsafe to open with
198.Dv O_RDONLY ,
199such as device nodes.
200.Pp
6e4ea98e
FT
201.Dv O_CLOEXEC
202may be used to atomically set the
203.Dv FD_CLOEXEC
204flag for the newly returned file descriptor.
205.Pp
984263bc
MD
206If successful,
207.Fn open
95c2ffe9
NT
208and
209.Fn openat
210return a non-negative integer, termed a file descriptor.
984263bc
MD
211It returns -1 on failure.
212The file pointer used to mark the current position within the
213file is set to the beginning of the file.
214.Pp
215When a new file is created it is given the group of the directory
216which contains it.
217.Pp
6e4ea98e 218Unless
d0217aec
SW
219.Dv O_CLOEXEC
220was specified, the new descriptor is set to remain open across
984263bc
MD
221.Xr execve 2
222system calls; see
6e4ea98e
FT
223.Xr close 2 ,
224.Xr fcntl 2
984263bc 225and
6e4ea98e
FT
226.Dv O_CLOEXEC
227description.
984263bc
MD
228.Pp
229The system imposes a limit on the number of file descriptors
230open simultaneously by one process.
231.Xr Getdtablesize 2
232returns the current system limit.
233.Sh RETURN VALUES
234If successful,
235.Fn open
95c2ffe9
NT
236and
237.Fn openat
238return a non-negative integer, termed a file descriptor.
239They return -1 on failure, and set
984263bc
MD
240.Va errno
241to indicate the error.
242.Sh ERRORS
243The named file is opened unless:
244.Bl -tag -width Er
245.It Bq Er ENOTDIR
95c2ffe9
NT
246A component of the path prefix is not a directory or the
247.Fa path
248argument is not an absolute path and the
249.Fa fd
5212f0c1 250argument is neither
95c2ffe9 251.Dv AT_FDCWD
f3b0543f
AH
252nor a file descriptor associated with a directory or
253.Dv O_DIRECTORY
254is specified and the file is not a directory.
984263bc
MD
255.It Bq Er ENAMETOOLONG
256A component of a pathname exceeded 255 characters,
257or an entire path name exceeded 1023 characters.
258.It Bq Er ENOENT
259.Dv O_CREAT
260is not set and the named file does not exist.
261.It Bq Er ENOENT
262A component of the path name that must exist does not exist.
263.It Bq Er EACCES
264Search permission is denied for a component of the path prefix.
265.It Bq Er EACCES
266The required permissions (for reading and/or writing)
267are denied for the given flags.
268.It Bq Er EACCES
269.Dv O_CREAT
270is specified,
271the file does not exist,
272and the directory in which it is to be created
273does not permit writing.
274.It Bq Er ELOOP
275Too many symbolic links were encountered in translating the pathname.
276.It Bq Er EISDIR
277The named file is a directory, and the arguments specify
278it is to be opened for writing.
279.It Bq Er EROFS
280The named file resides on a read-only file system,
281and the file is to be modified.
282.It Bq Er EMFILE
283The process has already reached its limit for open file descriptors.
284.It Bq Er ENFILE
285The system file table is full.
286.It Bq Er EMLINK
287.Dv O_NOFOLLOW
288was specified and the target is a symbolic link.
289.It Bq Er ENXIO
290The named file is a character special or block
291special file, and the device associated with this special file
292does not exist.
293.It Bq Er ENXIO
294The named file is a fifo, no process has
295it open for reading, and the arguments specify it is
296to be opened for writing.
297.It Bq Er EINTR
298The
299.Fn open
300operation was interrupted by a signal.
301.It Bq Er EOPNOTSUPP
302.Dv O_SHLOCK
303or
304.Dv O_EXLOCK
305is specified but the underlying filesystem does not support locking.
306.It Bq Er EWOULDBLOCK
307.Dv O_NONBLOCK
308and one of
309.Dv O_SHLOCK
310or
311.Dv O_EXLOCK
312is specified and the file is locked.
313.It Bq Er ENOSPC
314.Dv O_CREAT
315is specified,
316the file does not exist,
317and the directory in which the entry for the new file is being placed
318cannot be extended because there is no space left on the file
319system containing the directory.
320.It Bq Er ENOSPC
321.Dv O_CREAT
322is specified,
323the file does not exist,
324and there are no free inodes on the file system on which the
325file is being created.
326.It Bq Er EDQUOT
327.Dv O_CREAT
328is specified,
329the file does not exist,
330and the directory in which the entry for the new file
331is being placed cannot be extended because the
332user's quota of disk blocks on the file system
333containing the directory has been exhausted.
334.It Bq Er EDQUOT
335.Dv O_CREAT
336is specified,
337the file does not exist,
338and the user's quota of inodes on the file system on
339which the file is being created has been exhausted.
340.It Bq Er EIO
341An I/O error occurred while making the directory entry or
342allocating the inode for
343.Dv O_CREAT .
344.It Bq Er ETXTBSY
345The file is a pure procedure (shared text) file that is being
346executed and the
347.Fn open
348call requests write access.
349.It Bq Er EFAULT
350.Fa Path
351points outside the process's allocated address space.
352.It Bq Er EEXIST
353.Dv O_CREAT
354and
355.Dv O_EXCL
356were specified and the file exists.
357.It Bq Er EOPNOTSUPP
358An attempt was made to open a socket (not currently implemented).
359.It Bq Er EINVAL
360An attempt was made to open a descriptor with an illegal combination
361of
362.Dv O_RDONLY ,
363.Dv O_WRONLY ,
364and
365.Dv O_RDWR .
366.El
367.Sh SEE ALSO
368.Xr chmod 2 ,
369.Xr close 2 ,
370.Xr dup 2 ,
371.Xr getdtablesize 2 ,
372.Xr lseek 2 ,
373.Xr read 2 ,
374.Xr umask 2 ,
375.Xr write 2
376.Sh HISTORY
377An
378.Fn open
379function call appeared in
380.At v6 .
95c2ffe9
NT
381An
382.Fn openat
1badc694 383function call appeared first in Solaris and was ported to
95c2ffe9
NT
384.Dx 2.3 .
385.Sh BUGS
386The Open Group Extended API Set 2 specification requires that the test
5212f0c1
SW
387for
388.Fa fd Ap s
389searchability is based on whether it is open for searching,
390and not whether the underlying directory currently permits searches.
391The present implementation of
392.Fn openat
95c2ffe9 393checks the current permissions of directory instead.