Print this page
14249 pseudo-terminal nomenclature should reflect POSIX
Change-Id: Ib4a3cef899ff4c71b09cb0dc6878863c5e8357bc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man2/open.2
+++ new/usr/src/man/man2/open.2
1 1 .\"
2 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 3 .\" permission to reproduce portions of its copyrighted documentation.
4 4 .\" Original documentation from The Open Group can be obtained online at
5 5 .\" http://www.opengroup.org/bookstore/.
6 6 .\"
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 8 .\" Group, have given us permission to reprint portions of their
9 9 .\" documentation.
10 10 .\"
11 11 .\" In the following statement, the phrase ``this text'' refers to portions
12 12 .\" of the system documentation.
13 13 .\"
14 14 .\" Portions of this text are reprinted and reproduced in electronic form
15 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 16 .\" Standard for Information Technology -- Portable Operating System
17 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 20 .\" between these versions and the original IEEE and The Open Group
21 21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 22 .\" document. The original Standard can be obtained online at
23 23 .\" http://www.opengroup.org/unix/online.html.
24 24 .\"
25 25 .\" This notice shall appear on any product containing this material.
26 26 .\"
27 27 .\" The contents of this file are subject to the terms of the
28 28 .\" Common Development and Distribution License (the "License").
29 29 .\" You may not use this file except in compliance with the License.
30 30 .\"
31 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 32 .\" or http://www.opensolaris.org/os/licensing.
33 33 .\" See the License for the specific language governing permissions
34 34 .\" and limitations under the License.
35 35 .\"
36 36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 38 .\" If applicable, add the following below this CDDL HEADER, with the
39 39 .\" fields enclosed by brackets "[]" replaced with your own identifying
|
↓ open down ↓ |
39 lines elided |
↑ open up ↑ |
40 40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 41 .\"
42 42 .\"
43 43 .\" Copyright 1989 AT&T
44 44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 45 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
46 46 .\" Portions Copyright (c) 2013, OmniTI Computer Consulting, Inc.
47 47 .\" All Rights Reserved.
48 48 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
49 49 .\" Copyright 2020 Joyent, Inc.
50 +.\" Copyright 2022 Oxide Computer Company
50 51 .\"
51 -.TH OPEN 2 "Mar 10, 2020"
52 -.SH NAME
53 -open, openat \- open a file
54 -.SH SYNOPSIS
55 -.nf
56 -#include <sys/types.h>
57 -#include <sys/stat.h>
58 -#include <fcntl.h>
59 -
60 -\fBint\fR \fBopen\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR \fIoflag\fR, \fB/* mode_t\fR \fImode\fR */);
61 -.fi
62 -
63 -.LP
64 -.nf
65 -\fBint\fR \fBopenat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR, \fBint\fR \fIoflag\fR,
66 - \fB/* mode_t\fR \fImode\fR */);
67 -.fi
68 -
69 -.SH DESCRIPTION
70 -The \fBopen()\fR function establishes the connection between a file and a file
71 -descriptor. It creates an open file description that refers to a file and a
72 -file descriptor that refers to that open file description. The file descriptor
73 -is used by other I/O functions to refer to that file. The \fIpath\fR argument
74 -points to a pathname naming the file.
75 -.sp
76 -.LP
77 -The \fBopenat()\fR function is identical to the \fBopen()\fR function except
78 -that the \fIpath\fR argument is interpreted relative to the starting point
79 -implied by the \fIfildes\fR argument. If the \fIfildes\fR argument has the
80 -special value \fBAT_FDCWD\fR, a relative path argument will be resolved
81 -relative to the current working directory. If the \fIpath\fR argument is
82 -absolute, the \fIfildes\fR argument is ignored.
83 -.sp
84 -.LP
85 -The \fBopen()\fR function returns a file descriptor for the named file that is
86 -the lowest file descriptor not currently open for that process. The open file
87 -description is new, and therefore the file descriptor does not share it with
88 -any other process in the system. The \fBFD_CLOEXEC\fR file descriptor flag
89 -associated with the new file descriptor is cleared.
90 -.sp
91 -.LP
52 +.Dd February 5, 2022
53 +.Dt OPEN 2
54 +.Os
55 +.Sh NAME
56 +.Nm open ,
57 +.Nm openat
58 +.Nd open a file
59 +.Sh SYNOPSIS
60 +.In sys/types.h
61 +.In sys/stat.h
62 +.In fcntl.h
63 +.Ft int
64 +.Fo open
65 +.Fa "const char *path"
66 +.Fa "int oflag"
67 +.Op , Fa "mode_t mode"
68 +.Fc
69 +.Ft int
70 +.Fo openat
71 +.Fa "int fildes"
72 +.Fa "const char *path"
73 +.Fa "int oflag"
74 +.Op , Fa "mode_t mode"
75 +.Fc
76 +.Sh DESCRIPTION
77 +The
78 +.Fn open
79 +function establishes the connection between a file and a file descriptor.
80 +It creates an open file description that refers to a file and a file descriptor
81 +that refers to that open file description.
82 +The file descriptor is used by other I/O functions to refer to that file.
83 +The
84 +.Fa path
85 +argument points to a pathname naming the file.
86 +.Pp
87 +The
88 +.Fn openat
89 +function is identical to the
90 +.Fn open
91 +function except
92 +that the
93 +.Fa path
94 +argument is interpreted relative to the starting point
95 +implied by the
96 +.Fa fildes
97 +argument.
98 +If the
99 +.Fa fildes
100 +argument has the special value
101 +.Dv AT_FDCWD ,
102 +a relative path argument will be resolved relative to the current working
103 +directory.
104 +If the
105 +.Fa path
106 +argument is absolute, the
107 +.Fa fildes
108 +argument is ignored.
109 +.Pp
110 +The
111 +.Fn open
112 +function returns a file descriptor for the named file that is the lowest file
113 +descriptor not currently open for that process.
114 +The open file description is new, and therefore the file descriptor does not
115 +share it with any other process in the system.
116 +The
117 +.Dv FD_CLOEXEC
118 +file descriptor flag associated with the new file descriptor is cleared.
119 +.Pp
92 120 The file offset used to mark the current position within the file is set to the
93 121 beginning of the file.
94 -.sp
95 -.LP
122 +.Pp
96 123 The file status flags and file access modes of the open file description are
97 -set according to the value of \fIoflag\fR. The \fImode\fR argument is used only
98 -when \fBO_CREAT\fR is specified (see below.)
99 -.sp
100 -.LP
101 -Values for \fIoflag\fR are constructed by a bitwise-inclusive-OR of flags from
102 -the following list, defined in <\fBfcntl.h\fR>. Applications must specify
103 -exactly one of the first three values (file access modes) below in the value of
104 -\fIoflag\fR:
105 -.sp
106 -.ne 2
107 -.na
108 -\fB\fBO_RDONLY\fR\fR
109 -.ad
110 -.RS 12n
124 +set according to the value of
125 +.Fa oflag .
126 +The
127 +.Fa mode
128 +argument is used only
129 +when
130 +.Dv O_CREAT
131 +is specified
132 +.Pq "see below" .
133 +.Pp
134 +Values for
135 +.Fa oflag
136 +are constructed by a bitwise-inclusive-OR of flags from
137 +the following list, defined in
138 +.Xr fcntl.h 3HEAD .
139 +Applications must specify exactly one of the first three values (file access
140 +modes) below in the value of
141 +.Fa oflag :
142 +.Bl -tag -width Ds
143 +.It Dv O_RDONLY
111 144 Open for reading only.
112 -.RE
113 -
114 -.sp
115 -.ne 2
116 -.na
117 -\fB\fBO_WRONLY\fR\fR
118 -.ad
119 -.RS 12n
145 +.It Dv O_WRONLY
120 146 Open for writing only.
121 -.RE
122 -
123 -.sp
124 -.ne 2
125 -.na
126 -\fB\fBO_RDWR\fR\fR
127 -.ad
128 -.RS 12n
129 -Open for reading and writing. The result is undefined if this flag is applied
130 -to a FIFO.
131 -.RE
132 -
133 -.sp
134 -.LP
147 +.It Dv O_RDWR
148 +Open for reading and writing.
149 +The result is undefined if this flag is applied to a FIFO.
150 +.El
151 +.Pp
135 152 Any combination of the following may be used:
136 -.sp
137 -.ne 2
138 -.na
139 -\fB\fBO_APPEND\fR\fR
140 -.ad
141 -.sp .6
142 -.RS 4n
153 +.Bl -tag -width Ds
154 +.It Dv O_APPEND
143 155 If set, the file offset is set to the end of the file prior to each write.
144 -.RE
145 -
146 -.sp
147 -.ne 2
148 -.na
149 -\fB\fBO_CREAT\fR\fR
150 -.ad
151 -.sp .6
152 -.RS 4n
153 -Create the file if it does not exist. This flag requires that the \fImode\fR
156 +.It Dv O_CREAT
157 +Create the file if it does not exist.
158 +This flag requires that the
159 +.Fa mode
154 160 argument be specified.
155 -.sp
156 -If the file exists, this flag has no effect except as noted under \fBO_EXCL\fR
157 -below. Otherwise, the file is created with the user \fBID\fR of the file set
158 -to the effective user \fBID\fR of the process. The group \fBID\fR of the file
159 -is set to the effective group \fBIDs\fR of the process, or if the \fBS_ISGID\fR
161 +.Pp
162 +If the file exists, this flag has no effect except as noted under
163 +.Dv O_EXCL
164 +below.
165 +Otherwise, the file is created with the user ID of the file set to the
166 +effective user ID of the process.
167 +The group ID of the file is set to the effective group IDs of the process, or
168 +if the
169 +.Dv S_ISGID
160 170 bit is set in the directory in which the file is being created, the file's
161 -group \fBID\fR is set to the group \fBID\fR of its parent directory. If the
162 -group \fBID\fR of the new file does not match the effective group \fBID\fR or
163 -one of the supplementary groups IDs, the \fBS_ISGID\fR bit is cleared. The
164 -access permission bits (see \fB<sys/stat.h>\fR) of the file mode are set to the
165 -value of \fImode\fR, modified as follows (see \fBcreat\fR(2)): a bitwise-AND is
166 -performed on the file-mode bits and the corresponding bits in the complement of
167 -the process's file mode creation mask. Thus, all bits set in the process's file
168 -mode creation mask (see \fBumask\fR(2)) are correspondingly cleared in the
169 -file's permission mask. The "save text image after execution bit" of the mode
170 -is cleared (see \fBchmod\fR(2)). When bits other than the file permission bits
171 -are set, the effect is unspecified. The \fImode\fR argument does not affect
172 -whether the file is open for reading, writing or for both.
173 -.RE
174 -
175 -.sp
176 -.ne 2
177 -.na
178 -.B O_DIRECT
179 -.ad
180 -.sp .6
181 -.RS 4n
171 +group ID is set to the group ID of its parent directory.
172 +If the group ID of the new file does not match the effective group
173 +ID or one of the supplementary groups IDs, the
174 +.Dv S_ISGID bit is cleared.
175 +.Pp
176 +The access permission bits
177 +.Po
178 +see
179 +.Xr stat.h 3HEAD
180 +.Pc
181 +of the file mode are set to the value of
182 +.Fa mode ,
183 +modified as follows
184 +.Po
185 +see
186 +.Xr creat 2
187 +.Pc :
188 +a bitwise-AND is performed on the file-mode bits and the corresponding bits in
189 +the complement of the process's file mode creation mask.
190 +Thus, all bits set in the process's file mode creation mask
191 +.Po
192 +see
193 +.Xr umask 2
194 +.Pc
195 +are correspondingly cleared in the file's permission mask.
196 +The
197 +.Dq save text image after execution bit
198 +of the mode is cleared
199 +.Po
200 +see
201 +.Xr chmod 2
202 +.Pc .
203 +When bits other than the file permission bits are set, the effect is
204 +unspecified.
205 +The
206 +.Fa mode
207 +argument does not affect whether the file is open for reading, writing or for
208 +both.
209 +.It Dv O_DIRECT
182 210 Indicates that the file data is not going to be reused in the near future.
183 211 When possible, data is read or written directly between the application's
184 -memory and the device when the data is accessed with \fBread\fR(2) and
185 -\fBwrite\fR(2) operations. See \fBdirectio\fR(3C) for more details.
186 -.RE
187 -
188 -.sp
189 -.ne 2
190 -.na
191 -.B O_DIRECTORY
192 -.ad
193 -.sp .6
194 -.RS 4n
212 +memory and the device when the data is accessed with
213 +.Xr read 2
214 +and
215 +.Xr write 2
216 +operations.
217 +See
218 +.Xr directio 3C
219 +for more details.
220 +.It Dv O_DIRECTORY
195 221 Indicates that attempts to open
196 -.I path
222 +.Fa path
197 223 should fail unless
198 -.I path
224 +.Fa path
199 225 is a directory.
200 226 If both
201 -.B O_CREAT
227 +.Dv O_CREAT
202 228 and
203 -.B O_DIRECTORY
229 +.Dv O_DIRECTORY
204 230 are specified then the call will fail if it would result in a file being
205 231 created.
206 232 If a directory already exists at
207 -.I path
233 +.Fa path
208 234 then it will behave as if the
209 -.B O_DIRECTORY
235 +.Dv O_DIRECTORY
210 236 flag had not been present.
211 237 If the
212 -.B O_EXCL
238 +.Dv O_EXCL
213 239 and
214 -.B O_CREAT
215 -flags are specified, then the call will always fail as they imply a file
216 -should always be created.
217 -.RE
218 -
219 -.sp
220 -.ne 2
221 -.na
222 -\fB\fBO_DSYNC\fR\fR
223 -.ad
224 -.sp .6
225 -.RS 4n
240 +.Dv O_CREAT
241 +flags are specified, then the call will always fail as they imply a file should
242 +always be created.
243 +.It Dv O_DSYNC
226 244 Write I/O operations on the file descriptor complete as defined by synchronized
227 245 I/O data integrity completion.
228 -.RE
229 -
230 -.sp
231 -.ne 2
232 -.na
233 -\fB\fBO_EXCL\fR\fR
234 -.ad
235 -.sp .6
236 -.RS 4n
237 -If \fBO_CREAT\fR and \fBO_EXCL\fR are set, \fBopen()\fR fails if the file
238 -exists. The check for the existence of the file and the creation of the file if
246 +.It Dv O_EXCL
247 +If
248 +.Dv O_CREAT
249 +and
250 +.Dv O_EXCL
251 +are set,
252 +.Fn open
253 +fails if the file exists.
254 +The check for the existence of the file and the creation of the file if
239 255 it does not exist is atomic with respect to other threads executing
240 -\fBopen()\fR naming the same filename in the same directory with \fBO_EXCL\fR
241 -and \fBO_CREAT\fR set. If \fBO_EXCL\fR and \fBO_CREAT\fR are set, and path
242 -names a symbolic link, \fBopen()\fR fails and sets \fBerrno\fR to \fBEEXIST\fR,
243 -regardless of the contents of the symbolic link. If \fBO_EXCL\fR is set and
244 -\fBO_CREAT\fR is not set, the result is undefined.
245 -.RE
246 -
247 -.sp
248 -.ne 2
249 -.na
250 -.B O_EXEC
251 -.na
252 -.ad
253 -.sp .6
254 -.RS 4n
256 +.Fn open
257 +naming the same filename in the same directory with
258 +.Dv O_EXCL
259 +and
260 +.Dv O_CREAT
261 +set.
262 +If
263 +.Dv O_EXCL
264 +and
265 +.Dv O_CREAT
266 +are set, and
267 +.Fa path
268 +names a symbolic link,
269 +.Fn open
270 +fails and sets
271 +.Va errno
272 +to
273 +.Er EEXIST ,
274 +regardless of the contents of the symbolic link.
275 +If
276 +.Dv O_EXCL
277 +is set and
278 +.Dv O_CREAT
279 +is not set, the result is undefined.
280 +.It Dv O_EXEC
255 281 If set, indicates that the file should be opened for execute permission.
256 -This option is only valid for regular files, an error will be returned
257 -if it is not.
258 -.RE
259 -
260 -.sp
261 -.ne 2
262 -.na
263 -\fB\fBO_LARGEFILE\fR\fR
264 -.ad
265 -.sp .6
266 -.RS 4n
282 +This option is only valid for regular files; an error will be returned if the
283 +target is not a regular file.
284 +.It Dv O_LARGEFILE
267 285 If set, the offset maximum in the open file description is the largest value
268 -that can be represented correctly in an object of type \fBoff64_t\fR.
269 -.RE
270 -
271 -.sp
272 -.ne 2
273 -.na
274 -\fB\fBO_NOCTTY\fR\fR
275 -.ad
276 -.sp .6
277 -.RS 4n
278 -If set and \fIpath\fR identifies a terminal device, \fBopen()\fR does not cause
279 -the terminal device to become the controlling terminal for the process.
280 -.RE
281 -
282 -.sp
283 -.ne 2
284 -.na
285 -\fB\fBO_NOFOLLOW\fR\fR
286 -.ad
287 -.sp .6
288 -.RS 4n
289 -If the path names a symbolic link, \fBopen()\fR fails and sets \fBerrno\fR to
290 -\fBELOOP\fR.
291 -.RE
292 -
293 -.sp
294 -.ne 2
295 -.na
296 -\fB\fBO_NOLINKS\fR\fR
297 -.ad
298 -.sp .6
299 -.RS 4n
300 -If the link count of the named file is greater than 1, \fBopen()\fR fails and
301 -sets \fBerrno\fR to \fBEMLINK\fR.
302 -.RE
303 -
304 -.sp
305 -.ne 2
306 -.na
307 -\fB\fBO_CLOEXEC\fR\fR
308 -.ad
309 -.sp .6
310 -.RS 4n
286 +that can be represented correctly in an object of type
287 +.Vt off64_t .
288 +.It Dv O_NOCTTY
289 +If set and
290 +.Fa path
291 +identifies a terminal device,
292 +.Fn open
293 +does not cause the terminal device to become the controlling terminal for the
294 +process.
295 +.It Dv O_NOFOLLOW
296 +If the path names a symbolic link,
297 +.Fn open
298 +fails and sets
299 +.Va errno
300 +to
301 +.Er ELOOP .
302 +.It Dv O_NOLINKS
303 +If the link count of the named file is greater than
304 +.Sy 1 ,
305 +.Fn open
306 +fails and sets
307 +.Va errno
308 +to
309 +.Er EMLINK .
310 +.It Dv O_CLOEXEC
311 311 If set, the file descriptor returned will be closed prior to any future
312 -\fBexec()\fR calls.
313 -.RE
314 -
315 -.sp
316 -.ne 2
317 -.na
318 -\fB\fBO_NONBLOCK\fR or \fBO_NDELAY\fR\fR
319 -.ad
320 -.sp .6
321 -.RS 4n
322 -These flags can affect subsequent reads and writes (see \fBread\fR(2) and
323 -\fBwrite\fR(2)). If both \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are set,
324 -\fBO_NONBLOCK\fR takes precedence.
325 -.sp
326 -When opening a \fBFIFO\fR with \fBO_RDONLY\fR or \fBO_WRONLY\fR set:
327 -.RS +4
328 -.TP
329 -.ie t \(bu
330 -.el o
331 -If \fBO_NONBLOCK\fR or \fBO_NDELAY\fR is set, an \fBopen()\fR for reading only
332 -returns without delay. An \fBopen()\fR for writing only returns an error if no
333 -process currently has the file open for reading.
334 -.RE
335 -.RS +4
336 -.TP
337 -.ie t \(bu
338 -.el o
339 -If \fBO_NONBLOCK\fR and \fBO_NDELAY\fR are clear, an \fBopen()\fR for reading
340 -only blocks until a thread opens the file for writing. An \fBopen()\fR for
341 -writing only blocks the calling thread until a thread opens the file for
312 +.Xr exec 2
313 +calls.
314 +.It Dv O_NONBLOCK O_NDELAY
315 +These flags can affect subsequent reads and writes
316 +.Po
317 +see
318 +.Xr read 2
319 +and
320 +.Xr write 2
321 +.Pc .
322 +If both
323 +.Dv O_NDELAY
324 +and
325 +.Dv O_NONBLOCK
326 +are set,
327 +.Dv O_NONBLOCK
328 +takes precedence.
329 +.Pp
330 +When opening a FIFO with
331 +.Dv O_RDONLY
332 +or
333 +.Dv O_WRONLY
334 +set:
335 +.Bl -bullet
336 +.It
337 +If
338 +.Dv O_NONBLOCK
339 +or
340 +.Dv O_NDELAY
341 +is set, an
342 +.Fn open
343 +for reading only returns without delay.
344 +An
345 +.Fn open
346 +for writing only returns an error if no process currently has the file open for
342 347 reading.
343 -.RE
344 -After both ends of a \fBFIFO\fR have been opened, there is no guarantee that
345 -further calls to \fBopen()\fR \fBO_RDONLY\fR (\fBO_WRONLY\fR) will synchronize
346 -with later calls to \fBopen()\fR \fBO_WRONLY\fR (\fBO_RDONLY\fR) until both
347 -ends of the \fBFIFO\fR have been closed by all readers and writers. Any data
348 -written into a \fBFIFO\fR will be lost if both ends of the \fBFIFO\fR are
349 -closed before the data is read.
350 -.sp
348 +.It
349 +If
350 +.Dv O_NONBLOCK
351 +and
352 +.Dv O_NDELAY
353 +are clear, an
354 +.Fn open
355 +for reading only blocks until a thread opens the file for writing.
356 +An
357 +.Fn open
358 +for writing only blocks the calling thread until a thread opens the file for
359 +reading.
360 +.El
361 +.Pp
362 +After both ends of a FIFO have been opened once, there is no guarantee that
363 +further calls to
364 +.Fn open
365 +.Dv O_RDONLY
366 +.Pq Dv O_WRONLY
367 +will synchronize with later calls to
368 +.Fn open
369 +.Dv O_WRONLY
370 +.Pq Dv O_RDONLY
371 +until both ends of the FIFO have been closed by all readers and writers.
372 +Any data written into a FIFO will be lost if both ends of the FIFO are closed
373 +before the data is read.
374 +.Pp
351 375 When opening a block special or character special file that supports
352 376 non-blocking opens:
353 -.RS +4
354 -.TP
355 -.ie t \(bu
356 -.el o
357 -If \fBO_NONBLOCK\fR or \fBO_NDELAY\fR is set, the \fBopen()\fR function returns
358 -without blocking for the device to be ready or available. Subsequent behavior
359 -of the device is device-specific.
360 -.RE
361 -.RS +4
362 -.TP
363 -.ie t \(bu
364 -.el o
365 -If \fBO_NONBLOCK\fR and \fBO_NDELAY\fR are clear, the \fBopen()\fR function
366 -blocks the calling thread until the device is ready or available before
367 -returning.
368 -.RE
369 -Otherwise, the behavior of \fBO_NONBLOCK\fR and \fBO_NDELAY\fR is unspecified.
370 -.RE
371 -
372 -.sp
373 -.ne 2
374 -.na
375 -\fB\fBO_RSYNC\fR\fR
376 -.ad
377 -.sp .6
378 -.RS 4n
377 +.Bl -bullet
378 +.It
379 +If
380 +.Dv O_NONBLOCK
381 +or
382 +.Dv O_NDELAY
383 +is set, the
384 +.Fn open
385 +function returns without blocking for the device to be ready or available.
386 +Subsequent behavior of the device is device-specific.
387 +.It
388 +If
389 +.Dv O_NONBLOCK
390 +and
391 +.Dv O_NDELAY
392 +are clear, the
393 +.Fn open
394 +function blocks the calling thread until the device is ready or available
395 +before returning.
396 +.El
397 +.Pp
398 +Otherwise, the behavior of
399 +.Dv O_NONBLOCK
400 +and
401 +.Dv O_NDELAY
402 +is unspecified.
403 +.It Dv O_RSYNC
379 404 Read I/O operations on the file descriptor complete at the same level of
380 -integrity as specified by the \fBO_DSYNC\fR and \fBO_SYNC\fR flags. If both
381 -\fBO_DSYNC\fR and \fBO_RSYNC\fR are set in \fIoflag\fR, all I/O operations on
382 -the file descriptor complete as defined by synchronized I/O data integrity
383 -completion. If both \fBO_SYNC\fR and \fBO_RSYNC\fR are set in \fIoflag\fR, all
384 -I/O operations on the file descriptor complete as defined by synchronized I/O
385 -file integrity completion.
386 -.RE
387 -
388 -.sp
389 -.ne 2
390 -.na
391 -.B O_SEARCH
392 -.ad
393 -.sp .6
394 -.RS 4n
405 +integrity as specified by the
406 +.Dv O_DSYNC
407 +and
408 +.Dv O_SYNC
409 +flags.
410 +If both
411 +.Dv O_DSYNC
412 +and
413 +.Dv O_RSYNC
414 +are set in
415 +.Fa oflag ,
416 +all I/O operations on the file descriptor complete as defined by synchronized
417 +I/O data integrity completion.
418 +If both
419 +.Dv O_SYNC
420 +and
421 +.Dv O_RSYNC
422 +are set in
423 +.Fa oflag ,
424 +all I/O operations on the file descriptor complete as defined by synchronized
425 +I/O file integrity completion.
426 +.It Dv O_SEARCH
395 427 If set, indicates that the directory should be opened for searching.
396 -This option is only valid for a directory, an error will be returned if
397 -it is not.
398 -.RE
399 -
400 -.sp
401 -.ne 2
402 -.na
403 -\fB\fBO_SYNC\fR\fR
404 -.ad
405 -.sp .6
406 -.RS 4n
428 +This option is only valid for a directory; an error will be returned if the
429 +target is not a directory.
430 +.It Dv O_SYNC
407 431 Write I/O operations on the file descriptor complete as defined by synchronized
408 -I/O file integrity completion (see \fBfcntl.h\fR(3HEAD) definition of
409 -\fBO_SYNC\fR).
410 -.RE
411 -
412 -.sp
413 -.ne 2
414 -.na
415 -\fB\fBO_TRUNC\fR\fR
416 -.ad
417 -.sp .6
418 -.RS 4n
432 +I/O file integrity completion
433 +.Po
434 +see
435 +.Xr fcntl.h 3HEAD
436 +.Pc
437 +definition of
438 +.Dv O_SYNC .
439 +.It Dv O_TRUNC
419 440 If the file exists and is a regular file, and the file is successfully opened
420 -\fBO_RDWR\fR or \fBO_WRONLY\fR, its length is truncated to 0 and the mode and
421 -owner are unchanged. It has no effect on \fBFIFO\fR special files or terminal
422 -device files. Its effect on other file types is implementation-dependent. The
423 -result of using \fBO_TRUNC\fR with \fBO_RDONLY\fR is undefined.
424 -.RE
425 -
426 -.sp
427 -.ne 2
428 -.na
429 -\fB\fBO_XATTR\fR\fR
430 -.ad
431 -.sp .6
432 -.RS 4n
433 -If set in \fBopenat()\fR, a relative path argument is interpreted as a
434 -reference to an extended attribute of the file associated with the supplied
435 -file descriptor. This flag therefore requires the presence of a legal
436 -\fIfildes\fR argument. If set in \fBopen()\fR, the implied file descriptor is
437 -that for the current working directory. Extended attributes must be referenced
438 -with a relative path; providing an absolute path results in a normal file
439 -reference.
440 -.RE
441 -
442 -.sp
443 -.LP
444 -If \fBO_CREAT\fR is set and the file did not previously exist, upon successful
445 -completion, \fBopen()\fR marks for update the \fBst_atime\fR, \fBst_ctime\fR,
446 -and \fBst_mtime\fR fields of the file and the \fBst_ctime\fR and \fBst_mtime\fR
441 +.Dv O_RDWR
442 +or
443 +.Dv O_WRONLY ,
444 +its length is truncated to
445 +.Sy 0
446 +and the mode and owner are unchanged.
447 +It has no effect on FIFO special files or terminal device files.
448 +Its effect on other file types is implementation-dependent.
449 +The result of using
450 +.Dv O_TRUNC
451 +with
452 +.Dv O_RDONLY
453 +is undefined.
454 +.It Dv O_XATTR
455 +If set in
456 +.Fn openat ,
457 +a relative path argument is interpreted as a reference to an extended attribute
458 +of the file associated with the supplied file descriptor.
459 +This flag therefore requires the presence of a legal
460 +.Fa fildes
461 +argument.
462 +If set in
463 +.Fn open ,
464 +the implied file descriptor is that for the current working directory.
465 +Extended attributes must be referenced with a relative path; providing an
466 +absolute path results in a normal file reference.
467 +.El
468 +.Pp
469 +If
470 +.Dv O_CREAT
471 +is set and the file did not previously exist, upon successful completion,
472 +.Fn open
473 +marks for update the
474 +.Fa st_atime ,
475 +.Fa st_ctime ,
476 +and
477 +.Fa st_mtime
478 +fields of the file and the
479 +.Fa st_ctime
480 +and
481 +.Fa st_mtime
447 482 fields of the parent directory.
448 -.sp
449 -.LP
450 -If \fBO_TRUNC\fR is set and the file did previously exist, upon successful
451 -completion, \fBopen()\fR marks for update the \fBst_ctime\fR and \fBst_mtime\fR
483 +.Pp
484 +If
485 +.Dv O_TRUNC
486 +is set and the file did previously exist, upon successful completion,
487 +.Fn open
488 +marks for update the
489 +.Fa st_ctime
490 +and
491 +.Fa st_mtime
452 492 fields of the file.
453 -.sp
454 -.LP
455 -If both the \fBO_SYNC\fR and \fBO_DSYNC\fR flags are set, the effect is as if
456 -only the \fBO_SYNC\fR flag was set.
457 -.sp
458 -.LP
459 -If \fIpath\fR refers to a \fBSTREAMS\fR file, \fIoflag\fR may be constructed
460 -from \fBO_NONBLOCK\fR or \fBO_NODELAY\fR OR-ed with either \fBO_RDONLY\fR,
461 -\fBO_WRONLY\fR, or \fBO_RDWR\fR. Other flag values are not applicable to
462 -\fBSTREAMS\fR devices and have no effect on them. The values \fBO_NONBLOCK\fR
463 -and \fBO_NODELAY\fR affect the operation of \fBSTREAMS\fR drivers and certain
464 -functions (see \fBread\fR(2), \fBgetmsg\fR(2), \fBputmsg\fR(2), and
465 -\fBwrite\fR(2)) applied to file descriptors associated with \fBSTREAMS\fR
466 -files. For \fBSTREAMS\fR drivers, the implementation of \fBO_NONBLOCK\fR and
467 -\fBO_NODELAY\fR is device-specific.
468 -.sp
469 -.LP
470 -When \fBopen()\fR is invoked to open a named stream, and the \fBconnld\fR
471 -module (see \fBconnld\fR(7M)) has been pushed on the pipe, \fBopen()\fR blocks
472 -until the server process has issued an \fBI_RECVFD\fR \fBioctl()\fR (see
473 -\fBstreamio\fR(7I)) to receive the file descriptor.
474 -.sp
475 -.LP
476 -If \fIpath\fR names the master side of a pseudo-terminal device, then it is
477 -unspecified whether \fBopen()\fR locks the slave side so that it cannot be
478 -opened. Portable applications must call \fBunlockpt\fR(3C) before opening the
479 -slave side.
480 -.sp
481 -.LP
493 +.Pp
494 +If both the
495 +.Dv O_SYNC
496 +and
497 +.Dv O_DSYNC
498 +flags are set, the effect is as if only the
499 +.Dv O_SYNC
500 +flag was set.
501 +.Pp
502 +If
503 +.Fa path
504 +refers to a STREAMS file,
505 +.Fa oflag
506 +may be constructed from
507 +.Dv O_NONBLOCK
508 +or
509 +.Dv O_NODELAY
510 +OR-ed with either
511 +.Dv O_RDONLY ,
512 +.Dv O_WRONLY ,
513 +or
514 +.Dv O_RDWR .
515 +Other flag values are not applicable to STREAMS devices and have no effect on
516 +them.
517 +The values
518 +.Dv O_NONBLOCK
519 +and
520 +.Dv O_NODELAY
521 +affect the operation of STREAMS drivers and certain functions
522 +.Po
523 +see
524 +.Xr read 2 ,
525 +.Xr getmsg 2 ,
526 +.Xr putmsg 2 ,
527 +and
528 +.Xr write 2
529 +.Pc
530 +applied to file descriptors associated with STREAMS files.
531 +For STREAMS drivers, the implementation of
532 +.Dv O_NONBLOCK
533 +and
534 +.Dv O_NODELAY
535 +is device-specific.
536 +.Pp
537 +When
538 +.Fn open
539 +is invoked to open a named stream, and the
540 +.Xr connld 7M
541 +module has been pushed on the pipe,
542 +.Fn open
543 +blocks until the server process has issued an
544 +.Dv I_RECVFD
545 +.Xr ioctl 2
546 +.Po
547 +see
548 +.Xr streamio 7I
549 +.Pc
550 +to receive the file descriptor.
551 +.Pp
552 +If
553 +.Fa path
554 +names the manager side of a pseudo-terminal device, then it is unspecified
555 +whether
556 +.Fn open
557 +locks the subsidiary side so that it cannot be opened.
558 +Portable applications must call
559 +.Xr unlockpt 3C
560 +before opening the subsidiary side.
561 +.Pp
482 562 If the file is a regular file and the local file system is mounted with the
483 -\fBnbmand\fR mount option, then a mandatory share reservation is automatically
484 -obtained on the file. The share reservation is obtained as if \fBfcntl\fR(2)
485 -were called with \fIcmd\fR \fBF_SHARE_NBMAND\fR and the \fBfshare_t\fR values
486 -set as follows:
487 -.sp
488 -.ne 2
489 -.na
490 -\fB\fBf_access\fR\fR
491 -.ad
492 -.RS 12n
563 +.Cm nbmand
564 +mount option, then a mandatory share reservation is automatically obtained on
565 +the file.
566 +The share reservation is obtained as if
567 +.Xr fcntl 2
568 +were called with
569 +.Fa cmd
570 +.Dv F_SHARE_NBMAND
571 +and the
572 +.Vt fshare_t
573 +values set as follows:
574 +.Bl -tag -width Ds -offset Ds
575 +.It Fa f_access
493 576 Set to the type of read/write access for which the file is opened.
494 -.RE
495 -
496 -.sp
497 -.ne 2
498 -.na
499 -\fB\fBf_deny\fR\fR
500 -.ad
501 -.RS 12n
502 -\fBF_NODNY\fR
503 -.RE
504 -
505 -.sp
506 -.ne 2
507 -.na
508 -\fB\fBf_id\fR\fR
509 -.ad
510 -.RS 12n
511 -The file descriptor value returned from \fBopen()\fR.
512 -.RE
513 -
514 -.sp
515 -.LP
516 -If \fIpath\fR is a symbolic link and \fBO_CREAT\fR and \fBO_EXCL\fR are set,
517 -the link is not followed.
518 -.sp
519 -.LP
520 -Certain flag values can be set following \fBopen()\fR as described in
521 -\fBfcntl\fR(2).
522 -.sp
523 -.LP
577 +.It Fa f_deny
578 +.Dv F_NODNY
579 +.It Fa f_id
580 +The file descriptor value returned from
581 +.Fn open .
582 +.El
583 +.Pp
584 +If
585 +.Fa path
586 +is a symbolic link and
587 +.Dv O_CREAT
588 +and
589 +.Dv O_EXCL
590 +are set, the link is not followed.
591 +.Pp
592 +Certain flag values can be set following
593 +.Fn open
594 +as described in
595 +.Xr fcntl 2 .
596 +.Pp
524 597 The largest value that can be represented correctly in an object of type
525 -\fBoff_t\fR is established as the offset maximum in the open file description.
526 -.SH RETURN VALUES
527 -Upon successful completion, both \fBopen()\fR and \fBopenat()\fR functions open
528 -the file and return a non-negative integer representing the lowest numbered
529 -unused file descriptor. Otherwise, \fB\(mi1\fR is returned, \fBerrno\fR is set
530 -to indicate the error, and no files are created or modified.
531 -.SH ERRORS
532 -The \fBopen()\fR and \fBopenat()\fR functions will fail if:
533 -.sp
534 -.ne 2
535 -.na
536 -\fB\fBEACCES\fR\fR
537 -.ad
538 -.RS 16n
539 -Search permission is denied on a component of the path prefix.
540 -.sp
541 -The file exists and the permissions specified by \fIoflag\fR are denied.
542 -.sp
543 -The file does not exist and write permission is denied for the parent directory
544 -of the file to be created.
545 -.sp
546 -\fBO_TRUNC\fR is specified and write permission is denied.
547 -.sp
548 -The {\fBPRIV_FILE_DAC_SEARCH\fR} privilege allows processes to search
549 -directories regardless of permission bits. The {\fBPRIV_FILE_DAC_WRITE\fR}
550 -privilege allows processes to open files for writing regardless of permission
551 -bits. See \fBprivileges\fR(5) for special considerations when opening files
552 -owned by UID 0 for writing. The {\fBPRIV_FILE_DAC_READ\fR} privilege allows
553 -processes to open files for reading regardless of permission bits.
554 -.RE
555 -
556 -.sp
557 -.ne 2
558 -.na
559 -\fB\fBEAGAIN\fR\fR
560 -.ad
561 -.RS 16n
562 -A mandatory share reservation could not be obtained because the desired access
563 -conflicts with an existing \fBf_deny\fR share reservation.
564 -.RE
565 -
566 -.sp
567 -.ne 2
568 -.na
569 -\fB\fBEDQUOT\fR\fR
570 -.ad
571 -.RS 16n
572 -The file does not exist, \fBO_CREAT\fR is specified, and either the directory
573 -where the new file entry is being placed cannot be extended because the user's
574 -quota of disk blocks on that file system has been exhausted, or the user's
575 -quota of inodes on the file system where the file is being created has been
576 -exhausted.
577 -.RE
578 -
579 -.sp
580 -.ne 2
581 -.na
582 -\fB\fBEEXIST\fR\fR
583 -.ad
584 -.RS 16n
585 -The \fBO_CREAT\fR and \fBO_EXCL\fR flags are set and the named file exists.
586 -.RE
587 -
588 -.sp
589 -.ne 2
590 -.na
591 -\fB\fBEILSEQ\fR\fR
592 -.ad
593 -.RS 16n
594 -The \fIpath\fR argument includes non-UTF8 characters and the file system
595 -accepts only file names where all characters are part of the UTF-8 character
596 -codeset.
597 -.RE
598 -
599 -.sp
600 -.ne 2
601 -.na
602 -\fB\fBEINTR\fR\fR
603 -.ad
604 -.RS 16n
605 -A signal was caught during \fBopen()\fR.
606 -.RE
607 -
608 -.sp
609 -.ne 2
610 -.na
611 -\fB\fBEFAULT\fR\fR
612 -.ad
613 -.RS 16n
614 -The \fIpath\fR argument points to an illegal address.
615 -.RE
616 -
617 -.sp
618 -.ne 2
619 -.na
620 -\fB\fBEINVAL\fR\fR
621 -.ad
622 -.RS 16n
623 -The system does not support synchronized or direct I/O for this file, or the
624 -\fBO_XATTR\fR flag was supplied and the underlying file system does not support
625 -extended file attributes.
626 -.RE
627 -
628 -.sp
629 -.ne 2
630 -.na
631 -\fB\fBEIO\fR\fR
632 -.ad
633 -.RS 16n
634 -The \fIpath\fR argument names a \fBSTREAMS\fR file and a hangup or error
635 -occurred during the \fBopen()\fR.
636 -.RE
637 -
638 -.sp
639 -.ne 2
640 -.na
641 -\fB\fBEISDIR\fR\fR
642 -.ad
643 -.RS 16n
644 -The named file is a directory and \fIoflag\fR includes \fBO_WRONLY\fR or
645 -\fBO_RDWR\fR.
646 -.RE
647 -
648 -.sp
649 -.ne 2
650 -.na
651 -\fB\fBELOOP\fR\fR
652 -.ad
653 -.RS 16n
654 -Too many symbolic links were encountered in resolving \fIpath\fR.
655 -.sp
656 -A loop exists in symbolic links encountered during resolution of the \fIpath\fR
657 -argument.
658 -.sp
659 -The \fBO_NOFOLLOW\fR flag is set and the final component of path is a symbolic
660 -link.
661 -.RE
662 -
663 -.sp
664 -.ne 2
665 -.na
666 -\fB\fBEMFILE\fR\fR
667 -.ad
668 -.RS 16n
669 -There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling
670 -process.
671 -.RE
672 -
673 -.sp
674 -.ne 2
675 -.na
676 -\fB\fBEMLINK\fR\fR
677 -.ad
678 -.RS 16n
679 -The \fBO_NOLINKS\fR flag is set and the named file has a link count greater
680 -than 1.
681 -.RE
682 -
683 -.sp
684 -.ne 2
685 -.na
686 -\fB\fBEMULTIHOP\fR\fR
687 -.ad
688 -.RS 16n
689 -Components of \fIpath\fR require hopping to multiple remote machines and the
690 -file system does not allow it.
691 -.RE
692 -
693 -.sp
694 -.ne 2
695 -.na
696 -\fB\fBENAMETOOLONG\fR\fR
697 -.ad
698 -.RS 16n
699 -The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR} or a pathname
700 -component is longer than {\fBNAME_MAX\fR}.
701 -.RE
702 -
703 -.sp
704 -.ne 2
705 -.na
706 -\fB\fBENFILE\fR\fR
707 -.ad
708 -.RS 16n
709 -The maximum allowable number of files is currently open in the system.
710 -.RE
711 -
712 -.sp
713 -.ne 2
714 -.na
715 -\fB\fBENOENT\fR\fR
716 -.ad
717 -.RS 16n
718 -The \fBO_CREAT\fR flag is not set and the named file does not exist; or the
719 -\fBO_CREAT\fR flag is set and either the path prefix does not exist or the
720 -\fIpath\fR argument points to an empty string.
721 -.sp
598 +.Vt off_t
599 +is established as the offset maximum in the open file description.
600 +.Sh RETURN VALUES
722 601 The
723 -.B O_CREAT
602 +.Fn open
724 603 and
725 -.B O_DIRECTORY
726 -flags were both set and
727 -.I path
728 -did not point to a file.
729 -.RE
730 -
731 -.sp
732 -.ne 2
733 -.na
734 -.B ENOEXEC
735 -.ad
736 -.RS 16n
737 -The \fBO_EXEC\fR flag is set and \fIpath\fR does not point to a regular
738 -file.
739 -.RE
740 -
741 -.sp
742 -.ne 2
743 -.na
744 -\fB\fBENOLINK\fR\fR
745 -.ad
746 -.RS 16n
747 -The \fIpath\fR argument points to a remote machine, and the link to that
748 -machine is no longer active.
749 -.RE
750 -
751 -.sp
752 -.ne 2
753 -.na
754 -\fB\fBENOSR\fR\fR
755 -.ad
756 -.RS 16n
757 -The \fIpath\fR argument names a STREAMS-based file and the system is unable to
758 -allocate a STREAM.
759 -.RE
760 -
761 -.sp
762 -.ne 2
763 -.na
764 -\fB\fBENOSPC\fR\fR
765 -.ad
766 -.RS 16n
767 -The directory or file system that would contain the new file cannot be
768 -expanded, the file does not exist, and \fBO_CREAT\fR is specified.
769 -.RE
770 -
771 -.sp
772 -.ne 2
773 -.na
774 -\fB\fBENOSYS\fR\fR
775 -.ad
776 -.RS 16n
777 -The device specified by \fIpath\fR does not support the open operation.
778 -.RE
779 -
780 -.sp
781 -.ne 2
782 -.na
783 -\fB\fBENOTDIR\fR\fR
784 -.ad
785 -.RS 16n
786 -A component of the path prefix is not a directory or a relative path was
787 -supplied to \fBopenat()\fR, the \fBO_XATTR\fR flag was not supplied, and the
788 -file descriptor does not refer to a directory. The \fBO_SEARCH\fR flag
789 -was passed and \fIpath\fR does not refer to a directory.
790 -.sp
791 -The
792 -.B O_DIRECTORY
793 -flag was set and the file was not a directory.
794 -.RE
795 -
796 -.sp
797 -.ne 2
798 -.na
799 -\fB\fBENXIO\fR\fR
800 -.ad
801 -.RS 16n
802 -The \fBO_NONBLOCK\fR flag is set, the named file is a FIFO, the \fBO_WRONLY\fR
803 -flag is set, and no process has the file open for reading; or the named file is
804 -a character special or block special file and the device associated with this
805 -special file does not exist or has been retired by the fault management
806 -framework .
807 -.RE
808 -
809 -.sp
810 -.ne 2
811 -.na
812 -\fB\fBEOPNOTSUPP\fR\fR
813 -.ad
814 -.RS 16n
815 -An attempt was made to open a path that corresponds to a \fBAF_UNIX\fR socket.
816 -.RE
817 -
818 -.sp
819 -.ne 2
820 -.na
821 -\fB\fBEOVERFLOW\fR\fR
822 -.ad
823 -.RS 16n
824 -The named file is a regular file and either \fBO_LARGEFILE\fR is not set and
825 -the size of the file cannot be represented correctly in an object of type
826 -\fBoff_t\fR or \fBO_LARGEFILE\fR is set and the size of the file cannot be
827 -represented correctly in an object of type \fBoff64_t\fR.
828 -.RE
829 -
830 -.sp
831 -.ne 2
832 -.na
833 -\fB\fBEROFS\fR\fR
834 -.ad
835 -.RS 16n
836 -The named file resides on a read-only file system and either \fBO_WRONLY\fR,
837 -\fBO_RDWR\fR, \fBO_CREAT\fR (if file does not exist), or \fBO_TRUNC\fR is set
838 -in the \fIoflag\fR argument.
839 -.RE
840 -
841 -.sp
842 -.LP
843 -The \fBopenat()\fR function will fail if:
844 -.sp
845 -.ne 2
846 -.na
847 -\fB\fBEBADF\fR\fR
848 -.ad
849 -.RS 9n
850 -The \fIfildes\fR argument is not a valid open file descriptor or is not
851 -\fBAT_FTCWD\fR.
852 -.RE
853 -
854 -.sp
855 -.LP
856 -The \fBopen()\fR function may fail if:
857 -.sp
858 -.ne 2
859 -.na
860 -\fB\fBEAGAIN\fR\fR
861 -.ad
862 -.RS 16n
863 -The \fIpath\fR argument names the slave side of a pseudo-terminal device that
864 -is locked.
865 -.RE
866 -
867 -.sp
868 -.ne 2
869 -.na
870 -\fB\fBEINVAL\fR\fR
871 -.ad
872 -.RS 16n
873 -The value of the \fIoflag\fR argument is not valid.
874 -.RE
875 -
876 -.sp
877 -.ne 2
878 -.na
879 -\fB\fBENAMETOOLONG\fR\fR
880 -.ad
881 -.RS 16n
882 -Pathname resolution of a symbolic link produced an intermediate result whose
883 -length exceeds {\fBPATH_MAX\fR}.
884 -.RE
885 -
886 -.sp
887 -.ne 2
888 -.na
889 -\fB\fBENOMEM\fR\fR
890 -.ad
891 -.RS 16n
892 -The \fIpath\fR argument names a \fBSTREAMS\fR file and the system is unable to
893 -allocate resources.
894 -.RE
895 -
896 -.sp
897 -.ne 2
898 -.na
899 -\fB\fBETXTBSY\fR\fR
900 -.ad
901 -.RS 16n
902 -The file is a pure procedure (shared text) file that is being executed and
903 -\fIoflag\fR is \fBO_WRONLY\fR or \fBO_RDWR\fR.
904 -.RE
905 -
906 -.SH EXAMPLES
907 -\fBExample 1 \fROpen a file for writing by the owner.
908 -.sp
909 -.LP
910 -The following example opens the file \fB/tmp/file\fR, either by creating it if
911 -it does not already exist, or by truncating its length to 0 if it does exist.
604 +.Fn openat
605 +functions open the file and, if successful, return a non-negative integer
606 +representing the lowest numbered unused file descriptor; otherwise the
607 +value
608 +.Sy -1
609 +is returned and the global variable
610 +.Va errno
611 +is set to indicate the error and no files are created or modified.
612 +.Sh EXAMPLES
613 +.Sy Example 1
614 +Open a file for writing by the owner.
615 +.Pp
616 +The following example opens the file
617 +.Pa /tmp/file ,
618 +either by creating it if it does not already exist, or by truncating its length
619 +to
620 +.Sy 0
621 +if it does exist.
912 622 If the call creates a new file, the access permission bits in the file mode of
913 623 the file are set to permit reading and writing by the owner, and to permit
914 624 reading only by group members and others.
915 -
916 -.sp
917 -.LP
918 -If the call to \fBopen()\fR is successful, the file is opened for writing.
919 -
920 -.sp
921 -.in +2
922 -.nf
625 +.Pp
626 +If the call to
627 +.Fn open
628 +is successful, the file is opened for writing.
629 +.Bd -literal -offset Ds
923 630 #include <fcntl.h>
924 631 \&...
925 632 int fd;
926 633 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
927 634 char *filename = "/tmp/file";
928 635 \&...
929 636 fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode);
930 637 \&...
931 -.fi
932 -.in -2
933 -
934 -.LP
935 -\fBExample 2 \fROpen a file using an existence check.
936 -.sp
937 -.LP
938 -The following example uses the \fBopen()\fR function to try to create the
939 -\fBLOCKFILE\fR file and open it for writing. Since the \fBopen()\fR function
940 -specifies the \fBO_EXCL\fR flag, the call fails if the file already exists. In
941 -that case, the application assumes that someone else is updating the password
942 -file and exits.
943 -
944 -.sp
945 -.in +2
946 -.nf
638 +.Ed
639 +.Pp
640 +.Sy Example 2
641 +Open a file using an existence check.
642 +.Pp
643 +The following example uses the
644 +.Fn open
645 +function to try to create the
646 +.Dv LOCKFILE
647 +file and open it for writing.
648 +Since the
649 +.Fn open
650 +function specifies the
651 +.Dv O_EXCL
652 +flag, the call fails if the file already exists.
653 +In that case, the application assumes that someone else is updating the
654 +password file and exits.
655 +.Bd -literal -offset Ds
947 656 #include <fcntl.h>
948 657 #include <stdio.h>
949 658 #include <stdlib.h>
659 +#include <err.h>
660 +\&...
950 661 #define LOCKFILE "/etc/ptmp"
951 662 \&...
952 663 int pfd; /* Integer for file descriptor returned by open() call. */
953 664 \&...
954 665 if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
955 - S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
956 -{
957 - fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en");
958 - exit(1);
666 + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) < 0) {
667 + err(1, "Cannot open %s. Try again later.", LOCKFILE);
959 668 }
960 669 \&...
961 -.fi
962 -.in -2
963 -
964 -.LP
965 -\fBExample 3 \fROpen a file for writing.
966 -.sp
967 -.LP
670 +.Ed
671 +.Pp
672 +.Sy Example 3
673 +Open a file for writing.
674 +.Pp
968 675 The following example opens a file for writing, creating the file if it does
969 -not already exist. If the file does exist, the system truncates the file to
970 -zero bytes.
971 -
972 -.sp
973 -.in +2
974 -.nf
676 +not already exist.
677 +If the file does exist, the system truncates the file to zero bytes.
678 +.Bd -literal -offset Ds
975 679 #include <fcntl.h>
976 680 #include <stdio.h>
977 681 #include <stdlib.h>
978 -#define LOCKFILE "/etc/ptmp"
682 +#include <err.h>
979 683 \&...
980 684 int pfd;
981 685 char filename[PATH_MAX+1];
982 686 \&...
983 687 if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
984 - S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
985 -{
986 - perror("Cannot open output file\en"); exit(1);
688 + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) < 0) {
689 + err(1, "Cannot open output file");
987 690 }
988 691 \&...
989 -.fi
990 -.in -2
991 -
992 -.SH USAGE
993 -The \fBopen()\fR function has a transitional interface for 64-bit file offsets.
994 -See \fBlf64\fR(5). Note that using \fBopen64()\fR is equivalent to using
995 -\fBopen()\fR with \fBO_LARGEFILE\fR set in \fIoflag\fR.
996 -.SH ATTRIBUTES
997 -See \fBattributes\fR(5) for descriptions of the following attributes:
998 -.sp
999 -
1000 -.sp
1001 -.TS
1002 -box;
1003 -c | c
1004 -l | l .
1005 -ATTRIBUTE TYPE ATTRIBUTE VALUE
1006 -_
1007 -Interface Stability Committed
1008 -_
1009 -MT-Level Async-Signal-Safe
1010 -_
1011 -Standard For \fBopen()\fR, see \fBstandards\fR(5).
1012 -.TE
1013 -
1014 -.SH SEE ALSO
1015 -\fBIntro\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
1016 -\fBexec\fR(2), \fBfcntl\fR(2), \fBgetmsg\fR(2), \fBgetrlimit\fR(2),
1017 -\fBlseek\fR(2), \fBputmsg\fR(2), \fBread\fR(2), \fBstat\fR(2), \fBumask\fR(2),
1018 -\fBwrite\fR(2), \fBattropen\fR(3C), \fBdirectio\fR(3C),
1019 -\fBfcntl.h\fR(3HEAD), \fBstat.h\fR(3HEAD),
1020 -\fBunlockpt\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), \fBprivileges\fR(5),
1021 -\fBstandards\fR(5), \fBconnld\fR(7M), \fBstreamio\fR(7I)
1022 -.SH NOTES
1023 -Hierarchical Storage Management (HSM) file systems can sometimes cause long
1024 -delays when opening a file, since HSM files must be recalled from secondary
1025 -storage.
692 +.Ed
693 +.Sh ERRORS
694 +The
695 +.Fn open
696 +and
697 +.Fn openat
698 +functions will fail if:
699 +.Bl -tag -width Er
700 +.It Er EACCES
701 +Search permission is denied on a component of the path prefix.
702 +.Pp
703 +The file exists and the permissions specified by
704 +.Fa oflag
705 +are denied.
706 +.Pp
707 +The file does not exist and write permission is denied for the parent directory
708 +of the file to be created.
709 +.Pp
710 +.Dv O_TRUNC
711 +is specified and write permission is denied.
712 +.Pp
713 +The
714 +.Brq Dv PRIV_FILE_DAC_SEARCH
715 +privilege allows processes to search directories regardless of permission bits.
716 +The
717 +.Brq Dv PRIV_FILE_DAC_WRITE
718 +privilege allows processes to open files for writing regardless of permission
719 +bits.
720 +See
721 +.Xr privileges 5 for special considerations when opening files owned by user ID
722 +.Sy 0
723 +for writing.
724 +The
725 +.Brq Dv PRIV_FILE_DAC_READ
726 +privilege allows
727 +processes to open files for reading regardless of permission bits.
728 +.It Er EAGAIN
729 +A mandatory share reservation could not be obtained because the desired access
730 +conflicts with an existing
731 +.Fa f_deny
732 +share reservation
733 +.Po
734 +see
735 +.Xr fcntl 2
736 +.Pc .
737 +.It Er EDQUOT
738 +The file does not exist,
739 +.Dv O_CREAT
740 +is specified, and either the directory where the new file entry is being placed
741 +cannot be extended because the user's quota of disk blocks on that file system
742 +has been exhausted, or the user's quota of inodes on the file system where the
743 +file is being created has been exhausted.
744 +.It Er EEXIST
745 +The
746 +.Dv O_CREAT
747 +and
748 +.Dv O_EXCL
749 +flags are set and the named file already exists.
750 +.It Er EILSEQ
751 +The
752 +.Fa path
753 +argument includes bytes that are not valid UTF-8 characters, and the file
754 +system accepts only file names where all characters are part of the UTF-8
755 +character codeset.
756 +.It Er EINTR
757 +A signal was caught during
758 +.Fn open .
759 +.It Er EFAULT
760 +The
761 +.Fa path
762 +argument points to an illegal address.
763 +.It Er EINVAL
764 +Either the system does not support synchronized or direct I/O for this file, or
765 +the
766 +.Dv O_XATTR
767 +flag was supplied and the underlying file system does not support extended file
768 +attributes.
769 +.It Er EIO
770 +The
771 +.Fa path
772 +argument names a STREAMS file and a hangup or error occurred during the
773 +.Fn open .
774 +.It Er EISDIR
775 +The named file is a directory and
776 +.Fa oflag
777 +includes
778 +.Dv O_WRONLY
779 +or
780 +.Dv O_RDWR .
781 +.It Er ELOOP
782 +Too many symbolic links were encountered in resolving
783 +.Fa path .
784 +.Pp
785 +A loop exists in symbolic links encountered during resolution of the
786 +.Fa path
787 +argument.
788 +.Pp
789 +The
790 +.Dv O_NOFOLLOW
791 +flag is set and the final component of path is a symbolic link.
792 +.It Er EMFILE
793 +There are currently
794 +.Brq Dv OPEN_MAX
795 +file descriptors open in the calling process.
796 +.It Er EMLINK
797 +The
798 +.Dv O_NOLINKS
799 +flag is set and the named file has a link count greater than
800 +.Sy 1 .
801 +.It Er EMULTIHOP
802 +Components of
803 +.Fa path
804 +require hopping to multiple remote machines and the file system does not allow
805 +it.
806 +.It Er ENAMETOOLONG
807 +The length of the
808 +.Fa path
809 +argument exceeds
810 +.Brq Dv PATH_MAX
811 +or a pathname component is longer than
812 +.Brq Dv NAME_MAX .
813 +.It Er ENFILE
814 +The maximum allowable number of files is currently open in the system.
815 +.It Er ENOENT
816 +The
817 +.Dv O_CREAT
818 +flag is not set and the named file does not exist; or the
819 +.Dv O_CREAT
820 +flag is set and either the path prefix does not exist or the
821 +.Fa path
822 +argument points to an empty string.
823 +.Pp
824 +The
825 +.Dv O_CREAT
826 +and
827 +.Dv O_DIRECTORY
828 +flags were both set and
829 +.Fa path
830 +did not point to a file.
831 +.It Er ENOEXEC
832 +The
833 +.Dv O_EXEC
834 +flag is set and
835 +.Fa path
836 +does not point to a regular file.
837 +.It Er ENOLINK
838 +The
839 +.Fa path
840 +argument points to a remote machine, and the link to that machine is no longer
841 +active.
842 +.It Er ENOSR
843 +Th
844 +.Fa path
845 +argument names a STREAMS-based file and the system is unable to allocate a
846 +STREAM.
847 +.It Er ENOSPC
848 +The directory or file system that would contain the new file cannot be
849 +expanded, the file does not exist, and
850 +.Dv O_CREAT
851 +is specified.
852 +.It Er ENOSYS
853 +The device specified by
854 +.Fa path
855 +does not support the open operation.
856 +.It Er ENOTDIR
857 +A component of the path prefix is not a directory or a relative path was
858 +supplied to
859 +.Fn openat ,
860 +the
861 +.Dv O_XATTR
862 +flag was not supplied, and the file descriptor does not refer to a directory.
863 +The
864 +.Dv O_SEARCH
865 +flag was passed and
866 +.Fa path
867 +does not refer to a directory.
868 +.Pp
869 +The
870 +.Dv O_DIRECTORY
871 +flag was set and the file was not a directory.
872 +.It Er ENXIO
873 +The
874 +.Dv O_NONBLOCK
875 +flag is set, the named file is a FIFO, the
876 +.Dv O_WRONLY
877 +flag is set, and no process has the file open for reading; or the named file is
878 +a character special or block special file and the device associated with this
879 +special file does not exist or has been retired by the fault management
880 +framework.
881 +.It Er EOPNOTSUPP
882 +An attempt was made to open a path that corresponds to an
883 +.Dv AF_UNIX
884 +socket.
885 +.It Er EOVERFLOW
886 +The named file is a regular file and either
887 +.Dv O_LARGEFILE
888 +is not set and the size of the file cannot be represented correctly in an
889 +object of type
890 +.Vt off_t
891 +or
892 +.Dv O_LARGEFILE
893 +is set and the size of the file cannot be represented correctly in an object of
894 +type
895 +.Vt off64_t .
896 +.It Er EROFS
897 +The named file resides on a read-only file system and either
898 +.Dv O_WRONLY ,
899 +.Dv O_RDWR ,
900 +.Dv O_CREAT
901 +(if file does not exist), or
902 +.Dv O_TRUNC
903 +is set in the
904 +.Fa oflag
905 +argument.
906 +.El
907 +.Pp
908 +The
909 +.Fn openat
910 +function will fail if:
911 +.Bl -tag -width Er
912 +.It Er EBADF
913 +The
914 +.Fa fildes
915 +argument is not a valid open file descriptor or is not
916 +.Dv AT_FTCWD .
917 +.El
918 +.Pp
919 +The
920 +.Fn open
921 +function may fail if:
922 +.Bl -tag -width Er
923 +.It Er EAGAIN
924 +The
925 +.Fa path
926 +argument names the subsidiary side of a pseudo-terminal device that is locked.
927 +.It Er EINVAL
928 +The value of the
929 +.Fa oflag
930 +argument is not valid.
931 +.It Er ENAMETOOLONG
932 +Pathname resolution of a symbolic link produced an intermediate result whose
933 +length exceeds
934 +.Brq Dv PATH_MAX .
935 +.It Er ENOMEM
936 +The
937 +.Fa path
938 +argument names a STREAMS file and the system is unable to allocate resources.
939 +.It Er ETXTBSY
940 +The file is a pure procedure (shared text) file that is being executed and
941 +.Fa oflag
942 +is
943 +.Dv O_WRONLY
944 +or
945 +.Dv O_RDWR .
946 +.El
947 +.Sh USAGE
948 +The
949 +.Fn open
950 +function has a transitional interface for 64-bit file offsets.
951 +See
952 +.Xr lf64 5 .
953 +Note that using
954 +.Fn open64
955 +is equivalent to using
956 +.Fn open with
957 +.Dv O_LARGEFILE
958 +set in
959 +.Fa oflag .
960 +.Sh INTERFACE STABILITY
961 +.Sy Committed
962 +.Sh MT LEVEL
963 +.Sy Async-Signal-Safe
964 +.Sh SEE ALSO
965 +.Xr chmod 2 ,
966 +.Xr close 2 ,
967 +.Xr creat 2 ,
968 +.Xr dup 2 ,
969 +.Xr exec 2 ,
970 +.Xr fcntl 2 ,
971 +.Xr getmsg 2 ,
972 +.Xr getrlimit 2 ,
973 +.Xr Intro 2 ,
974 +.Xr lseek 2 ,
975 +.Xr putmsg 2 ,
976 +.Xr read 2 ,
977 +.Xr stat 2 ,
978 +.Xr umask 2 ,
979 +.Xr write 2 ,
980 +.Xr attropen 3C ,
981 +.Xr directio 3C ,
982 +.Xr unlockpt 3C ,
983 +.Xr fcntl.h 3HEAD ,
984 +.Xr stat.h 3HEAD ,
985 +.Xr attributes 5 ,
986 +.Xr lf64 5 ,
987 +.Xr privileges 5 ,
988 +.Xr standards 5 ,
989 +.Xr streamio 7I ,
990 +.Xr connld 7M
991 +.Sh NOTES
992 +Hierarchical Storage Management
993 +.Pq HSM
994 +file systems can sometimes cause long delays when opening a file, since HSM
995 +files must be recalled from secondary storage.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX