Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)open.2 6.7 (Berkeley) 5/27/91 | |
33 | .\" | |
34 | .Dd May 27, 1991 | |
35 | .Dt OPEN 2 | |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm open | |
39 | .Nd open or create a file for reading or writing | |
40 | .Sh SYNOPSIS | |
41 | .Fd #include <sys/file.h> | |
42 | .Ft int | |
43 | .Fn open "const char *path" "int flags" "mode_t mode" | |
44 | .Sh DESCRIPTION | |
45 | The file name specified by | |
46 | .Fa path | |
47 | is opened | |
48 | for reading and/or writing as specified by the | |
49 | argument | |
50 | .Fa flags | |
51 | and the file descriptor returned to the calling process. | |
52 | The | |
53 | .Fa flags | |
54 | argument may indicate the file is to be | |
55 | created if it does not exist (by specifying the | |
56 | .Dv O_CREAT | |
57 | flag), in which case the file is created with mode | |
58 | .Fa mode | |
59 | as described in | |
60 | .Xr chmod 2 | |
61 | and modified by the process' umask value (see | |
62 | .Xr umask 2 ) . | |
63 | .Pp | |
64 | The flags specified are formed by | |
65 | .Em or Ap ing | |
66 | the following values | |
67 | .Pp | |
68 | .Bd -literal -offset indent -compact | |
69 | O_RDONLY open for reading only | |
70 | O_WRONLY open for writing only | |
71 | O_RDWR open for reading and writing | |
72 | O_NONBLOCK do not block on open | |
73 | O_APPEND append on each write | |
74 | O_CREAT create file if it does not exist | |
75 | O_TRUNC truncate size to 0 | |
76 | O_EXCL error if create and file exists | |
77 | O_SHLOCK atomically obtain a shared lock | |
78 | O_EXLOCK atomically obtain an exclusive lock | |
79 | .Ed | |
80 | .Pp | |
81 | Opening a file with | |
82 | .Dv O_APPEND | |
83 | set causes each write on the file | |
84 | to be appended to the end. If | |
85 | .Dv O_TRUNC | |
86 | is specified and the | |
87 | file exists, the file is truncated to zero length. | |
88 | If | |
89 | .Dv O_EXCL | |
90 | is set with | |
91 | .Dv O_CREAT | |
92 | and the file already | |
93 | exists, | |
94 | .Fn open | |
95 | returns an error. This may be used to | |
96 | implement a simple exclusive access locking mechanism. | |
97 | If | |
98 | .Dv O_EXCL | |
99 | is set and the last component of the pathname is | |
100 | a symbolic link, | |
101 | .Fn open | |
102 | will fail even if the symbolic | |
103 | link points to a non-existent name. | |
104 | If the | |
105 | .Dv O_NONBLOCK | |
106 | flag is specified and the | |
107 | .Fn open | |
108 | call would result | |
109 | in the process being blocked for some reason (e.g., waiting for | |
110 | carrier on a dialup line), | |
111 | .Fn open | |
112 | returns immediately. | |
113 | The first time the process attempts to perform I/O on the open | |
114 | file it will block (not currently implemented). | |
115 | .Pp | |
116 | When opening a file, a lock with | |
117 | .Xr flock 2 | |
118 | semantics can be obtained by setting | |
119 | .Dv O_SHLOCK | |
120 | for a shared lock, or | |
121 | .Dv O_EXLOCK | |
122 | for an exclusive lock. | |
123 | If creating a file with | |
124 | .Dv O_CREAT , | |
125 | the request for the lock will never fail | |
126 | (provided that the underlying filesystem supports locking). | |
127 | .Pp | |
128 | If successful, | |
129 | .Fn open | |
130 | returns a non-negative integer, termed a | |
131 | file descriptor. It returns -1 on failure. | |
132 | The file pointer used to mark the current position within the | |
133 | file is set to the beginning of the file. | |
134 | .Pp | |
135 | The new descriptor is set to remain open across | |
136 | .Xr execve | |
137 | system calls; see | |
138 | .Xr close 2 | |
139 | and | |
140 | .Xr fcntl 2 . | |
141 | .Pp | |
142 | The system imposes a limit on the number of file descriptors | |
143 | open simultaneously by one process. | |
144 | .Xr Getdtablesize 2 | |
145 | returns the current system limit. | |
146 | .Sh ERRORS | |
147 | The named file is opened unless: | |
148 | .Bl -tag -width Er | |
149 | .It Bq Er ENOTDIR | |
150 | A component of the path prefix is not a directory. | |
151 | .It Bq Er ENAMETOOLONG | |
152 | A component of a pathname exceeded 255 characters, | |
153 | or an entire path name exceeded 1023 characters. | |
154 | .It Bq Er ENOENT | |
155 | .Dv O_CREAT | |
156 | is not set and the named file does not exist. | |
157 | .It Bq Er ENOENT | |
158 | A component of the path name that must exist does not exist. | |
159 | .It Bq Er EACCES | |
160 | Search permission is denied for a component of the path prefix. | |
161 | .It Bq Er EACCES | |
162 | The required permissions (for reading and/or writing) | |
163 | are denied for the given flags. | |
164 | .It Bq Er EACCES | |
165 | .Dv O_CREAT | |
166 | is specified, | |
167 | the file does not exist, | |
168 | and the directory in which it is to be created | |
169 | does not permit writing. | |
170 | .It Bq Er ELOOP | |
171 | Too many symbolic links were encountered in translating the pathname. | |
172 | .It Bq Er EISDIR | |
173 | The named file is a directory, and the arguments specify | |
174 | it is to be opened for writing. | |
175 | .It Bq Er EROFS | |
176 | The named file resides on a read-only file system, | |
177 | and the file is to be modified. | |
178 | .It Bq Er EMFILE | |
179 | The process has already reached its limit for open file descriptors. | |
180 | .It Bq Er ENFILE | |
181 | The system file table is full. | |
182 | .It Bq Er ENXIO | |
183 | The named file is a character special or block | |
184 | special file, and the device associated with this special file | |
185 | does not exist. | |
186 | .It Bq Er EINTR | |
187 | The | |
188 | .Nm | |
189 | operation was interrupted by a signal. | |
190 | .It Bq Er EOPNOTSUPP | |
191 | .Dv O_SHLOCK | |
192 | or | |
193 | .Dv O_EXLOCK | |
194 | is specified but the underlying filesystem does not support locking. | |
195 | .It Bq Er ENOSPC | |
196 | .Dv O_CREAT | |
197 | is specified, | |
198 | the file does not exist, | |
199 | and the directory in which the entry for the new file is being placed | |
200 | cannot be extended because there is no space left on the file | |
201 | system containing the directory. | |
202 | .It Bq Er ENOSPC | |
203 | .Dv O_CREAT | |
204 | is specified, | |
205 | the file does not exist, | |
206 | and there are no free inodes on the file system on which the | |
207 | file is being created. | |
208 | .It Bq Er EDQUOT | |
209 | .Dv O_CREAT | |
210 | is specified, | |
211 | the file does not exist, | |
212 | and the directory in which the entry for the new file | |
213 | is being placed cannot be extended because the | |
214 | user's quota of disk blocks on the file system | |
215 | containing the directory has been exhausted. | |
216 | .It Bq Er EDQUOT | |
217 | .Dv O_CREAT | |
218 | is specified, | |
219 | the file does not exist, | |
220 | and the user's quota of inodes on the file system on | |
221 | which the file is being created has been exhausted. | |
222 | .It Bq Er EIO | |
223 | An I/O error occurred while making the directory entry or | |
224 | allocating the inode for | |
225 | .Dv O_CREAT . | |
226 | .It Bq Er ETXTBSY | |
227 | The file is a pure procedure (shared text) file that is being | |
228 | executed and the | |
229 | .Fn open | |
230 | call requests write access. | |
231 | .It Bq Er EFAULT | |
232 | .Fa Path | |
233 | points outside the process's allocated address space. | |
234 | .It Bq Er EEXIST | |
235 | .Dv O_CREAT | |
236 | and | |
237 | .Dv O_EXCL | |
238 | were specified and the file exists. | |
239 | .It Bq Er EOPNOTSUPP | |
240 | An attempt was made to open a socket (not currently implemented). | |
241 | .El | |
242 | .Sh SEE ALSO | |
243 | .Xr chmod 2 , | |
244 | .Xr close 2 , | |
245 | .Xr dup 2 , | |
246 | .Xr getdtablesize 2 , | |
247 | .Xr lseek 2 , | |
248 | .Xr read 2 , | |
249 | .Xr write 2 , | |
250 | .Xr umask 2 | |
251 | .Sh HISTORY | |
252 | An | |
253 | .Nm | |
326e0c26 GW |
254 | function call appeared in |
255 | .At v6 . |