Commit | Line | Data |
---|---|---|
931b8415 CL |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
7c9fa549 | 3 | .\" |
931b8415 | 4 | .\" %sccs.include.redist.man% |
7c9fa549 | 5 | .\" |
ac6404fc | 6 | .\" @(#)open.2 6.9 (Berkeley) %G% |
931b8415 CL |
7 | .\" |
8 | .Dd | |
9 | .Dt OPEN 2 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm open | |
13 | .Nd open or create a file for reading or writing | |
14 | .Sh SYNOPSIS | |
ac6404fc | 15 | .Fd #include <fcntl.h> |
931b8415 CL |
16 | .Ft int |
17 | .Fn open "const char *path" "int flags" "mode_t mode" | |
18 | .Sh DESCRIPTION | |
19 | The file name specified by | |
20 | .Fa path | |
21 | is opened | |
22 | for reading and/or writing as specified by the | |
23 | argument | |
24 | .Fa flags | |
25 | and the file descriptor returned to the calling process. | |
87d6e244 | 26 | The |
931b8415 | 27 | .Fa flags |
87d6e244 | 28 | argument may indicate the file is to be |
931b8415 CL |
29 | created if it does not exist (by specifying the |
30 | .Dv O_CREAT | |
31 | flag), in which case the file is created with mode | |
32 | .Fa mode | |
87d6e244 | 33 | as described in |
931b8415 | 34 | .Xr chmod 2 |
87d6e244 | 35 | and modified by the process' umask value (see |
931b8415 CL |
36 | .Xr umask 2 ) . |
37 | .Pp | |
87d6e244 | 38 | The flags specified are formed by |
931b8415 | 39 | .Em or Ap ing |
87d6e244 | 40 | the following values |
931b8415 CL |
41 | .Pp |
42 | .Bd -literal -offset indent -compact | |
43 | O_RDONLY open for reading only | |
44 | O_WRONLY open for writing only | |
45 | O_RDWR open for reading and writing | |
dd4ea981 | 46 | O_NONBLOCK do not block on open |
931b8415 CL |
47 | O_APPEND append on each write |
48 | O_CREAT create file if it does not exist | |
49 | O_TRUNC truncate size to 0 | |
50 | O_EXCL error if create and file exists | |
dd4ea981 KM |
51 | O_SHLOCK atomically obtain a shared lock |
52 | O_EXLOCK atomically obtain an exclusive lock | |
931b8415 CL |
53 | .Ed |
54 | .Pp | |
55 | Opening a file with | |
56 | .Dv O_APPEND | |
57 | set causes each write on the file | |
58 | to be appended to the end. If | |
59 | .Dv O_TRUNC | |
60 | is specified and the | |
87d6e244 | 61 | file exists, the file is truncated to zero length. |
931b8415 CL |
62 | If |
63 | .Dv O_EXCL | |
64 | is set with | |
65 | .Dv O_CREAT | |
66 | and the file already | |
67 | exists, | |
68 | .Fn open | |
69 | returns an error. This may be used to | |
87d6e244 | 70 | implement a simple exclusive access locking mechanism. |
931b8415 CL |
71 | If |
72 | .Dv O_EXCL | |
73 | is set and the last component of the pathname is | |
74 | a symbolic link, | |
75 | .Fn open | |
76 | will fail even if the symbolic | |
3e716fce | 77 | link points to a non-existent name. |
931b8415 | 78 | If the |
dd4ea981 | 79 | .Dv O_NONBLOCK |
931b8415 CL |
80 | flag is specified and the |
81 | .Fn open | |
82 | call would result | |
83 | in the process being blocked for some reason (e.g., waiting for | |
84 | carrier on a dialup line), | |
85 | .Fn open | |
86 | returns immediately. | |
87 | The first time the process attempts to perform I/O on the open | |
87d6e244 | 88 | file it will block (not currently implemented). |
931b8415 | 89 | .Pp |
dd4ea981 KM |
90 | When opening a file, a lock with |
91 | .Xr flock 2 | |
92 | semantics can be obtained by setting | |
93 | .Dv O_SHLOCK | |
94 | for a shared lock, or | |
95 | .Dv O_EXLOCK | |
96 | for an exclusive lock. | |
97 | If creating a file with | |
98 | .Dv O_CREAT , | |
99 | the request for the lock will never fail | |
100 | (provided that the underlying filesystem supports locking). | |
101 | .Pp | |
931b8415 CL |
102 | If successful, |
103 | .Fn open | |
e18fd532 KB |
104 | returns a non-negative integer, termed a file descriptor. |
105 | It returns -1 on failure. | |
87d6e244 KM |
106 | The file pointer used to mark the current position within the |
107 | file is set to the beginning of the file. | |
931b8415 | 108 | .Pp |
e18fd532 KB |
109 | When a new file is created it is given the group of the directory |
110 | which contains it. | |
111 | .Pp | |
87d6e244 | 112 | The new descriptor is set to remain open across |
931b8415 | 113 | .Xr execve |
87d6e244 | 114 | system calls; see |
931b8415 CL |
115 | .Xr close 2 |
116 | and | |
117 | .Xr fcntl 2 . | |
118 | .Pp | |
8f02ec0d MK |
119 | The system imposes a limit on the number of file descriptors |
120 | open simultaneously by one process. | |
931b8415 | 121 | .Xr Getdtablesize 2 |
8f02ec0d | 122 | returns the current system limit. |
931b8415 CL |
123 | .Sh ERRORS |
124 | The named file is opened unless: | |
125 | .Bl -tag -width Er | |
126 | .It Bq Er ENOTDIR | |
87d6e244 | 127 | A component of the path prefix is not a directory. |
931b8415 | 128 | .It Bq Er ENAMETOOLONG |
b5984ffe KM |
129 | A component of a pathname exceeded 255 characters, |
130 | or an entire path name exceeded 1023 characters. | |
931b8415 CL |
131 | .It Bq Er ENOENT |
132 | .Dv O_CREAT | |
133 | is not set and the named file does not exist. | |
134 | .It Bq Er ENOENT | |
fd690c8b | 135 | A component of the path name that must exist does not exist. |
931b8415 | 136 | .It Bq Er EACCES |
b5984ffe | 137 | Search permission is denied for a component of the path prefix. |
931b8415 | 138 | .It Bq Er EACCES |
87d6e244 | 139 | The required permissions (for reading and/or writing) |
931b8415 CL |
140 | are denied for the given flags. |
141 | .It Bq Er EACCES | |
142 | .Dv O_CREAT | |
143 | is specified, | |
fd690c8b KM |
144 | the file does not exist, |
145 | and the directory in which it is to be created | |
146 | does not permit writing. | |
931b8415 | 147 | .It Bq Er ELOOP |
b5984ffe | 148 | Too many symbolic links were encountered in translating the pathname. |
931b8415 | 149 | .It Bq Er EISDIR |
87d6e244 | 150 | The named file is a directory, and the arguments specify |
931b8415 CL |
151 | it is to be opened for writing. |
152 | .It Bq Er EROFS | |
87d6e244 KM |
153 | The named file resides on a read-only file system, |
154 | and the file is to be modified. | |
931b8415 CL |
155 | .It Bq Er EMFILE |
156 | The process has already reached its limit for open file descriptors. | |
157 | .It Bq Er ENFILE | |
fd690c8b | 158 | The system file table is full. |
931b8415 | 159 | .It Bq Er ENXIO |
87d6e244 KM |
160 | The named file is a character special or block |
161 | special file, and the device associated with this special file | |
162 | does not exist. | |
dd4ea981 KM |
163 | .It Bq Er EINTR |
164 | The | |
165 | .Nm | |
166 | operation was interrupted by a signal. | |
167 | .It Bq Er EOPNOTSUPP | |
168 | .Dv O_SHLOCK | |
169 | or | |
170 | .Dv O_EXLOCK | |
171 | is specified but the underlying filesystem does not support locking. | |
931b8415 CL |
172 | .It Bq Er ENOSPC |
173 | .Dv O_CREAT | |
174 | is specified, | |
fd690c8b KM |
175 | the file does not exist, |
176 | and the directory in which the entry for the new file is being placed | |
177 | cannot be extended because there is no space left on the file | |
178 | system containing the directory. | |
931b8415 CL |
179 | .It Bq Er ENOSPC |
180 | .Dv O_CREAT | |
181 | is specified, | |
fd690c8b KM |
182 | the file does not exist, |
183 | and there are no free inodes on the file system on which the | |
184 | file is being created. | |
931b8415 CL |
185 | .It Bq Er EDQUOT |
186 | .Dv O_CREAT | |
187 | is specified, | |
fd690c8b | 188 | the file does not exist, |
dd4ea981 | 189 | and the directory in which the entry for the new file |
fd690c8b KM |
190 | is being placed cannot be extended because the |
191 | user's quota of disk blocks on the file system | |
192 | containing the directory has been exhausted. | |
931b8415 CL |
193 | .It Bq Er EDQUOT |
194 | .Dv O_CREAT | |
195 | is specified, | |
fd690c8b KM |
196 | the file does not exist, |
197 | and the user's quota of inodes on the file system on | |
198 | which the file is being created has been exhausted. | |
931b8415 | 199 | .It Bq Er EIO |
b5984ffe | 200 | An I/O error occurred while making the directory entry or |
931b8415 CL |
201 | allocating the inode for |
202 | .Dv O_CREAT . | |
203 | .It Bq Er ETXTBSY | |
87d6e244 | 204 | The file is a pure procedure (shared text) file that is being |
931b8415 CL |
205 | executed and the |
206 | .Fn open | |
207 | call requests write access. | |
208 | .It Bq Er EFAULT | |
209 | .Fa Path | |
87d6e244 | 210 | points outside the process's allocated address space. |
931b8415 CL |
211 | .It Bq Er EEXIST |
212 | .Dv O_CREAT | |
213 | and | |
214 | .Dv O_EXCL | |
215 | were specified and the file exists. | |
216 | .It Bq Er EOPNOTSUPP | |
87d6e244 | 217 | An attempt was made to open a socket (not currently implemented). |
931b8415 CL |
218 | .El |
219 | .Sh SEE ALSO | |
220 | .Xr chmod 2 , | |
221 | .Xr close 2 , | |
222 | .Xr dup 2 , | |
223 | .Xr getdtablesize 2 , | |
224 | .Xr lseek 2 , | |
225 | .Xr read 2 , | |
226 | .Xr write 2 , | |
227 | .Xr umask 2 | |
228 | .Sh HISTORY | |
229 | An | |
230 | .Nm | |
231 | function call appeared in Version 6 AT&T UNIX. |