0intro 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602
  1. .TH INTRO 5
  2. .SH NAME
  3. intro \- introduction to the Plan 9 File Protocol, 9P
  4. .SH SYNOPSIS
  5. .B #include <fcall.h>
  6. .SH DESCRIPTION
  7. A Plan 9
  8. .I server
  9. is an agent that provides one or more hierarchical file systems
  10. \(em file trees \(em
  11. that may be accessed by Plan 9 processes.
  12. A server responds to requests by
  13. .I clients
  14. to navigate the hierarchy,
  15. and to create, remove, read, and write files.
  16. The prototypical server is a separate machine that stores
  17. large numbers of user files on permanent media;
  18. such a machine is called, somewhat confusingly, a
  19. .I file
  20. .IR server .
  21. Another possibility for a server is to synthesize
  22. files on demand, perhaps based on information on data structures
  23. inside the kernel; the
  24. .IR proc (3)
  25. .I kernel device
  26. is a part of the Plan 9 kernel that does this.
  27. User programs can also act as servers.
  28. .PP
  29. A
  30. .I connection
  31. to a server is a bidirectional communication path from the client to the server.
  32. There may be a single client or
  33. multiple clients sharing the same connection.
  34. A server's file tree is attached to a process
  35. group's name space by
  36. .IR bind (2)
  37. and
  38. .I mount
  39. calls;
  40. see
  41. .IR intro (2).
  42. Processes in the group are then clients
  43. of the server:
  44. system calls operating on files are translated into requests
  45. and responses transmitted on the connection to the appropriate service.
  46. .PP
  47. The
  48. .IR "Plan 9 File Protocol" ,
  49. 9P, is used for messages between
  50. .I clients
  51. and
  52. .IR servers .
  53. A client transmits
  54. .I requests
  55. .RI ( T-messages )
  56. to a server, which
  57. subsequently returns
  58. .I replies
  59. .RI ( R-messages )
  60. to the client.
  61. The combined acts of transmitting (receiving) a request of a particular type,
  62. and receiving (transmitting)
  63. its reply is called a
  64. .I transaction
  65. of that type.
  66. .PP
  67. Each message consists of a sequence of bytes.
  68. Two-, four-, and eight-byte fields hold unsigned
  69. integers represented in little-endian order
  70. (least significant byte first).
  71. Data items of larger or variable lengths are represented
  72. by a two-byte field specifying a count,
  73. .IR n ,
  74. followed by
  75. .I n
  76. bytes of data.
  77. Text strings are represented this way,
  78. with the text itself stored as a UTF-8
  79. encoded sequence of Unicode characters (see
  80. .IR utf (6)).
  81. Text strings in 9P messages are not
  82. .SM NUL\c
  83. -terminated:
  84. .I n
  85. counts the bytes of UTF-8 data, which include no final zero byte.
  86. The
  87. .SM NUL
  88. character is illegal in all text strings in 9P, and is therefore
  89. excluded from file names, user names, and so on.
  90. .PP
  91. Each 9P message begins with a four-byte size field
  92. specifying the length in bytes of the complete message including
  93. the four bytes of the size field itself.
  94. The next byte is the message type, one of the constants
  95. in the enumeration in the include file
  96. .BR <fcall.h> .
  97. The next two bytes are an identifying
  98. .IR tag ,
  99. described below.
  100. The remaining bytes are parameters of different sizes.
  101. In the message descriptions, the number of bytes in a field
  102. is given in brackets after the field name.
  103. The notation
  104. .IR parameter [ n ]
  105. where
  106. .I n
  107. is not a constant represents a variable-length parameter:
  108. .IR n [2]
  109. followed by
  110. .I n
  111. bytes of data forming the
  112. .IR parameter .
  113. The notation
  114. .IR string [ s ]
  115. (using a literal
  116. .I s
  117. character)
  118. is shorthand for
  119. .IR s [2]
  120. followed by
  121. .I s
  122. bytes of UTF-8 text.
  123. (Systems may choose to reduce the set of legal characters
  124. to reduce syntactic problems,
  125. for example to remove slashes from name components,
  126. but the protocol has no such restriction.
  127. Plan 9 names may contain any printable character (that is, any character
  128. outside hexadecimal 00-1F and 80-9F)
  129. except slash.)
  130. Messages are transported in byte form to allow for machine independence;
  131. .IR fcall (2)
  132. describes routines that convert to and from this form into a machine-dependent
  133. C structure.
  134. .SH MESSAGES
  135. .ta \w'\fLTsession 'u
  136. .IP
  137. .ne 2v
  138. .IR size [4]
  139. .B Tversion
  140. .IR tag [2]
  141. .IR msize [4]
  142. .IR version [ s ]
  143. .br
  144. .IR size [4]
  145. .B Rversion
  146. .IR tag [2]
  147. .IR msize [4]
  148. .IR version [ s ]
  149. .IP
  150. .ne 2v
  151. .IR size [4]
  152. .B Tauth
  153. .IR tag [2]
  154. .IR afid [4]
  155. .IR uname [ s ]
  156. .IR aname [ s ]
  157. .br
  158. .br
  159. .IR size [4]
  160. .B Rauth
  161. .IR tag [2]
  162. .IR aqid [13]
  163. .IP
  164. .ne 2v
  165. .IR size [4]
  166. .B Rerror
  167. .IR tag [2]
  168. .IR ename [ s ]
  169. .IP
  170. .ne 2v
  171. .IR size [4]
  172. .B Tflush
  173. .IR tag [2]
  174. .IR oldtag [2]
  175. .br
  176. .IR size [4]
  177. .B Rflush
  178. .IR tag [2]
  179. .IP
  180. .ne 2v
  181. .IR size [4]
  182. .B Tattach
  183. .IR tag [2]
  184. .IR fid [4]
  185. .IR afid [4]
  186. .IR uname [ s ]
  187. .IR aname [ s ]
  188. .br
  189. .IR size [4]
  190. .B Rattach
  191. .IR tag [2]
  192. .IR qid [13]
  193. .IP
  194. .ne 2v
  195. .IR size [4]
  196. .B Twalk
  197. .IR tag [2]
  198. .IR fid [4]
  199. .IR newfid [4]
  200. .IR nwname [2]
  201. .IR nwname *( wname [ s ])
  202. .br
  203. .IR size [4]
  204. .B Rwalk
  205. .IR tag [2]
  206. .IR nwqid [2]
  207. .IR nwqid *( wqid [13])
  208. .IP
  209. .ne 2v
  210. .IR size [4]
  211. .B Topen
  212. .IR tag [2]
  213. .IR fid [4]
  214. .IR mode [1]
  215. .br
  216. .IR size [4]
  217. .B Ropen
  218. .IR tag [2]
  219. .IR qid [13]
  220. .IR iounit [4]
  221. .IP
  222. .ne 2v
  223. .IR size [4]
  224. .B Tcreate
  225. .IR tag [2]
  226. .IR fid [4]
  227. .IR name [ s ]
  228. .IR perm [4]
  229. .IR mode [1]
  230. .br
  231. .IR size [4]
  232. .B Rcreate
  233. .IR tag [2]
  234. .IR qid [13]
  235. .IR iounit [4]
  236. .IP
  237. .ne 2v
  238. .IR size [4]
  239. .B Tread
  240. .IR tag [2]
  241. .IR fid [4]
  242. .IR offset [8]
  243. .IR count [4]
  244. .br
  245. .IR size [4]
  246. .B Rread
  247. .IR tag [2]
  248. .IR count [4]
  249. .IR data [ count ]
  250. .IP
  251. .ne 2v
  252. .IR size [4]
  253. .B Twrite
  254. .IR tag [2]
  255. .IR fid [4]
  256. .IR offset [8]
  257. .IR count [4]
  258. .IR data [ count ]
  259. .br
  260. .IR size [4]
  261. .B Rwrite
  262. .IR tag [2]
  263. .IR count [4]
  264. .IP
  265. .ne 2v
  266. .IR size [4]
  267. .B Tclunk
  268. .IR tag [2]
  269. .IR fid [4]
  270. .br
  271. .IR size [4]
  272. .B Rclunk
  273. .IR tag [2]
  274. .IP
  275. .ne 2v
  276. .IR size [4]
  277. .B Tremove
  278. .IR tag [2]
  279. .IR fid [4]
  280. .br
  281. .IR size [4]
  282. .B Rremove
  283. .IR tag [2]
  284. .IP
  285. .ne 2v
  286. .IR size [4]
  287. .B Tstat
  288. .IR tag [2]
  289. .IR fid [4]
  290. .br
  291. .IR size [4]
  292. .B Rstat
  293. .IR tag [2]
  294. .IR stat [ n ]
  295. .IP
  296. .ne 2v
  297. .IR size [4]
  298. .B Twstat
  299. .IR tag [2]
  300. .IR fid [4]
  301. .IR stat [ n ]
  302. .br
  303. .IR size [4]
  304. .B Rwstat
  305. .IR tag [2]
  306. .PP
  307. Each T-message has a
  308. .I tag
  309. field, chosen and used by the client to identify the message.
  310. The reply to the message will have the same tag.
  311. Clients must arrange that no two outstanding messages
  312. on the same connection have the same tag.
  313. An exception is the tag
  314. .BR NOTAG ,
  315. defined as
  316. .B (ushort)~0
  317. in
  318. .BR <fcall.h> :
  319. the client can use it, when establishing a connection,
  320. to
  321. override tag matching in
  322. .B version
  323. messages.
  324. .PP
  325. The type of an R-message will either be one greater than the type
  326. of the corresponding T-message or
  327. .BR Rerror ,
  328. indicating that the request failed.
  329. In the latter case, the
  330. .I ename
  331. field contains a string describing the reason for failure.
  332. .PP
  333. The
  334. .B version
  335. message identifies the version of the protocol and indicates
  336. the maximum message size the system is prepared to handle.
  337. It also initializes the connection and
  338. aborts all outstanding I/O on the connection.
  339. The set of messages between
  340. .B version
  341. requests is called a
  342. .IR session .
  343. .PP
  344. Most T-messages contain a
  345. .IR fid ,
  346. a 32-bit unsigned integer that the client uses to identify
  347. a ``current file'' on the server.
  348. Fids are somewhat like file descriptors in a user process,
  349. but they are not restricted to files open for I/O:
  350. directories being examined, files being accessed by
  351. .IR stat (2)
  352. calls, and so on \(em all files being manipulated by the operating
  353. system \(em are identified by fids.
  354. Fids are chosen by the client.
  355. All requests on a connection share the same fid space;
  356. when several clients share a connection,
  357. the agent managing the sharing must arrange
  358. that no two clients choose the same fid.
  359. .PP
  360. The fid supplied in an
  361. .B attach
  362. message
  363. will be taken by the server to refer to the root of the served file tree.
  364. The
  365. .B attach
  366. identifies the user
  367. to the server and may specify a particular file tree served
  368. by the server (for those that supply more than one).
  369. .PP
  370. Permission to attach to the service is proven by providing a special fid, called
  371. .BR afid ,
  372. in the
  373. .B attach
  374. message. This
  375. .B afid
  376. is established by exchanging
  377. .B auth
  378. messages and subsequently manipulated using
  379. .B read
  380. and
  381. .B write
  382. messages to exchange authentication information not defined explicitly by 9P.
  383. Once the authentication protocol is complete, the
  384. .B afid
  385. is presented in the
  386. .B attach
  387. to permit the user to access the service.
  388. .PP
  389. A
  390. .B walk
  391. message causes the server to change the current file associated
  392. with a fid to be a file in the directory that is the old current file, or one of
  393. its subdirectories.
  394. .B Walk
  395. returns a new fid that refers to the resulting file.
  396. Usually, a client maintains a fid for the root,
  397. and navigates by
  398. .B walks
  399. from the root fid.
  400. .PP
  401. A client can send multiple T-messages without waiting for the corresponding
  402. R-messages, but all outstanding T-messages must specify different tags.
  403. The server may delay the response to a request
  404. and respond to later ones;
  405. this is sometimes necessary, for example when the client reads
  406. from a file that the server synthesizes from external events
  407. such as keyboard characters.
  408. .PP
  409. Replies (R-messages) to
  410. .BR auth ,
  411. .BR attach ,
  412. .BR walk ,
  413. .BR open ,
  414. and
  415. .B create
  416. requests convey a
  417. .I qid
  418. field back to the client.
  419. The qid represents the server's unique identification for the
  420. file being accessed:
  421. two files on the same server hierarchy are the same if and only if their qids
  422. are the same.
  423. (The client may have multiple fids pointing to a single file on a server
  424. and hence having a single qid.)
  425. The thirteen-byte qid fields hold a one-byte type,
  426. specifying whether the file is a directory, append-only file, etc.,
  427. and two unsigned integers:
  428. first the four-byte qid
  429. .IR version ,
  430. then the eight-byte qid
  431. .IR path .
  432. The path is an integer unique among all files in the hierarchy.
  433. If a file is deleted and recreated with the
  434. same name in the same directory, the old and new path components of the qids
  435. should be different.
  436. The version is a version number for a file;
  437. typically, it is incremented every time the file is modified.
  438. .PP
  439. An existing file can be
  440. .BR opened ,
  441. or a new file may be
  442. .B created
  443. in the current (directory) file.
  444. I/O of a given number of bytes
  445. at a given offset
  446. on an open file is done by
  447. .B read
  448. and
  449. .BR write .
  450. .PP
  451. A client should
  452. .B clunk
  453. any fid that is no longer needed.
  454. The
  455. .B remove
  456. transaction deletes files.
  457. .PP
  458. The
  459. .B stat
  460. transaction retrieves information about the file.
  461. The
  462. .I stat
  463. field in the reply includes the file's
  464. name,
  465. access permissions (read, write and execute for owner, group and public),
  466. access and modification times, and
  467. owner and group identifications
  468. (see
  469. .IR stat (2)).
  470. The owner and group identifications are textual names.
  471. The
  472. .B wstat
  473. transaction allows some of a file's properties
  474. to be changed.
  475. .PP
  476. A request can be aborted with a
  477. flush
  478. request.
  479. When a server receives a
  480. .BR Tflush ,
  481. it should not reply to the message with tag
  482. .I oldtag
  483. (unless it has already replied),
  484. and it should immediately send an
  485. .BR Rflush .
  486. The client must wait
  487. until it gets the
  488. .B Rflush
  489. (even if the reply to the original message arrives in the interim),
  490. at which point
  491. .I oldtag
  492. may be reused.
  493. .PP
  494. Because the message size is negotiable and some elements of the
  495. protocol are variable length, it is possible (although unlikely) to have
  496. a situation where a valid message is too large to fit within the negotiated size.
  497. For example, a very long file name may cause a
  498. .B Rstat
  499. of the file or
  500. .B Rread
  501. of its directory entry to be too large to send.
  502. In most such cases, the server should generate an error rather than
  503. modify the data to fit, such as by truncating the file name.
  504. The exception is that a long error string in an
  505. .B Rerror
  506. message should be truncated if necessary, since the string is only
  507. advisory and in some sense arbitrary.
  508. .PP
  509. Most programs do not see the 9P protocol directly; instead calls to library
  510. routines that access files are
  511. translated by the mount driver,
  512. .IR mnt (3),
  513. into 9P messages.
  514. .SH DIRECTORIES
  515. Directories are created by
  516. .B create
  517. with
  518. .B DMDIR
  519. set in the permissions argument (see
  520. .IR stat (5)).
  521. The members of a directory can be found with
  522. .IR read (5).
  523. All directories must support
  524. .B walks
  525. to the directory
  526. .B ..
  527. (dot-dot)
  528. meaning parent directory, although by convention directories
  529. contain no explicit entry for
  530. .B ..
  531. or
  532. .B .
  533. (dot).
  534. The parent of the root directory of a server's tree is itself.
  535. .SH "ACCESS PERMISSIONS"
  536. Each file server maintains a set of user and group names.
  537. Each user can be a member of any number of groups.
  538. Each group has a
  539. .I group leader
  540. who has special privileges (see
  541. .IR stat (5)
  542. and
  543. .IR users (6)).
  544. Every file request has an implicit user id (copied from the original
  545. .BR attach )
  546. and an implicit set of groups (every group of which the user is a member).
  547. .PP
  548. Each file has an associated
  549. .I owner
  550. and
  551. .I group
  552. id and
  553. three sets of permissions:
  554. those of the owner, those of the group, and those of ``other'' users.
  555. When the owner attempts to do something to a file, the owner, group,
  556. and other permissions are consulted, and if any of them grant
  557. the requested permission, the operation is allowed.
  558. For someone who is not the owner, but is a member of the file's group,
  559. the group and other permissions are consulted.
  560. For everyone else, the other permissions are used.
  561. Each set of permissions says whether reading is allowed,
  562. whether writing is allowed, and whether executing is allowed.
  563. A
  564. .B walk
  565. in a directory is regarded as executing the directory,
  566. not reading it.
  567. Permissions are kept in the low-order bits of the file
  568. .IR mode :
  569. owner read/write/execute permission represented as 1 in bits 8, 7, and 6
  570. respectively (using 0 to number the low order).
  571. The group permissions are in bits 5, 4, and 3,
  572. and the other permissions are in bits 2, 1, and 0.
  573. .PP
  574. The file
  575. .I mode
  576. contains some additional attributes besides the permissions.
  577. If bit 31
  578. .RB ( DMDIR )
  579. is set, the file is a directory;
  580. if bit 30
  581. .RB ( DMAPPEND )
  582. is set, the file is append-only (offset is ignored in writes);
  583. if bit 29
  584. .RB ( DMEXCL )
  585. is set, the file is exclusive-use (only one client may have it
  586. open at a time);
  587. if bit 27
  588. .RB ( DMAUTH )
  589. is set, the file is an authentication file established by
  590. .B auth
  591. messages.
  592. (Bit 28 is skipped for historical reasons.)
  593. These bits are reproduced, from the top bit down, in the type byte of the Qid:
  594. .BR QTDIR ,
  595. .BR QTAPPEND ,
  596. .BR QTEXCL ,
  597. and (skipping one bit)
  598. .BR QTAUTH .
  599. The name
  600. .BR QTFILE ,
  601. defined to be zero,
  602. identifies the value of the type for a plain file.