open.2 (aefb332f5664b51526fd3e7d0b3cb6bdda1e1758) open.2 (1fa2a66491e7d8ae0be84e7da4da8e812480c710)
1.\"
2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3.\" permission to reproduce portions of its copyrighted documentation.
4.\" Original documentation from The Open Group can be obtained online at
5.\" http://www.opengroup.org/bookstore/.
6.\"
7.\" The Institute of Electrical and Electronics Engineers and The Open
8.\" Group, have given us permission to reprint portions of their

--- 33 unchanged lines hidden (view full) ---

42.\"
43.\" Copyright 1989 AT&T
44.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
46.\" Portions Copyright (c) 2013, OmniTI Computer Consulting, Inc.
47.\" All Rights Reserved.
48.\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
49.\" Copyright 2020 Joyent, Inc.
1.\"
2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3.\" permission to reproduce portions of its copyrighted documentation.
4.\" Original documentation from The Open Group can be obtained online at
5.\" http://www.opengroup.org/bookstore/.
6.\"
7.\" The Institute of Electrical and Electronics Engineers and The Open
8.\" Group, have given us permission to reprint portions of their

--- 33 unchanged lines hidden (view full) ---

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