sys/man/5/open

   1 .TH OPEN 5
   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 (5)),
  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 create
 161 system call
 162 (see
 163 .IR open (2))
 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 (5).
 207 .SH ENTRY POINTS
 208 .I Open
 209 and
 210 .I create
 211 both generate
 212 .B open
 213 messages; only
 214 .I create
 215 generates a
 216 .B create
 217 message.
 218 The
 219 .B iounit
 220 associated with an open file may be discovered by calling
 221 .IR iounit (2).
 222 .PP
 223 For programs that need atomic file creation, without the race
 224 that exists in the
 225 .B open-create
 226 sequence described above,
 227 the kernel does the following.
 228 If the
 229 .B OEXCL
 230 .RB ( 0x1000 )
 231 bit is set in the
 232 .I mode
 233 for a
 234 .B create
 235 system call,
 236 the
 237 .B open
 238 message is not sent; the kernel issues only the
 239 .BR create .
 240 Thus, if the file exists,
 241 .B create
 242 will draw an error, but if it doesn't and the
 243 .B create
 244 system call succeeds, the process issuing the
 245 .B create
 246 is guaranteed to be the one that created the file.
 247