open.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.