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.man.txt
+++ new/usr/src/man/man2/open.2.man.txt
1 1 OPEN(2) System Calls OPEN(2)
2 2
3 3 NAME
4 - open, openat - open a file
4 + open, openat - open a file
5 5
6 6 SYNOPSIS
7 - #include <sys/types.h>
8 - #include <sys/stat.h>
9 - #include <fcntl.h>
7 + #include <sys/types.h>
8 + #include <sys/stat.h>
9 + #include <fcntl.h>
10 10
11 - int open(const char *path, int oflag, /* mode_t mode */);
11 + int
12 + open(const char *path, int oflag [, mode_t mode]);
12 13
14 + int
15 + openat(int fildes, const char *path, int oflag [, mode_t mode]);
13 16
14 - int openat(int fildes, const char *path, int oflag,
15 - /* mode_t mode */);
16 -
17 -
18 17 DESCRIPTION
19 - The open() function establishes the connection between a file and a
20 - file descriptor. It creates an open file description that refers to a
21 - file and a file descriptor that refers to that open file description.
22 - The file descriptor is used by other I/O functions to refer to that
23 - file. The path argument points to a pathname naming the file.
18 + The open() function establishes the connection between a file and a file
19 + descriptor. It creates an open file description that refers to a file
20 + and a file descriptor that refers to that open file description. The
21 + file descriptor is used by other I/O functions to refer to that file.
22 + The path argument points to a pathname naming the file.
24 23
24 + The openat() function is identical to the open() function except that the
25 + path argument is interpreted relative to the starting point implied by
26 + the fildes argument. If the fildes argument has the special value
27 + AT_FDCWD, a relative path argument will be resolved relative to the
28 + current working directory. If the path argument is absolute, the fildes
29 + argument is ignored.
25 30
26 - The openat() function is identical to the open() function except that
27 - the path argument is interpreted relative to the starting point implied
28 - by the fildes argument. If the fildes argument has the special value
29 - AT_FDCWD, a relative path argument will be resolved relative to the
30 - current working directory. If the path argument is absolute, the fildes
31 - argument is ignored.
31 + The open() function returns a file descriptor for the named file that is
32 + the lowest file descriptor not currently open for that process. The open
33 + file description is new, and therefore the file descriptor does not share
34 + it with any other process in the system. The FD_CLOEXEC file descriptor
35 + flag associated with the new file descriptor is cleared.
32 36
37 + The file offset used to mark the current position within the file is set
38 + to the beginning of the file.
33 39
34 - The open() function returns a file descriptor for the named file that
35 - is the lowest file descriptor not currently open for that process. The
36 - open file description is new, and therefore the file descriptor does
37 - not share it with any other process in the system. The FD_CLOEXEC file
38 - descriptor flag associated with the new file descriptor is cleared.
40 + The file status flags and file access modes of the open file description
41 + are set according to the value of oflag. The mode argument is used only
42 + when O_CREAT is specified (see below).
39 43
44 + Values for oflag are constructed by a bitwise-inclusive-OR of flags from
45 + the following list, defined in fcntl.h(3HEAD). Applications must specify
46 + exactly one of the first three values (file access modes) below in the
47 + value of oflag:
40 48
41 - The file offset used to mark the current position within the file is
42 - set to the beginning of the file.
49 + O_RDONLY
50 + Open for reading only.
43 51
52 + O_WRONLY
53 + Open for writing only.
44 54
45 - The file status flags and file access modes of the open file
46 - description are set according to the value of oflag. The mode argument
47 - is used only when O_CREAT is specified (see below.)
55 + O_RDWR Open for reading and writing. The result is undefined if this
56 + flag is applied to a FIFO.
48 57
58 + Any combination of the following may be used:
49 59
50 - Values for oflag are constructed by a bitwise-inclusive-OR of flags
51 - from the following list, defined in <fcntl.h>. Applications must
52 - specify exactly one of the first three values (file access modes) below
53 - in the value of oflag:
60 + O_APPEND
61 + If set, the file offset is set to the end of the file prior to
62 + each write.
54 63
55 - O_RDONLY
56 - Open for reading only.
64 + O_CREAT
65 + Create the file if it does not exist. This flag requires that
66 + the mode argument be specified.
57 67
68 + If the file exists, this flag has no effect except as noted under
69 + O_EXCL below. Otherwise, the file is created with the user ID of
70 + the file set to the effective user ID of the process. The group
71 + ID of the file is set to the effective group IDs of the process,
72 + or if the S_ISGID bit is set in the directory in which the file
73 + is being created, the file's group ID is set to the group ID of
74 + its parent directory. If the group ID of the new file does not
75 + match the effective group ID or one of the supplementary groups
76 + IDs, the S_ISGID bit is cleared.
58 77
59 - O_WRONLY
60 - Open for writing only.
78 + The access permission bits (see stat.h(3HEAD)) of the file mode
79 + are set to the value of mode, modified as follows (see creat(2)):
80 + a bitwise-AND is performed on the file-mode bits and the
81 + corresponding bits in the complement of the process's file mode
82 + creation mask. Thus, all bits set in the process's file mode
83 + creation mask (see umask(2)) are correspondingly cleared in the
84 + file's permission mask. The "save text image after execution
85 + bit" of the mode is cleared (see chmod(2)). When bits other than
86 + the file permission bits are set, the effect is unspecified. The
87 + mode argument does not affect whether the file is open for
88 + reading, writing or for both.
61 89
90 + O_DIRECT
91 + Indicates that the file data is not going to be reused in the
92 + near future. When possible, data is read or written directly
93 + between the application's memory and the device when the data is
94 + accessed with read(2) and write(2) operations. See directio(3C)
95 + for more details.
62 96
63 - O_RDWR
64 - Open for reading and writing. The result is undefined if
65 - this flag is applied to a FIFO.
97 + O_DIRECTORY
98 + Indicates that attempts to open path should fail unless path is a
99 + directory. If both O_CREAT and O_DIRECTORY are specified then
100 + the call will fail if it would result in a file being created.
101 + If a directory already exists at path then it will behave as if
102 + the O_DIRECTORY flag had not been present. If the O_EXCL and
103 + O_CREAT flags are specified, then the call will always fail as
104 + they imply a file should always be created.
66 105
106 + O_DSYNC
107 + Write I/O operations on the file descriptor complete as defined
108 + by synchronized I/O data integrity completion.
67 109
110 + O_EXCL If O_CREAT and O_EXCL are set, open() fails if the file exists.
111 + The check for the existence of the file and the creation of the
112 + file if it does not exist is atomic with respect to other threads
113 + executing open() naming the same filename in the same directory
114 + with O_EXCL and O_CREAT set. If O_EXCL and O_CREAT are set, and
115 + path names a symbolic link, open() fails and sets errno to
116 + EEXIST, regardless of the contents of the symbolic link. If
117 + O_EXCL is set and O_CREAT is not set, the result is undefined.
68 118
69 - Any combination of the following may be used:
119 + O_EXEC If set, indicates that the file should be opened for execute
120 + permission. This option is only valid for regular files; an
121 + error will be returned if the target is not a regular file.
70 122
71 - O_APPEND
123 + O_LARGEFILE
124 + If set, the offset maximum in the open file description is the
125 + largest value that can be represented correctly in an object of
126 + type off64_t.
72 127
73 - If set, the file offset is set to the end of the file prior to each
74 - write.
128 + O_NOCTTY
129 + If set and path identifies a terminal device, open() does not
130 + cause the terminal device to become the controlling terminal for
131 + the process.
75 132
133 + O_NOFOLLOW
134 + If the path names a symbolic link, open() fails and sets errno to
135 + ELOOP.
76 136
77 - O_CREAT
137 + O_NOLINKS
138 + If the link count of the named file is greater than 1, open()
139 + fails and sets errno to EMLINK.
78 140
79 - Create the file if it does not exist. This flag requires that the
80 - mode argument be specified.
141 + O_CLOEXEC
142 + If set, the file descriptor returned will be closed prior to any
143 + future exec(2) calls.
81 144
82 - If the file exists, this flag has no effect except as noted under
83 - O_EXCL below. Otherwise, the file is created with the user ID of
84 - the file set to the effective user ID of the process. The group ID
85 - of the file is set to the effective group IDs of the process, or if
86 - the S_ISGID bit is set in the directory in which the file is being
87 - created, the file's group ID is set to the group ID of its parent
88 - directory. If the group ID of the new file does not match the
89 - effective group ID or one of the supplementary groups IDs, the
90 - S_ISGID bit is cleared. The access permission bits (see
91 - <sys/stat.h>) of the file mode are set to the value of mode,
92 - modified as follows (see creat(2)): a bitwise-AND is performed on
93 - the file-mode bits and the corresponding bits in the complement of
94 - the process's file mode creation mask. Thus, all bits set in the
95 - process's file mode creation mask (see umask(2)) are
96 - correspondingly cleared in the file's permission mask. The "save
97 - text image after execution bit" of the mode is cleared (see
98 - chmod(2)). When bits other than the file permission bits are set,
99 - the effect is unspecified. The mode argument does not affect
100 - whether the file is open for reading, writing or for both.
145 + O_NONBLOCK O_NDELAY
146 + These flags can affect subsequent reads and writes (see read(2)
147 + and write(2)). If both O_NDELAY and O_NONBLOCK are set,
148 + O_NONBLOCK takes precedence.
101 149
150 + When opening a FIFO with O_RDONLY or O_WRONLY set:
102 151
103 - O_DIRECT
152 + o If O_NONBLOCK or O_NDELAY is set, an open() for reading only
153 + returns without delay. An open() for writing only returns an
154 + error if no process currently has the file open for reading.
104 155
105 - Indicates that the file data is not going to be reused in the near
106 - future. When possible, data is read or written directly between
107 - the application's memory and the device when the data is accessed
108 - with read(2) and write(2) operations. See directio(3C) for more
109 - details.
156 + o If O_NONBLOCK and O_NDELAY are clear, an open() for reading
157 + only blocks until a thread opens the file for writing. An
158 + open() for writing only blocks the calling thread until a
159 + thread opens the file for reading.
110 160
161 + After both ends of a FIFO have been opened once, there is no
162 + guarantee that further calls to open() O_RDONLY (O_WRONLY) will
163 + synchronize with later calls to open() O_WRONLY (O_RDONLY) until
164 + both ends of the FIFO have been closed by all readers and
165 + writers. Any data written into a FIFO will be lost if both ends
166 + of the FIFO are closed before the data is read.
111 167
112 - O_DIRECTORY
168 + When opening a block special or character special file that
169 + supports non-blocking opens:
113 170
114 - Indicates that attempts to open path should fail unless path is a
115 - directory. If both O_CREAT and O_DIRECTORY are specified then the
116 - call will fail if it would result in a file being created. If a
117 - directory already exists at path then it will behave as if the
118 - O_DIRECTORY flag had not been present. If the O_EXCL and O_CREAT
119 - flags are specified, then the call will always fail as they imply a
120 - file should always be created.
171 + o If O_NONBLOCK or O_NDELAY is set, the open() function returns
172 + without blocking for the device to be ready or available.
173 + Subsequent behavior of the device is device-specific.
121 174
175 + o If O_NONBLOCK and O_NDELAY are clear, the open() function
176 + blocks the calling thread until the device is ready or
177 + available before returning.
122 178
123 - O_DSYNC
179 + Otherwise, the behavior of O_NONBLOCK and O_NDELAY is
180 + unspecified.
124 181
125 - Write I/O operations on the file descriptor complete as defined by
126 - synchronized I/O data integrity completion.
182 + O_RSYNC
183 + Read I/O operations on the file descriptor complete at the same
184 + level of integrity as specified by the O_DSYNC and O_SYNC flags.
185 + If both O_DSYNC and O_RSYNC are set in oflag, all I/O operations
186 + on the file descriptor complete as defined by synchronized I/O
187 + data integrity completion. If both O_SYNC and O_RSYNC are set in
188 + oflag, all I/O operations on the file descriptor complete as
189 + defined by synchronized I/O file integrity completion.
127 190
191 + O_SEARCH
192 + If set, indicates that the directory should be opened for
193 + searching. This option is only valid for a directory; an error
194 + will be returned if the target is not a directory.
128 195
129 - O_EXCL
196 + O_SYNC Write I/O operations on the file descriptor complete as defined
197 + by synchronized I/O file integrity completion (see
198 + fcntl.h(3HEAD)) definition of O_SYNC.
130 199
131 - If O_CREAT and O_EXCL are set, open() fails if the file exists. The
132 - check for the existence of the file and the creation of the file if
133 - it does not exist is atomic with respect to other threads executing
134 - open() naming the same filename in the same directory with O_EXCL
135 - and O_CREAT set. If O_EXCL and O_CREAT are set, and path names a
136 - symbolic link, open() fails and sets errno to EEXIST, regardless of
137 - the contents of the symbolic link. If O_EXCL is set and O_CREAT is
138 - not set, the result is undefined.
200 + O_TRUNC
201 + If the file exists and is a regular file, and the file is
202 + successfully opened O_RDWR or O_WRONLY, its length is truncated
203 + to 0 and the mode and owner are unchanged. It has no effect on
204 + FIFO special files or terminal device files. Its effect on other
205 + file types is implementation-dependent. The result of using
206 + O_TRUNC with O_RDONLY is undefined.
139 207
208 + O_XATTR
209 + If set in openat(), a relative path argument is interpreted as a
210 + reference to an extended attribute of the file associated with
211 + the supplied file descriptor. This flag therefore requires the
212 + presence of a legal fildes argument. If set in open(), the
213 + implied file descriptor is that for the current working
214 + directory. Extended attributes must be referenced with a
215 + relative path; providing an absolute path results in a normal
216 + file reference.
140 217
141 - O_EXEC
218 + If O_CREAT is set and the file did not previously exist, upon successful
219 + completion, open() marks for update the st_atime, st_ctime, and st_mtime
220 + fields of the file and the st_ctime and st_mtime fields of the parent
221 + directory.
142 222
143 - If set, indicates that the file should be opened for execute
144 - permission. This option is only valid for regular files, an error
145 - will be returned if it is not.
223 + If O_TRUNC is set and the file did previously exist, upon successful
224 + completion, open() marks for update the st_ctime and st_mtime fields of
225 + the file.
146 226
227 + If both the O_SYNC and O_DSYNC flags are set, the effect is as if only
228 + the O_SYNC flag was set.
147 229
148 - O_LARGEFILE
230 + If path refers to a STREAMS file, oflag may be constructed from
231 + O_NONBLOCK or O_NODELAY OR-ed with either O_RDONLY, O_WRONLY, or O_RDWR.
232 + Other flag values are not applicable to STREAMS devices and have no
233 + effect on them. The values O_NONBLOCK and O_NODELAY affect the operation
234 + of STREAMS drivers and certain functions (see read(2), getmsg(2),
235 + putmsg(2), and write(2)) applied to file descriptors associated with
236 + STREAMS files. For STREAMS drivers, the implementation of O_NONBLOCK and
237 + O_NODELAY is device-specific.
149 238
150 - If set, the offset maximum in the open file description is the
151 - largest value that can be represented correctly in an object of
152 - type off64_t.
239 + When open() is invoked to open a named stream, and the connld(7M) module
240 + has been pushed on the pipe, open() blocks until the server process has
241 + issued an I_RECVFD ioctl(2) (see streamio(7I)) to receive the file
242 + descriptor.
153 243
244 + If path names the manager side of a pseudo-terminal device, then it is
245 + unspecified whether open() locks the subsidiary side so that it cannot be
246 + opened. Portable applications must call unlockpt(3C) before opening the
247 + subsidiary side.
154 248
155 - O_NOCTTY
249 + If the file is a regular file and the local file system is mounted with
250 + the nbmand mount option, then a mandatory share reservation is
251 + automatically obtained on the file. The share reservation is obtained as
252 + if fcntl(2) were called with cmd F_SHARE_NBMAND and the fshare_t values
253 + set as follows:
156 254
157 - If set and path identifies a terminal device, open() does not cause
158 - the terminal device to become the controlling terminal for the
159 - process.
160 -
161 -
162 - O_NOFOLLOW
163 -
164 - If the path names a symbolic link, open() fails and sets errno to
165 - ELOOP.
166 -
167 -
168 - O_NOLINKS
169 -
170 - If the link count of the named file is greater than 1, open() fails
171 - and sets errno to EMLINK.
172 -
173 -
174 - O_CLOEXEC
175 -
176 - If set, the file descriptor returned will be closed prior to any
177 - future exec() calls.
178 -
179 -
180 - O_NONBLOCK or O_NDELAY
181 -
182 - These flags can affect subsequent reads and writes (see read(2) and
183 - write(2)). If both O_NDELAY and O_NONBLOCK are set, O_NONBLOCK
184 - takes precedence.
185 -
186 - When opening a FIFO with O_RDONLY or O_WRONLY set:
187 -
188 - o If O_NONBLOCK or O_NDELAY is set, an open() for reading
189 - only returns without delay. An open() for writing only
190 - returns an error if no process currently has the file
191 - open for reading.
192 -
193 - o If O_NONBLOCK and O_NDELAY are clear, an open() for
194 - reading only blocks until a thread opens the file for
195 - writing. An open() for writing only blocks the calling
196 - thread until a thread opens the file for reading.
197 - After both ends of a FIFO have been opened, there is no guarantee
198 - that further calls to open() O_RDONLY (O_WRONLY) will synchronize
199 - with later calls to open() O_WRONLY (O_RDONLY) until both ends of
200 - the FIFO have been closed by all readers and writers. Any data
201 - written into a FIFO will be lost if both ends of the FIFO are
202 - closed before the data is read.
203 -
204 - When opening a block special or character special file that
205 - supports non-blocking opens:
206 -
207 - o If O_NONBLOCK or O_NDELAY is set, the open() function
208 - returns without blocking for the device to be ready or
209 - available. Subsequent behavior of the device is device-
210 - specific.
211 -
212 - o If O_NONBLOCK and O_NDELAY are clear, the open()
213 - function blocks the calling thread until the device is
214 - ready or available before returning.
215 - Otherwise, the behavior of O_NONBLOCK and O_NDELAY is unspecified.
216 -
217 -
218 - O_RSYNC
219 -
220 - Read I/O operations on the file descriptor complete at the same
221 - level of integrity as specified by the O_DSYNC and O_SYNC flags. If
222 - both O_DSYNC and O_RSYNC are set in oflag, all I/O operations on
223 - the file descriptor complete as defined by synchronized I/O data
224 - integrity completion. If both O_SYNC and O_RSYNC are set in oflag,
225 - all I/O operations on the file descriptor complete as defined by
226 - synchronized I/O file integrity completion.
227 -
228 -
229 - O_SEARCH
230 -
231 - If set, indicates that the directory should be opened for
232 - searching. This option is only valid for a directory, an error
233 - will be returned if it is not.
234 -
235 -
236 - O_SYNC
237 -
238 - Write I/O operations on the file descriptor complete as defined by
239 - synchronized I/O file integrity completion (see fcntl.h(3HEAD)
240 - definition of O_SYNC).
241 -
242 -
243 - O_TRUNC
244 -
245 - If the file exists and is a regular file, and the file is
246 - successfully opened O_RDWR or O_WRONLY, its length is truncated to
247 - 0 and the mode and owner are unchanged. It has no effect on FIFO
248 - special files or terminal device files. Its effect on other file
249 - types is implementation-dependent. The result of using O_TRUNC with
250 - O_RDONLY is undefined.
251 -
252 -
253 - O_XATTR
254 -
255 - If set in openat(), a relative path argument is interpreted as a
256 - reference to an extended attribute of the file associated with the
257 - supplied file descriptor. This flag therefore requires the
258 - presence of a legal fildes argument. If set in open(), the implied
259 - file descriptor is that for the current working directory. Extended
260 - attributes must be referenced with a relative path; providing an
261 - absolute path results in a normal file reference.
262 -
263 -
264 -
265 - If O_CREAT is set and the file did not previously exist, upon
266 - successful completion, open() marks for update the st_atime, st_ctime,
267 - and st_mtime fields of the file and the st_ctime and st_mtime fields of
268 - the parent directory.
269 -
270 -
271 - If O_TRUNC is set and the file did previously exist, upon successful
272 - completion, open() marks for update the st_ctime and st_mtime fields of
273 - the file.
274 -
275 -
276 - If both the O_SYNC and O_DSYNC flags are set, the effect is as if only
277 - the O_SYNC flag was set.
278 -
279 -
280 - If path refers to a STREAMS file, oflag may be constructed from
281 - O_NONBLOCK or O_NODELAY OR-ed with either O_RDONLY, O_WRONLY, or
282 - O_RDWR. Other flag values are not applicable to STREAMS devices and
283 - have no effect on them. The values O_NONBLOCK and O_NODELAY affect the
284 - operation of STREAMS drivers and certain functions (see read(2),
285 - getmsg(2), putmsg(2), and write(2)) applied to file descriptors
286 - associated with STREAMS files. For STREAMS drivers, the implementation
287 - of O_NONBLOCK and O_NODELAY is device-specific.
288 -
289 -
290 - When open() is invoked to open a named stream, and the connld module
291 - (see connld(7M)) has been pushed on the pipe, open() blocks until the
292 - server process has issued an I_RECVFD ioctl() (see streamio(7I)) to
293 - receive the file descriptor.
294 -
295 -
296 - If path names the master side of a pseudo-terminal device, then it is
297 - unspecified whether open() locks the slave side so that it cannot be
298 - opened. Portable applications must call unlockpt(3C) before opening
299 - the slave side.
300 -
301 -
302 - If the file is a regular file and the local file system is mounted with
303 - the nbmand mount option, then a mandatory share reservation is
304 - automatically obtained on the file. The share reservation is obtained
305 - as if fcntl(2) were called with cmd F_SHARE_NBMAND and the fshare_t
306 - values set as follows:
307 -
308 - f_access
255 + f_access
309 256 Set to the type of read/write access for which the file is
310 257 opened.
311 258
259 + f_deny F_NODNY
312 260
313 - f_deny
314 - F_NODNY
261 + f_id The file descriptor value returned from open().
315 262
263 + If path is a symbolic link and O_CREAT and O_EXCL are set, the link is
264 + not followed.
316 265
317 - f_id
318 - The file descriptor value returned from open().
266 + Certain flag values can be set following open() as described in fcntl(2).
319 267
268 + The largest value that can be represented correctly in an object of type
269 + off_t is established as the offset maximum in the open file description.
320 270
321 -
322 - If path is a symbolic link and O_CREAT and O_EXCL are set, the link is
323 - not followed.
324 -
325 -
326 - Certain flag values can be set following open() as described in
327 - fcntl(2).
328 -
329 -
330 - The largest value that can be represented correctly in an object of
331 - type off_t is established as the offset maximum in the open file
332 - description.
333 -
334 271 RETURN VALUES
335 - Upon successful completion, both open() and openat() functions open the
336 - file and return a non-negative integer representing the lowest numbered
337 - unused file descriptor. Otherwise, -1 is returned, errno is set to
338 - indicate the error, and no files are created or modified.
272 + The open() and openat() functions open the file and, if successful,
273 + return a non-negative integer representing the lowest numbered unused
274 + file descriptor; otherwise the value -1 is returned and the global
275 + variable errno is set to indicate the error and no files are created or
276 + modified.
339 277
340 -ERRORS
341 - The open() and openat() functions will fail if:
278 +EXAMPLES
279 + Example 1 Open a file for writing by the owner.
342 280
343 - EACCES
344 - Search permission is denied on a component of the path
345 - prefix.
281 + The following example opens the file /tmp/file, either by creating it if
282 + it does not already exist, or by truncating its length to 0 if it does
283 + exist. If the call creates a new file, the access permission bits in the
284 + file mode of the file are set to permit reading and writing by the owner,
285 + and to permit reading only by group members and others.
346 286
347 - The file exists and the permissions specified by oflag
348 - are denied.
287 + If the call to open() is successful, the file is opened for writing.
349 288
350 - The file does not exist and write permission is denied
351 - for the parent directory of the file to be created.
289 + #include <fcntl.h>
290 + ...
291 + int fd;
292 + mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
293 + char *filename = "/tmp/file";
294 + ...
295 + fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode);
296 + ...
352 297
353 - O_TRUNC is specified and write permission is denied.
298 + Example 2 Open a file using an existence check.
354 299
355 - The {PRIV_FILE_DAC_SEARCH} privilege allows processes
356 - to search directories regardless of permission bits.
357 - The {PRIV_FILE_DAC_WRITE} privilege allows processes to
358 - open files for writing regardless of permission bits.
359 - See privileges(5) for special considerations when
360 - opening files owned by UID 0 for writing. The
361 - {PRIV_FILE_DAC_READ} privilege allows processes to open
362 - files for reading regardless of permission bits.
300 + The following example uses the open() function to try to create the
301 + LOCKFILE file and open it for writing. Since the open() function
302 + specifies the O_EXCL flag, the call fails if the file already exists. In
303 + that case, the application assumes that someone else is updating the
304 + password file and exits.
363 305
306 + #include <fcntl.h>
307 + #include <stdio.h>
308 + #include <stdlib.h>
309 + #include <err.h>
310 + ...
311 + #define LOCKFILE "/etc/ptmp"
312 + ...
313 + int pfd; /* Integer for file descriptor returned by open() call. */
314 + ...
315 + if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
316 + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) < 0) {
317 + err(1, "Cannot open %s. Try again later.", LOCKFILE);
318 + }
319 + ...
364 320
365 - EAGAIN
366 - A mandatory share reservation could not be obtained
367 - because the desired access conflicts with an existing
368 - f_deny share reservation.
321 + Example 3 Open a file for writing.
369 322
323 + The following example opens a file for writing, creating the file if it
324 + does not already exist. If the file does exist, the system truncates the
325 + file to zero bytes.
370 326
371 - EDQUOT
372 - The file does not exist, O_CREAT is specified, and
373 - either the directory where the new file entry is being
374 - placed cannot be extended because the user's quota of
375 - disk blocks on that file system has been exhausted, or
376 - the user's quota of inodes on the file system where the
377 - file is being created has been exhausted.
327 + #include <fcntl.h>
328 + #include <stdio.h>
329 + #include <stdlib.h>
330 + #include <err.h>
331 + ...
332 + int pfd;
333 + char filename[PATH_MAX+1];
334 + ...
335 + if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
336 + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) < 0) {
337 + err(1, "Cannot open output file");
338 + }
339 + ...
378 340
341 +ERRORS
342 + The open() and openat() functions will fail if:
379 343
380 - EEXIST
381 - The O_CREAT and O_EXCL flags are set and the named file
382 - exists.
344 + EACCES Search permission is denied on a component of the path
345 + prefix.
383 346
347 + The file exists and the permissions specified by oflag
348 + are denied.
384 349
385 - EILSEQ
386 - The path argument includes non-UTF8 characters and the
387 - file system accepts only file names where all
388 - characters are part of the UTF-8 character codeset.
350 + The file does not exist and write permission is denied
351 + for the parent directory of the file to be created.
389 352
353 + O_TRUNC is specified and write permission is denied.
390 354
391 - EINTR
392 - A signal was caught during open().
355 + The {PRIV_FILE_DAC_SEARCH} privilege allows processes
356 + to search directories regardless of permission bits.
357 + The {PRIV_FILE_DAC_WRITE} privilege allows processes
358 + to open files for writing regardless of permission
359 + bits. See privileges(5) for special considerations
360 + when opening files owned by user ID 0 for writing.
361 + The {PRIV_FILE_DAC_READ} privilege allows processes to
362 + open files for reading regardless of permission bits.
393 363
364 + EAGAIN A mandatory share reservation could not be obtained
365 + because the desired access conflicts with an existing
366 + f_deny share reservation (see fcntl(2)).
394 367
395 - EFAULT
396 - The path argument points to an illegal address.
368 + EDQUOT The file does not exist, O_CREAT is specified, and
369 + either the directory where the new file entry is being
370 + placed cannot be extended because the user's quota of
371 + disk blocks on that file system has been exhausted, or
372 + the user's quota of inodes on the file system where
373 + the file is being created has been exhausted.
397 374
375 + EEXIST The O_CREAT and O_EXCL flags are set and the named
376 + file already exists.
398 377
399 - EINVAL
400 - The system does not support synchronized or direct I/O
401 - for this file, or the O_XATTR flag was supplied and the
402 - underlying file system does not support extended file
403 - attributes.
378 + EILSEQ The path argument includes bytes that are not valid
379 + UTF-8 characters, and the file system accepts only
380 + file names where all characters are part of the UTF-8
381 + character codeset.
404 382
383 + EINTR A signal was caught during open().
405 384
406 - EIO
407 - The path argument names a STREAMS file and a hangup or
408 - error occurred during the open().
385 + EFAULT The path argument points to an illegal address.
409 386
387 + EINVAL Either the system does not support synchronized or
388 + direct I/O for this file, or the O_XATTR flag was
389 + supplied and the underlying file system does not
390 + support extended file attributes.
410 391
411 - EISDIR
412 - The named file is a directory and oflag includes
413 - O_WRONLY or O_RDWR.
392 + EIO The path argument names a STREAMS file and a hangup or
393 + error occurred during the open().
414 394
395 + EISDIR The named file is a directory and oflag includes
396 + O_WRONLY or O_RDWR.
415 397
416 - ELOOP
417 - Too many symbolic links were encountered in resolving
418 - path.
398 + ELOOP Too many symbolic links were encountered in resolving
399 + path.
419 400
420 - A loop exists in symbolic links encountered during
421 - resolution of the path argument.
401 + A loop exists in symbolic links encountered during
402 + resolution of the path argument.
422 403
423 - The O_NOFOLLOW flag is set and the final component of
424 - path is a symbolic link.
404 + The O_NOFOLLOW flag is set and the final component of
405 + path is a symbolic link.
425 406
407 + EMFILE There are currently {OPEN_MAX} file descriptors open
408 + in the calling process.
426 409
427 - EMFILE
428 - There are currently {OPEN_MAX} file descriptors open in
429 - the calling process.
410 + EMLINK The O_NOLINKS flag is set and the named file has a
411 + link count greater than 1.
430 412
413 + EMULTIHOP Components of path require hopping to multiple remote
414 + machines and the file system does not allow it.
431 415
432 - EMLINK
433 - The O_NOLINKS flag is set and the named file has a link
434 - count greater than 1.
416 + ENAMETOOLONG The length of the path argument exceeds {PATH_MAX} or
417 + a pathname component is longer than {NAME_MAX}.
435 418
419 + ENFILE The maximum allowable number of files is currently
420 + open in the system.
436 421
437 - EMULTIHOP
438 - Components of path require hopping to multiple remote
439 - machines and the file system does not allow it.
422 + ENOENT The O_CREAT flag is not set and the named file does
423 + not exist; or the O_CREAT flag is set and either the
424 + path prefix does not exist or the path argument points
425 + to an empty string.
440 426
427 + The O_CREAT and O_DIRECTORY flags were both set and
428 + path did not point to a file.
441 429
442 - ENAMETOOLONG
443 - The length of the path argument exceeds {PATH_MAX} or a
444 - pathname component is longer than {NAME_MAX}.
430 + ENOEXEC The O_EXEC flag is set and path does not point to a
431 + regular file.
445 432
433 + ENOLINK The path argument points to a remote machine, and the
434 + link to that machine is no longer active.
446 435
447 - ENFILE
448 - The maximum allowable number of files is currently open
449 - in the system.
436 + ENOSR Th path argument names a STREAMS-based file and the
437 + system is unable to allocate a STREAM.
450 438
439 + ENOSPC The directory or file system that would contain the
440 + new file cannot be expanded, the file does not exist,
441 + and O_CREAT is specified.
451 442
452 - ENOENT
453 - The O_CREAT flag is not set and the named file does not
454 - exist; or the O_CREAT flag is set and either the path
455 - prefix does not exist or the path argument points to an
456 - empty string.
443 + ENOSYS The device specified by path does not support the open
444 + operation.
457 445
458 - The O_CREAT and O_DIRECTORY flags were both set and
459 - path did not point to a file.
446 + ENOTDIR A component of the path prefix is not a directory or a
447 + relative path was supplied to openat(), the O_XATTR
448 + flag was not supplied, and the file descriptor does
449 + not refer to a directory. The O_SEARCH flag was
450 + passed and path does not refer to a directory.
460 451
452 + The O_DIRECTORY flag was set and the file was not a
453 + directory.
461 454
462 - ENOEXEC
463 - The O_EXEC flag is set and path does not point to a
464 - regular file.
455 + ENXIO The O_NONBLOCK flag is set, the named file is a FIFO,
456 + the O_WRONLY flag is set, and no process has the file
457 + open for reading; or the named file is a character
458 + special or block special file and the device
459 + associated with this special file does not exist or
460 + has been retired by the fault management framework.
465 461
462 + EOPNOTSUPP An attempt was made to open a path that corresponds to
463 + an AF_UNIX socket.
466 464
467 - ENOLINK
468 - The path argument points to a remote machine, and the
469 - link to that machine is no longer active.
465 + EOVERFLOW The named file is a regular file and either
466 + O_LARGEFILE is not set and the size of the file cannot
467 + be represented correctly in an object of type off_t or
468 + O_LARGEFILE is set and the size of the file cannot be
469 + represented correctly in an object of type off64_t.
470 470
471 + EROFS The named file resides on a read-only file system and
472 + either O_WRONLY, O_RDWR, O_CREAT (if file does not
473 + exist), or O_TRUNC is set in the oflag argument.
471 474
472 - ENOSR
473 - The path argument names a STREAMS-based file and the
474 - system is unable to allocate a STREAM.
475 + The openat() function will fail if:
475 476
477 + EBADF The fildes argument is not a valid open file
478 + descriptor or is not AT_FTCWD.
476 479
477 - ENOSPC
478 - The directory or file system that would contain the new
479 - file cannot be expanded, the file does not exist, and
480 - O_CREAT is specified.
480 + The open() function may fail if:
481 481
482 + EAGAIN The path argument names the subsidiary side of a
483 + pseudo-terminal device that is locked.
482 484
483 - ENOSYS
484 - The device specified by path does not support the open
485 - operation.
485 + EINVAL The value of the oflag argument is not valid.
486 486
487 + ENAMETOOLONG Pathname resolution of a symbolic link produced an
488 + intermediate result whose length exceeds {PATH_MAX}.
487 489
488 - ENOTDIR
489 - A component of the path prefix is not a directory or a
490 - relative path was supplied to openat(), the O_XATTR
491 - flag was not supplied, and the file descriptor does not
492 - refer to a directory. The O_SEARCH flag was passed and
493 - path does not refer to a directory.
490 + ENOMEM The path argument names a STREAMS file and the system
491 + is unable to allocate resources.
494 492
495 - The O_DIRECTORY flag was set and the file was not a
496 - directory.
493 + ETXTBSY The file is a pure procedure (shared text) file that
494 + is being executed and oflag is O_WRONLY or O_RDWR.
497 495
498 -
499 - ENXIO
500 - The O_NONBLOCK flag is set, the named file is a FIFO,
501 - the O_WRONLY flag is set, and no process has the file
502 - open for reading; or the named file is a character
503 - special or block special file and the device associated
504 - with this special file does not exist or has been
505 - retired by the fault management framework .
506 -
507 -
508 - EOPNOTSUPP
509 - An attempt was made to open a path that corresponds to
510 - a AF_UNIX socket.
511 -
512 -
513 - EOVERFLOW
514 - The named file is a regular file and either O_LARGEFILE
515 - is not set and the size of the file cannot be
516 - represented correctly in an object of type off_t or
517 - O_LARGEFILE is set and the size of the file cannot be
518 - represented correctly in an object of type off64_t.
519 -
520 -
521 - EROFS
522 - The named file resides on a read-only file system and
523 - either O_WRONLY, O_RDWR, O_CREAT (if file does not
524 - exist), or O_TRUNC is set in the oflag argument.
525 -
526 -
527 -
528 - The openat() function will fail if:
529 -
530 - EBADF
531 - The fildes argument is not a valid open file descriptor or is
532 - not AT_FTCWD.
533 -
534 -
535 -
536 - The open() function may fail if:
537 -
538 - EAGAIN
539 - The path argument names the slave side of a pseudo-
540 - terminal device that is locked.
541 -
542 -
543 - EINVAL
544 - The value of the oflag argument is not valid.
545 -
546 -
547 - ENAMETOOLONG
548 - Pathname resolution of a symbolic link produced an
549 - intermediate result whose length exceeds {PATH_MAX}.
550 -
551 -
552 - ENOMEM
553 - The path argument names a STREAMS file and the system
554 - is unable to allocate resources.
555 -
556 -
557 - ETXTBSY
558 - The file is a pure procedure (shared text) file that is
559 - being executed and oflag is O_WRONLY or O_RDWR.
560 -
561 -
562 -EXAMPLES
563 - Example 1 Open a file for writing by the owner.
564 -
565 -
566 - The following example opens the file /tmp/file, either by creating it
567 - if it does not already exist, or by truncating its length to 0 if it
568 - does exist. If the call creates a new file, the access permission bits
569 - in the file mode of the file are set to permit reading and writing by
570 - the owner, and to permit reading only by group members and others.
571 -
572 -
573 -
574 - If the call to open() is successful, the file is opened for writing.
575 -
576 -
577 - #include <fcntl.h>
578 - ...
579 - int fd;
580 - mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
581 - char *filename = "/tmp/file";
582 - ...
583 - fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode);
584 - ...
585 -
586 -
587 - Example 2 Open a file using an existence check.
588 -
589 -
590 - The following example uses the open() function to try to create the
591 - LOCKFILE file and open it for writing. Since the open() function
592 - specifies the O_EXCL flag, the call fails if the file already exists.
593 - In that case, the application assumes that someone else is updating the
594 - password file and exits.
595 -
596 -
597 - #include <fcntl.h>
598 - #include <stdio.h>
599 - #include <stdlib.h>
600 - #define LOCKFILE "/etc/ptmp"
601 - ...
602 - int pfd; /* Integer for file descriptor returned by open() call. */
603 - ...
604 - if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
605 - S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
606 - {
607 - fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n");
608 - exit(1);
609 - }
610 - ...
611 -
612 -
613 - Example 3 Open a file for writing.
614 -
615 -
616 - The following example opens a file for writing, creating the file if it
617 - does not already exist. If the file does exist, the system truncates
618 - the file to zero bytes.
619 -
620 -
621 - #include <fcntl.h>
622 - #include <stdio.h>
623 - #include <stdlib.h>
624 - #define LOCKFILE "/etc/ptmp"
625 - ...
626 - int pfd;
627 - char filename[PATH_MAX+1];
628 - ...
629 - if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
630 - S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
631 - {
632 - perror("Cannot open output file\n"); exit(1);
633 - }
634 - ...
635 -
636 -
637 496 USAGE
638 - The open() function has a transitional interface for 64-bit file
639 - offsets. See lf64(5). Note that using open64() is equivalent to using
640 - open() with O_LARGEFILE set in oflag.
497 + The open() function has a transitional interface for 64-bit file offsets.
498 + See lf64(5). Note that using open64() is equivalent to using open(with)
499 + O_LARGEFILE set in oflag.
641 500
642 -ATTRIBUTES
643 - See attributes(5) for descriptions of the following attributes:
501 +INTERFACE STABILITY
502 + Committed
644 503
504 +MT LEVEL
505 + Async-Signal-Safe
645 506
646 -
647 -
648 - +--------------------+-------------------------------+
649 - | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
650 - +--------------------+-------------------------------+
651 - |Interface Stability | Committed |
652 - +--------------------+-------------------------------+
653 - |MT-Level | Async-Signal-Safe |
654 - +--------------------+-------------------------------+
655 - |Standard | For open(), see standards(5). |
656 - +--------------------+-------------------------------+
657 -
658 507 SEE ALSO
659 - Intro(2), chmod(2), close(2), creat(2), dup(2), exec(2), fcntl(2),
660 - getmsg(2), getrlimit(2), lseek(2), putmsg(2), read(2), stat(2),
661 - umask(2), write(2), attropen(3C), directio(3C), fcntl.h(3HEAD),
662 - stat.h(3HEAD), unlockpt(3C), attributes(5), lf64(5), privileges(5),
663 - standards(5), connld(7M), streamio(7I)
508 + chmod(2), close(2), creat(2), dup(2), exec(2), fcntl(2), getmsg(2),
509 + getrlimit(2), Intro(2), lseek(2), putmsg(2), read(2), stat(2), umask(2),
510 + write(2), attropen(3C), directio(3C), unlockpt(3C), fcntl.h(3HEAD),
511 + stat.h(3HEAD), attributes(5), lf64(5), privileges(5), standards(5),
512 + streamio(7I), connld(7M)
664 513
665 514 NOTES
666 - Hierarchical Storage Management (HSM) file systems can sometimes cause
667 - long delays when opening a file, since HSM files must be recalled from
668 - secondary storage.
515 + Hierarchical Storage Management (HSM) file systems can sometimes cause
516 + long delays when opening a file, since HSM files must be recalled from
517 + secondary storage.
669 518
670 - March 10, 2020 OPEN(2)
519 +illumos February 5, 2022 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX