1 .\" Copyright (c) 1980, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
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
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 $
30 .\" $DragonFly: src/lib/libc/sys/open.2,v 1.3 2005/07/29 23:16:04 hsu Exp $
37 .Nd open or create a file for reading or writing
43 .Fn open "const char *path" "int flags" "..."
45 .Fn openat "int fd" "const char *path" "int flags" "..."
47 The file name specified by
50 for reading and/or writing as specified by the
53 and the lowest unused file descriptor in the process' file descriptor table
57 argument may indicate the file is to be
58 created if it does not exist (by specifying the
65 require a third argument
67 and the file is created with mode
71 and modified by the process' umask value (see
76 function is equivalent to the
78 function except in the case where the
80 specifies a relative path.
81 In this case the file to be opened is determined relative to the directory
82 associated with the file descriptor
84 instead of the current working directory.
87 parameter and the optional fourth parameter correspond exactly to
92 is passed the special value
96 parameter, the current working directory is used
97 and the behavior is identical to a call to
100 The flags specified are formed by
104 .Bd -literal -offset indent -compact
105 O_RDONLY open for reading only
106 O_WRONLY open for writing only
107 O_RDWR open for reading and writing
108 O_NONBLOCK do not block on open
109 O_APPEND append on each write
110 O_CREAT create file if it does not exist
111 O_TRUNC truncate size to 0
112 O_EXCL error if create and file exists
113 O_SHLOCK atomically obtain a shared lock
114 O_EXLOCK atomically obtain an exclusive lock
115 O_DIRECT eliminate or reduce cache effects
116 O_FSYNC synchronous writes
117 O_NOFOLLOW do not follow symlinks
118 O_DIRECTORY error if file is not a directory
119 O_CLOEXEC set FD_CLOEXEC upon open
124 set causes each write on the file
125 to be appended to the end.
129 file exists, the file is truncated to zero length.
139 implement a simple exclusive access locking mechanism.
142 is set and the last component of the pathname is
145 will fail even if the symbolic
146 link points to a non-existent name.
149 flag is specified and the
152 in the process being blocked for some reason (e.g., waiting for
153 carrier on a dialup line),
156 The first time the process attempts to perform I/O on the open
157 file it will block (not currently implemented).
161 is used in the mask, all writes will
162 immediately be written to disk,
163 the kernel will not cache written data
164 and all writes on the descriptor will not return until
165 the data to be written completes.
169 is used in the mask and the target file passed to
171 is a symbolic link then the
175 When opening a file, a lock with
177 semantics can be obtained by setting
179 for a shared lock, or
181 for an exclusive lock.
182 If creating a file with
184 the request for the lock will never fail
185 (provided that the underlying filesystem supports locking).
188 may be used to minimize or eliminate the cache effects of reading and writing.
189 The system will attempt to avoid caching the data you read or write.
190 If it cannot avoid caching the data,
191 it will minimize the impact the data has on the cache.
192 Use of this flag can drastically reduce performance if not used with care.
195 may be used to ensure the resulting file descriptor refers to a directory.
196 This flag can be used to prevent applications with elevated privileges
197 from opening files which are even unsafe to open with
199 such as device nodes.
202 may be used to atomically set the
204 flag for the newly returned file descriptor.
210 return a non-negative integer, termed a file descriptor.
211 It returns -1 on failure.
212 The file pointer used to mark the current position within the
213 file is set to the beginning of the file.
215 When a new file is created it is given the group of the directory
220 was specified, the new descriptor is set to remain open across
229 The system imposes a limit on the number of file descriptors
230 open simultaneously by one process.
232 returns the current system limit.
238 return a non-negative integer, termed a file descriptor.
239 They return -1 on failure, and set
241 to indicate the error.
243 The named file is opened unless:
246 A component of the path prefix is not a directory or the
248 argument is not an absolute path and the
252 nor a file descriptor associated with a directory or
254 is specified and the file is not a directory.
255 .It Bq Er ENAMETOOLONG
256 A component of a pathname exceeded 255 characters,
257 or an entire path name exceeded 1023 characters.
260 is not set and the named file does not exist.
262 A component of the path name that must exist does not exist.
264 Search permission is denied for a component of the path prefix.
266 The required permissions (for reading and/or writing)
267 are denied for the given flags.
271 the file does not exist,
272 and the directory in which it is to be created
273 does not permit writing.
275 Too many symbolic links were encountered in translating the pathname.
277 The named file is a directory, and the arguments specify
278 it is to be opened for writing.
280 The named file resides on a read-only file system,
281 and the file is to be modified.
283 The process has already reached its limit for open file descriptors.
285 The system file table is full.
288 was specified and the target is a symbolic link.
290 The named file is a character special or block
291 special file, and the device associated with this special file
294 The named file is a fifo, no process has
295 it open for reading, and the arguments specify it is
296 to be opened for writing.
300 operation was interrupted by a signal.
305 is specified but the underlying filesystem does not support locking.
306 .It Bq Er EWOULDBLOCK
312 is specified and the file is locked.
316 the file does not exist,
317 and the directory in which the entry for the new file is being placed
318 cannot be extended because there is no space left on the file
319 system containing the directory.
323 the file does not exist,
324 and there are no free inodes on the file system on which the
325 file is being created.
329 the file does not exist,
330 and the directory in which the entry for the new file
331 is being placed cannot be extended because the
332 user's quota of disk blocks on the file system
333 containing the directory has been exhausted.
337 the file does not exist,
338 and the user's quota of inodes on the file system on
339 which the file is being created has been exhausted.
341 An I/O error occurred while making the directory entry or
342 allocating the inode for
345 The file is a pure procedure (shared text) file that is being
348 call requests write access.
351 points outside the process's allocated address space.
356 were specified and the file exists.
358 An attempt was made to open a socket (not currently implemented).
360 An attempt was made to open a descriptor with an illegal combination
371 .Xr getdtablesize 2 ,
379 function call appeared in
383 function call appeared first in Solaris and was ported to
386 The Open Group Extended API Set 2 specification requires that the test
389 searchability is based on whether it is open for searching,
390 and not whether the underlying directory currently permits searches.
391 The present implementation of
393 checks the current permissions of directory instead.