n9p.ms 12 KB

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