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