| blob | 1e5fb444f869bc1c1090899c6829fee640e73cd8 |
1 .\" $NetBSD: open.2,v 1.47 2010/09/22 17:58:09 wiz Exp $
2 .\"
3 .\" Copyright (c) 1980, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)open.2 8.2 (Berkeley) 11/16/93
31 .\"
32 .Dd September 22, 2010
33 .Dt OPEN 2
34 .Os
35 .Sh NAME
36 .Nm open
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" "mode_t mode"
44 .Sh DESCRIPTION
45 The file name specified by
46 .Fa path
47 is opened
48 for reading and/or writing as specified by the
49 argument
50 .Fa flags
51 and the file descriptor returned to the calling process.
52 The
53 .Fa flags
54 are specified by
55 .Em or Ns 'ing
56 the values listed below.
57 Applications must specify exactly one of the first three values
58 (file access methods):
59 .Bl -tag -offset indent -width O_NONBLOCK
60 .It Dv O_RDONLY
61 Open for reading only.
62 .It Dv O_WRONLY
63 Open for writing only.
64 .It Dv O_RDWR
65 Open for reading and writing.
66 .El
67 .Pp
68 Any combination of the following may be used:
69 .Bl -tag -offset indent -width O_NONBLOCK
70 .It Dv O_NONBLOCK
71 Do not block on open or for data to become available.
72 .It Dv O_APPEND
73 Append to the file on each write.
74 .It Dv O_CREAT
75 Create the file if it does not exist, in which case the file is
76 created with mode
77 .Ar mode
78 as described in
79 .Xr chmod 2
80 and modified by the process' umask value (see
81 .Xr umask 2 ) .
82 .It Dv O_TRUNC
83 Truncate size to 0.
84 .It Dv O_EXCL
85 Error if
86 .Dv O_CREAT
87 and the file already exists.
88 .It Dv O_SHLOCK
89 Atomically obtain a shared lock.
90 .It Dv O_EXLOCK
91 Atomically obtain an exclusive lock.
92 .It Dv O_NOFOLLOW
93 If last path element is a symlink, don't follow it.
94 This option is provided for compatibility with other operating
95 systems, but its security value is questionable.
96 .It Dv O_DSYNC
97 If set, write operations will be performed according to synchronized
98 I/O data integrity completion:
99 each write will wait for the file data to be committed to stable
100 storage.
101 .It Dv O_SYNC
102 If set, write operations will be performed according to synchronized
103 I/O file integrity completion:
104 each write will wait for both the file data and file status to be
105 committed to stable storage.
106 .It Dv O_RSYNC
107 If set, read operations will complete at the same level of
108 integrity which is in effect for write operations:
109 if specified together with
110 .Dv O_SYNC ,
111 each read will wait for the file status to be committed to stable
112 storage.
113 .Pp
114 Combining
115 .Dv O_RSYNC
116 with
117 .Dv O_DSYNC
118 only, or specifying it without any other synchronized I/O integrity
119 completion flag set, has no further effect.
120 .It Dv O_ALT_IO
121 Alternate I/O semantics will be used for read and write operations
122 on the file descriptor.
123 Alternate semantics are defined by the underlying layers and will not
124 have any alternate effect in most cases.
125 .It Dv O_NOCTTY
126 If the file is a terminal device, the opened device is not
127 made the controlling terminal for the session.
128 This flag has no effect on
129 .Nx ,
130 since the system defaults to the abovementioned behaviour.
131 The flag is present only for standards conformance.
132 .It Dv O_DIRECT
133 If set on a regular file, data I/O operations will not buffer the data
134 being transferred in the kernel's cache, but rather transfer the data
135 directly between user memory and the underlying device driver if possible.
136 This flag is advisory; the request may be performed in the normal
137 buffered fashion if certain conditions are not met, e.g. if the request
138 is not sufficiently aligned or if the file is mapped.
139 .Pp
140 To meet the alignment requirements for direct I/O, the file offset,
141 the length of the I/O and the address of the buffer in memory must all
142 be multiples of
143 .Dv DEV_BSIZE
144 (512 bytes).
145 If the I/O request is made
146 using an interface that supports scatter/gather via struct iovec, each
147 element of the request must meet the above alignment constraints.
148 .It Dv O_DIRECTORY
149 Fail if the file is not a directory.
150 .El
151 .Pp
152 Opening a file with
153 .Dv O_APPEND
154 set causes each write on the file
155 to be appended to the end.
156 If
157 .Dv O_TRUNC
158 is specified and the
159 file exists, the file is truncated to zero length.
160 .Pp
161 If
162 .Dv O_EXCL
163 is set with
164 .Dv O_CREAT
165 and the file already
166 exists,
167 .Fn open
168 returns an error.
169 This may be used to implement a simple exclusive access locking mechanism.
170 If
171 .Dv O_EXCL
172 is set and the last component of the pathname is
173 a symbolic link,
174 .Fn open
175 will fail even if the symbolic
176 link points to a non-existent name.
177 .Pp
178 If the
179 .Dv O_NONBLOCK
180 flag is specified, do not wait for the device or file to be ready or
181 available.
182 If the
183 .Fn open
184 call would result
185 in the process being blocked for some reason (e.g., waiting for
186 carrier on a dialup line),
187 .Fn open
188 returns immediately.
189 This flag also has the effect of making all subsequent I/O on the open file non-blocking.
190 .Pp
191 When opening a file, a lock with
192 .Xr flock 2
193 semantics can be obtained by setting
194 .Dv O_SHLOCK
195 for a shared lock, or
196 .Dv O_EXLOCK
197 for an exclusive lock.
198 If creating a file with
199 .Dv O_CREAT ,
200 the request for the lock will never fail
201 (provided that the underlying filesystem supports locking).
202 .Pp
203 If
204 .Fn open
205 is successful, the file pointer used to mark the current position within
206 the file is set to the beginning of the file.
207 .Pp
208 When a new file is created it is given the group of the directory
209 which contains it.
210 .Pp
211 The new descriptor is set to remain open across
212 .Xr execve 2
213 system calls; see
214 .Xr close 2
215 and
216 .Xr fcntl 2 .
217 .Pp
218 The system imposes a limit on the number of file descriptors
219 open simultaneously by one process.
220 Calling
221 .Xr getdtablesize 3
222 returns the current system limit.
223 .Sh RETURN VALUES
224 If successful,
225 .Fn open
226 returns a non-negative integer, termed a file descriptor.
227 Otherwise, a value of \-1 is returned and
228 .Va errno
229 is set to indicate the error.
230 .Sh ERRORS
231 The named file is opened unless:
232 .Bl -tag -width Er
233 .It Bq Er EACCES
234 Search permission is denied for a component of the path prefix,
235 the required permissions (for reading and/or writing)
236 are denied for the given flags, or
237 .Dv O_CREAT
238 is specified,
239 the file does not exist,
240 and the directory in which it is to be created
241 does not permit writing.
242 .It Bq Er EDQUOT
243 .Dv O_CREAT
244 is specified,
245 the file does not exist,
246 and the directory in which the entry for the new file
247 is being placed cannot be extended because the
248 user's quota of disk blocks on the file system
249 containing the directory has been exhausted; or
250 .Dv O_CREAT
251 is specified,
252 the file does not exist,
253 and the user's quota of inodes on the file system on
254 which the file is being created has been exhausted.
255 .It Bq Er EEXIST
256 .Dv O_CREAT
257 and
258 .Dv O_EXCL
259 were specified and the file exists.
260 .It Bq Er EFAULT
261 .Fa path
262 points outside the process's allocated address space.
263 .It Bq Er EFTYPE
264 .Dv O_NOFOLLOW
265 was specified, but the last path component is a symlink.
266 .Em Note :
267 .St -p1003.1-2008
268 specifies returning
269 .Bq Er ELOOP
270 for this case.
271 .It Bq Er EINTR
272 The
273 .Fn open
274 operation was interrupted by a signal.
275 .It Bq Er EIO
276 An I/O error occurred while making the directory entry or
277 allocating the inode for
278 .Dv O_CREAT .
279 .It Bq Er EISDIR
280 The named file is a directory, and the arguments specify
281 it is to be opened for writing.
282 .It Bq Er ELOOP
283 Too many symbolic links were encountered in translating the pathname.
284 .It Bq Er EMFILE
285 The process has already reached its limit for open file descriptors.
286 .It Bq Er ENAMETOOLONG
287 A component of a pathname exceeded
288 .Brq Dv NAME_MAX
289 characters, or an entire path name exceeded
290 .Brq Dv PATH_MAX
291 characters.
292 .It Bq Er ENFILE
293 The system file table is full.
294 .It Bq Er ENOENT
295 .Dv O_CREAT
296 is not set and the named file does not exist, or
297 a component of the path name that must exist does not exist.
298 .It Bq Er ENOSPC
299 .Dv O_CREAT
300 is specified,
301 the file does not exist,
302 and the directory in which the entry for the new file is being placed
303 cannot be extended because there is no space left on the file
304 system containing the directory; or
305 .Dv O_CREAT
306 is specified,
307 the file does not exist,
308 and there are no free inodes on the file system on which the
309 file is being created.
310 .It Bq Er ENOTDIR
311 A component of the path prefix is not a directory; or
312 .Dv O_DIRECTORY
313 is specified and the last path component is not a directory.
314 .It Bq Er ENXIO
315 The named file is a character special or block
316 special file, and the device associated with this special file
317 does not exist, or
318 the named file is a
319 .Tn FIFO ,
320 .Dv O_NONBLOCK
321 and
322 .Dv O_WRONLY
323 is set and no process has the file open for reading.
324 .It Bq Er EOPNOTSUPP
325 .Dv O_SHLOCK
326 or
327 .Dv O_EXLOCK
328 is specified but the underlying filesystem does not support locking; or
329 an attempt was made to open a socket (not currently implemented).
330 .It Bq Er EPERM
331 The file's flags (see
332 .Xr chflags 2 )
333 don't allow the file to be opened.
334 .It Bq Er EROFS
335 The named file resides on a read-only file system,
336 and the file is to be modified.
337 .It Bq Er ETXTBSY
338 The file is a pure procedure (shared text) file that is being
339 executed and the
340 .Fn open
341 call requests write access.
342 .El
343 .Sh SEE ALSO
344 .Xr chmod 2 ,
345 .Xr close 2 ,
346 .Xr dup 2 ,
347 .Xr lseek 2 ,
348 .Xr read 2 ,
349 .Xr umask 2 ,
350 .Xr write 2 ,
351 .Xr getdtablesize 3
352 .Sh STANDARDS
353 The
354 .Fn open
355 function conforms to
356 .St -p1003.1-90 .
357 The
358 .Fa flags
359 values
360 .Dv O_DSYNC ,
361 .Dv O_SYNC
362 and
363 .Dv O_RSYNC
364 are extensions defined in
365 .St -p1003.1b-93 .
366 .Pp
367 The
368 .Dv O_SHLOCK
369 and
370 .Dv O_EXLOCK
371 flags are non-standard extensions and should not be used if portability
372 is of concern.
373 .Sh HISTORY
374 An
375 .Fn open
376 function call appeared in
377 .At v2 .