topen.9p - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
topen.9p (4834B)
---
1 .TH OPEN 9P
2 .SH NAME
3 open, create \- prepare a fid for I/O on an existing or new file
4 .SH SYNOPSIS
5 .ta \w'\fLTcreate 'u
6 .IR size [4]
7 .B Topen
8 .IR tag [2]
9 .IR fid [4]
10 .IR mode [1]
11 .br
12 .IR size [4]
13 .B Ropen
14 .IR tag [2]
15 .IR qid [13]
16 .IR iounit [4]
17 .PP
18 .IR size [4]
19 .B Tcreate
20 .IR tag [2]
21 .IR fid [4]
22 .IR name [ s ]
23 .IR perm [4]
24 .IR mode [1]
25 .br
26 .IR size [4]
27 .B Rcreate
28 .IR tag [2]
29 .IR qid [13]
30 .IR iounit [4]
31 .SH DESCRIPTION
32 The
33 .B open
34 request asks the file server to check permissions and
35 prepare a fid for I/O with subsequent
36 .B read
37 and
38 .B write
39 messages.
40 The
41 .I mode
42 field determines the type of I/O:
43 0
44 (called
45 .BR OREAD
46 in
47 .BR <libc.h> ),
48 1
49 .RB ( OWRITE ),
50 2
51 .RB ( ORDWR ),
52 and 3
53 .RB ( OEXEC )
54 mean
55 .I
56 read access, write access, read and write access,
57 and
58 .I
59 execute access,
60 to be checked against the permissions for the file.
61 In addition, if
62 .I mode
63 has the
64 .B OTRUNC
65 .RB ( 0x10 )
66 bit set,
67 the file is to be truncated, which requires write permission
68 (if
69 the file is append-only, and permission is granted, the
70 .B open
71 succeeds but the file will not be truncated);
72 if the
73 .I mode
74 has the
75 .B ORCLOSE
76 .RB ( 0x40 )
77 bit set, the file is to be removed when the fid
78 is clunked, which requires permission to remove the file from its directory.
79 All other bits in
80 .I mode
81 should be zero.
82 It is illegal to write a directory, truncate it, or attempt to remove it on close.
83 If the file is marked for exclusive use (see
84 .IR stat (9P)),
85 only one client can have the file open at any time.
86 That is, after such a file has been opened,
87 further opens will fail until
88 .I fid
89 has been clunked.
90 All these permissions are checked at the time of the
91 .B open
92 request; subsequent changes to the permissions of files do not affect
93 the ability to read, write, or remove an open file.
94 .PP
95 The
96 .B create
97 request asks the file server to create a new file
98 with the
99 .I name
100 supplied, in the directory
101 .RI ( dir )
102 represented by
103 .IR fid ,
104 and requires write permission in the directory.
105 The owner of the file is the implied user id of the request,
106 the group of the file is the same as
107 .IR dir ,
108 and the permissions are the value of
109 .ce
110 .B "perm & (~0666 | (dir.perm & 0666))"
111 if a regular file is being created and
112 .ce
113 .B "perm & (~0777 | (dir.perm & 0777))"
114 if a directory is being created.
115 This means, for example, that if the
116 .B create
117 allows read permission to others, but the containing directory
118 does not, then the created file will not allow others to read the file.
119 .PP
120 Finally, the newly created file is opened according to
121 .IR mode ,
122 and
123 .I fid
124 will represent the newly opened file.
125 .I Mode
126 is not checked against the permissions in
127 .IR perm .
128 The
129 .I qid
130 for the new file is returned with the
131 .B create
132 reply message.
133 .PP
134 Directories are created by setting the
135 .B DMDIR
136 bit
137 .RB ( 0x80000000 )
138 in the
139 .IR perm .
140 .PP
141 The names
142 .B .
143 and
144 .B ..
145 are special; it is illegal to create files with these names.
146 .PP
147 It is an error for either of these messages if the fid
148 is already the product of a successful
149 .B open
150 or
151 .B create
152 message.
153 .PP
154 An attempt to
155 .B create
156 a file in a directory where the given
157 .I name
158 already exists will be rejected;
159 in this case, the
160 .I fscreate
161 call
162 (see
163 .MR 9pclient (3) )
164 uses
165 .B open
166 with truncation.
167 The algorithm used by the
168 .IR create
169 system call
170 is:
171 first walk to the directory to contain the file.
172 If that fails, return an error.
173 Next
174 .B walk
175 to the specified file.
176 If the
177 .B walk
178 succeeds, send a request to
179 .B open
180 and truncate the file and return the result, successful or not.
181 If the
182 .B walk
183 fails, send a create message.
184 If that fails, it may be because the file was created by another
185 process after the previous walk failed, so (once) try the
186 .B walk
187 and
188 .B open
189 again.
190 .\" .PP
191 .\" For the behavior of
192 .\" .I create
193 .\" on a union directory, see
194 .\" .IR bind (2).
195 .\" .PP
196 .\" The
197 .\" .B iounit
198 .\" field returned by
199 .\" .B open
200 .\" and
201 .\" .B create
202 .\" may be zero.
203 .\" If it is not, it is the maximum number of bytes that are guaranteed to
204 .\" be read from or written to the file without breaking the I/O transfer
205 .\" into multiple 9P messages; see
206 .\" .IR read (9P).
207 .SH ENTRY POINTS
208 .I Fsopen
209 and
210 .I fscreate
211 (see
212 .MR 9pclient (3) )
213 both generate
214 .B open
215 messages; only
216 .I fscreate
217 generates a
218 .B create
219 message.
220 The
221 .B iounit
222 associated with an open file may be discovered by calling
223 .IR fsiounit .
224 .PP
225 For programs that need atomic file creation, without the race
226 that exists in the
227 .B open-create
228 sequence described above,
229 .IR fscreate
230 does the following.
231 If the
232 .B OEXCL
233 .RB ( 0x1000 )
234 bit is set in the
235 .I mode
236 for a
237 .I fscreate
238 call,
239 the
240 .B open
241 message is not sent; the kernel issues only the
242 .BR create .
243 Thus, if the file exists,
244 .I fscreate
245 will draw an error, but if it doesn't and the
246 .I fscreate
247 call succeeds, the process issuing the
248 .I fscreate
249 is guaranteed to be the one that created the file.