1
0

open 4.6 KB

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