1 058b0118 2005-01-03 devnull .TH OPEN 9P
3 058b0118 2005-01-03 devnull open, create \- prepare a fid for I/O on an existing or new file
4 058b0118 2005-01-03 devnull .SH SYNOPSIS
5 058b0118 2005-01-03 devnull .ta \w'\fLTcreate 'u
6 058b0118 2005-01-03 devnull .IR size [4]
8 058b0118 2005-01-03 devnull .IR tag [2]
9 058b0118 2005-01-03 devnull .IR fid [4]
10 058b0118 2005-01-03 devnull .IR mode [1]
12 058b0118 2005-01-03 devnull .IR size [4]
14 058b0118 2005-01-03 devnull .IR tag [2]
15 058b0118 2005-01-03 devnull .IR qid [13]
16 058b0118 2005-01-03 devnull .IR iounit [4]
18 058b0118 2005-01-03 devnull .IR size [4]
19 058b0118 2005-01-03 devnull .B Tcreate
20 058b0118 2005-01-03 devnull .IR tag [2]
21 058b0118 2005-01-03 devnull .IR fid [4]
22 058b0118 2005-01-03 devnull .IR name [ s ]
23 058b0118 2005-01-03 devnull .IR perm [4]
24 058b0118 2005-01-03 devnull .IR mode [1]
26 058b0118 2005-01-03 devnull .IR size [4]
27 058b0118 2005-01-03 devnull .B Rcreate
28 058b0118 2005-01-03 devnull .IR tag [2]
29 058b0118 2005-01-03 devnull .IR qid [13]
30 058b0118 2005-01-03 devnull .IR iounit [4]
31 058b0118 2005-01-03 devnull .SH DESCRIPTION
34 058b0118 2005-01-03 devnull request asks the file server to check permissions and
35 058b0118 2005-01-03 devnull prepare a fid for I/O with subsequent
39 058b0118 2005-01-03 devnull messages.
42 058b0118 2005-01-03 devnull field determines the type of I/O:
45 058b0118 2005-01-03 devnull .BR OREAD
47 058b0118 2005-01-03 devnull .BR <libc.h> ),
49 058b0118 2005-01-03 devnull .RB ( OWRITE ),
51 058b0118 2005-01-03 devnull .RB ( ORDWR ),
53 058b0118 2005-01-03 devnull .RB ( OEXEC )
56 058b0118 2005-01-03 devnull read access, write access, read and write access,
59 058b0118 2005-01-03 devnull execute access,
60 058b0118 2005-01-03 devnull to be checked against the permissions for the file.
61 058b0118 2005-01-03 devnull In addition, if
64 058b0118 2005-01-03 devnull .B OTRUNC
65 058b0118 2005-01-03 devnull .RB ( 0x10 )
67 058b0118 2005-01-03 devnull the file is to be truncated, which requires write permission
69 058b0118 2005-01-03 devnull the file is append-only, and permission is granted, the
71 058b0118 2005-01-03 devnull succeeds but the file will not be truncated);
75 058b0118 2005-01-03 devnull .B ORCLOSE
76 058b0118 2005-01-03 devnull .RB ( 0x40 )
77 058b0118 2005-01-03 devnull bit set, the file is to be removed when the fid
78 058b0118 2005-01-03 devnull is clunked, which requires permission to remove the file from its directory.
79 058b0118 2005-01-03 devnull All other bits in
81 058b0118 2005-01-03 devnull should be zero.
82 058b0118 2005-01-03 devnull It is illegal to write a directory, truncate it, or attempt to remove it on close.
83 058b0118 2005-01-03 devnull If the file is marked for exclusive use (see
84 058b0118 2005-01-03 devnull .IR stat (9P)),
85 058b0118 2005-01-03 devnull only one client can have the file open at any time.
86 058b0118 2005-01-03 devnull That is, after such a file has been opened,
87 058b0118 2005-01-03 devnull further opens will fail until
89 058b0118 2005-01-03 devnull has been clunked.
90 058b0118 2005-01-03 devnull All these permissions are checked at the time of the
92 058b0118 2005-01-03 devnull request; subsequent changes to the permissions of files do not affect
93 058b0118 2005-01-03 devnull the ability to read, write, or remove an open file.
96 058b0118 2005-01-03 devnull .B create
97 058b0118 2005-01-03 devnull request asks the file server to create a new file
100 058b0118 2005-01-03 devnull supplied, in the directory
101 058b0118 2005-01-03 devnull .RI ( dir )
102 058b0118 2005-01-03 devnull represented by
103 058b0118 2005-01-03 devnull .IR fid ,
104 058b0118 2005-01-03 devnull and requires write permission in the directory.
105 058b0118 2005-01-03 devnull The owner of the file is the implied user id of the request,
106 058b0118 2005-01-03 devnull the group of the file is the same as
107 058b0118 2005-01-03 devnull .IR dir ,
108 058b0118 2005-01-03 devnull and the permissions are the value of
110 058b0118 2005-01-03 devnull .B "perm & (~0666 | (dir.perm & 0666))"
111 058b0118 2005-01-03 devnull if a regular file is being created and
113 058b0118 2005-01-03 devnull .B "perm & (~0777 | (dir.perm & 0777))"
114 058b0118 2005-01-03 devnull if a directory is being created.
115 058b0118 2005-01-03 devnull This means, for example, that if the
116 058b0118 2005-01-03 devnull .B create
117 058b0118 2005-01-03 devnull allows read permission to others, but the containing directory
118 058b0118 2005-01-03 devnull does not, then the created file will not allow others to read the file.
120 058b0118 2005-01-03 devnull Finally, the newly created file is opened according to
121 058b0118 2005-01-03 devnull .IR mode ,
124 058b0118 2005-01-03 devnull will represent the newly opened file.
126 058b0118 2005-01-03 devnull is not checked against the permissions in
127 058b0118 2005-01-03 devnull .IR perm .
130 058b0118 2005-01-03 devnull for the new file is returned with the
131 058b0118 2005-01-03 devnull .B create
132 058b0118 2005-01-03 devnull reply message.
134 058b0118 2005-01-03 devnull Directories are created by setting the
135 058b0118 2005-01-03 devnull .B DMDIR
137 058b0118 2005-01-03 devnull .RB ( 0x80000000 )
139 058b0118 2005-01-03 devnull .IR perm .
141 058b0118 2005-01-03 devnull The names
145 058b0118 2005-01-03 devnull are special; it is illegal to create files with these names.
147 058b0118 2005-01-03 devnull It is an error for either of these messages if the fid
148 058b0118 2005-01-03 devnull is already the product of a successful
151 058b0118 2005-01-03 devnull .B create
152 058b0118 2005-01-03 devnull message.
154 058b0118 2005-01-03 devnull An attempt to
155 058b0118 2005-01-03 devnull .B create
156 058b0118 2005-01-03 devnull a file in a directory where the given
158 058b0118 2005-01-03 devnull already exists will be rejected;
159 058b0118 2005-01-03 devnull in this case, the
160 058b0118 2005-01-03 devnull .I fscreate
163 36cd4c58 2021-01-30 crossd .MR 9pclient (3) )
166 058b0118 2005-01-03 devnull with truncation.
167 058b0118 2005-01-03 devnull The algorithm used by the
168 058b0118 2005-01-03 devnull .IR create
169 058b0118 2005-01-03 devnull system call
171 058b0118 2005-01-03 devnull first walk to the directory to contain the file.
172 058b0118 2005-01-03 devnull If that fails, return an error.
175 058b0118 2005-01-03 devnull to the specified file.
178 058b0118 2005-01-03 devnull succeeds, send a request to
180 058b0118 2005-01-03 devnull and truncate the file and return the result, successful or not.
183 058b0118 2005-01-03 devnull fails, send a create message.
184 058b0118 2005-01-03 devnull If that fails, it may be because the file was created by another
185 058b0118 2005-01-03 devnull process after the previous walk failed, so (once) try the
191 058b0118 2005-01-03 devnull .\" For the behavior of
192 058b0118 2005-01-03 devnull .\" .I create
193 058b0118 2005-01-03 devnull .\" on a union directory, see
194 058b0118 2005-01-03 devnull .\" .IR bind (2).
197 058b0118 2005-01-03 devnull .\" .B iounit
198 058b0118 2005-01-03 devnull .\" field returned by
199 058b0118 2005-01-03 devnull .\" .B open
201 058b0118 2005-01-03 devnull .\" .B create
202 058b0118 2005-01-03 devnull .\" may be zero.
203 058b0118 2005-01-03 devnull .\" If it is not, it is the maximum number of bytes that are guaranteed to
204 058b0118 2005-01-03 devnull .\" be read from or written to the file without breaking the I/O transfer
205 058b0118 2005-01-03 devnull .\" into multiple 9P messages; see
206 058b0118 2005-01-03 devnull .\" .IR read (9P).
207 058b0118 2005-01-03 devnull .SH ENTRY POINTS
208 058b0118 2005-01-03 devnull .I Fsopen
210 058b0118 2005-01-03 devnull .I fscreate
212 36cd4c58 2021-01-30 crossd .MR 9pclient (3) )
213 058b0118 2005-01-03 devnull both generate
215 058b0118 2005-01-03 devnull messages; only
216 058b0118 2005-01-03 devnull .I fscreate
217 058b0118 2005-01-03 devnull generates a
218 058b0118 2005-01-03 devnull .B create
219 058b0118 2005-01-03 devnull message.
221 058b0118 2005-01-03 devnull .B iounit
222 058b0118 2005-01-03 devnull associated with an open file may be discovered by calling
223 058b0118 2005-01-03 devnull .IR fsiounit .
225 058b0118 2005-01-03 devnull For programs that need atomic file creation, without the race
226 058b0118 2005-01-03 devnull that exists in the
227 058b0118 2005-01-03 devnull .B open-create
228 058b0118 2005-01-03 devnull sequence described above,
229 058b0118 2005-01-03 devnull .IR fscreate
230 058b0118 2005-01-03 devnull does the following.
232 058b0118 2005-01-03 devnull .B OEXCL
233 058b0118 2005-01-03 devnull .RB ( 0x1000 )
234 058b0118 2005-01-03 devnull bit is set in the
237 058b0118 2005-01-03 devnull .I fscreate
241 058b0118 2005-01-03 devnull message is not sent; the kernel issues only the
242 058b0118 2005-01-03 devnull .BR create .
243 058b0118 2005-01-03 devnull Thus, if the file exists,
244 058b0118 2005-01-03 devnull .I fscreate
245 058b0118 2005-01-03 devnull will draw an error, but if it doesn't and the
246 058b0118 2005-01-03 devnull .I fscreate
247 058b0118 2005-01-03 devnull call succeeds, the process issuing the
248 058b0118 2005-01-03 devnull .I fscreate
249 058b0118 2005-01-03 devnull is guaranteed to be the one that created the file.
