Changeset 9073 in project


Ignore:
Timestamp:
02/27/08 22:14:00 (12 years ago)
Author:
sjamaan
Message:

Update 9p docs to use the new chicken wiki syntax (procedure/constant/example)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/9p

    r8720 r9073  
    4747Before doing anything else, you must establish a connection with the server.  This is done with the {{9p:client-connect}} procedure.
    4848
    49     procedure: (9p:client-connect inport outport [user] [mountpoint])
     49<procedure>(9p:client-connect inport outport [user] [mountpoint])</procedure>
    5050
    5151The {{inport}} and {{outport}} arguments are the ports you use to communicate to the server.  The {{user}} argument is the name of the user that creates the files.  It defaults to the empty string.  There is no support for authentication, so the user name is simply used for newly created files on servers that support usernames (wmii doesn't, for example).  The {{mountpoint}} also defaults to the empty string, which selects the "default mount point" on the server.  If the server has multiple mountpoints it exports, you can select with this argument.
     
    5555You can use the following procedures to obtain some more information on the connection:
    5656
    57   procedure: (9p:connection-outport connection)
    58   procedure: (9p:connection-inport connection)
     57<procedure>(9p:connection-outport connection)</procedure>
     58<procedure>(9p:connection-inport connection)</procedure>
    5959
    6060Get back the underlying ports you passed to {{9p:client-connect}}.
    6161
    62   procedure: (9p:connection-message-size connection)
     62<procedure>(9p:connection-message-size connection)</procedure>
    6363
    6464The maximum size of a low-level message as negotiated in the connection handshake.  Not very useful unless you would like to write some custom messages.  This ''includes'' the size of the tag (2 bytes) and the message type (1 byte).
     
    6767===== 9p:client-disconnect
    6868
    69     procedure: (9p:client-disconnect connection)
     69<procedure>(9p:client-disconnect connection)</procedure>
    7070
    7171Disconnect from the server described by {{connection}}.  This clunks any fids that are still open (in Unix terms: closes any open file descriptors).
     
    7373===== 9p:connection?
    7474
    75    procedure: (9p:connection? object)
     75<procedure>(9p:connection? object)</procedure>
    7676
    7777You can verify an object is a connection to a 9p server with this predicate.
     
    8181===== 9p:with-output-to-file
    8282
    83   procedure: (9p:with-output-to-file connection file thunk)
     83<procedure>(9p:with-output-to-file connection file thunk)</procedure>
    8484
    8585Open {{file}} on the 9p connection {{connection}} and call {{thunk}} with the {{current-output-port}} set to a port that writes to the file. When the thunk finishes, the port is closed.
     
    8787===== 9p:call-with-output-file
    8888
    89   procedure: (9p:call-with-output-file connection file procedure)
     89<procedure>(9p:call-with-output-file connection file procedure)</procedure>
    9090
    9191Open {{file}} on the 9p connection {{connection}} and call {{procedure}} with an output-port that corresponds to the file. When the procedure finishes, the port is closed.  Procedure should accept one argument, the output-port.
     
    9393===== 9p:open-output-file
    9494
    95   procedure: (9p:open-output-file connection file [mode])
     95<procedure>(9p:open-output-file connection file [mode])</procedure>
    9696
    9797Create an output port that will write to the given {{file}} on the 9p connection {{connection}}.  If the file exists, it is truncated.  If it does not exist yet it will be created.  If the optional {{mode}} is given, it determines with what permissions the file will be created, if it is a new file.  See [[#Permission bits|below]] for the list of file permissions.
     
    101101===== 9p:with-input-from-file
    102102
    103   procedure: (9p:with-input-from-file connection file thunk)
     103<procedure>(9p:with-input-from-file connection file thunk)</procedure>
    104104
    105105Open {{file}} on the 9p connection {{connection}} and call {{thunk}} with the {{current-input-port}} set to a port that reads from the file. When the thunk finishes, the port is closed.
     
    107107===== 9p:call-with-input-file
    108108
    109   procedure: (9p:call-with-input-file connection file procedure)
     109<procedure>(9p:call-with-input-file connection file procedure)</procedure>
    110110
    111111Open {{file}} on the 9p connection {{connection}} and call {{procedure}} with an input-port that corresponds to the file. When the procedure finishes, the port is closed.  Procedure should accept one argument, the input-port.
     
    113113===== 9p:open-input-file
    114114
    115   procedure: (9p:open-input-file connection file)
     115<procedure>(9p:open-input-file connection file)</procedure>
    116116
    117117Create an input port that will read from the given {{file}} on the 9p connection {{connection}}.
     
    123123===== 9p:directory?
    124124
    125   procedure: (9p:directory? connection path)
     125<procedure>(9p:directory? connection path)</procedure>
    126126
    127127Returns {{#t}} if the given {{path}} on the {{connection}} is a directory, {{#f}} if not.
     
    129129===== 9p:create-directory
    130130
    131   procedure: (9p:create-directory connection path permissions)
     131<procedure>(9p:create-directory connection path permissions)</procedure>
    132132
    133133Create a directory on the {{connection}} with the given {{path}}.  It will have the specified {{permissions}}, see [[#Permission bits|below]] for the available permissions.
     
    135135===== 9p:directory
    136136
    137   procedure: (9p:directory connection directory [show-dotfiles?])
     137<procedure>(9p:directory connection directory [show-dotfiles?])</procedure>
    138138
    139139Returns a list with the contents of the {{directory}} on the {{connection}}. Files beginning with {{.}} are included only if {{show-dotfiles?}} is given and not #f.
     
    143143===== 9p:regular-file?
    144144
    145   procedure: (9p:regular-file? connection path)
     145<procedure>(9p:regular-file? connection path)</procedure>
    146146
    147147Returns {{#t}} if the given {{path}} on the {{connection}} is a regular file, {{#f}} if not.  9p does not support symlinks or FIFOs, so this is the same as {{(not (9p:directory? connection path))}}, even if the underlying FS is a Unix FS (the 9p egg currently does not (and probably will never) support [[http://v9fs.sourceforge.net/rfc/9p2000.u.html|9P2000.u]]).
     
    149149===== 9p:delete-file
    150150
    151   procedure: (9p:delete-file connection path)
     151<procedure>(9p:delete-file connection path)</procedure>
    152152
    153153Delete the file indicated by {{path}} on the {{connection}}. If the file does not exist or you do not have permission to delete it, an error is signaled.
     
    155155===== 9p:file-stat
    156156
    157   procedure: (9p:file-stat connection path)
     157<procedure>(9p:file-stat connection path)</procedure>
    158158
    159159Returns a 9-element vector which contains information about the file indicated by {{path}} on the {{connection}}.  It has the following contents:
     
    171171===== 9p:file-permissions
    172172
    173   procedure: (9p:file-permissions connection path)
     173<procedure>(9p:file-permissions connection path)</procedure>
    174174
    175175Returns the permissions of the file indicated by {{path}} on the {{connection}}. See [[#Permission bits|the permission bits section]] for a description of the possible bits.
     
    177177===== 9p:file-access-time
    178178
    179   procedure: (9p:file-access-time connection path)
     179<procedure>(9p:file-access-time connection path)</procedure>
    180180
    181181Returns the access time of the file indicated by {{path}} on the {{connection}}.  See the notes under [[9p:file-stat]].
     
    184184===== 9p:file-modification-time
    185185
    186   procedure: (9p:file-modification-time connection path)
     186<procedure>(9p:file-modification-time connection path)</procedure>
    187187
    188188Returns the modification time of the file indicated by {{path}} on the {{connection}}.  See the notes under [[9p:file-stat]].
     
    190190===== 9p:file-size
    191191
    192   procedure: (9p:file-size connection path)
     192<procedure>(9p:file-size connection path)</procedure>
    193193
    194194Returns the size, in bytes, of the file indicated by {{path}} on the {{connection}}.
     
    196196===== 9p:file-owner
    197197
    198   procedure: (9p:file-owner connection path)
     198<procedure>(9p:file-owner connection path)</procedure>
    199199
    200200Returns the name of the owner, as a string, of the file indicated by {{path}} on the {{connection}}.
     
    202202===== 9p:file-group
    203203
    204   procedure: (9p:file-group connection path)
     204<procedure>(9p:file-group connection path)</procedure>
    205205
    206206Returns the name of the owning group, as a string, of the file indicated by {{path}} on the {{connection}}.
     
    208208===== 9p:file-last-modified-by
    209209
    210   procedure: (9p:file-last-modified-by connection path)
     210<procedure>(9p:file-last-modified-by connection path)</procedure>
    211211
    212212Returns the name of the user, as a string, who last changed the file indicated by {{path}} on the {{connection}}.
     
    218218===== 9p:file-open
    219219
    220   procedure: (9p:file-open connection path mode)
     220<procedure>(9p:file-open connection path mode)</procedure>
    221221
    222222Opens the file indicated by {{path}} on the {{connection}} with the given {{mode}} and returns an opaque handle object which you can use for the other procedures described in this section.  For bit flags that the {{mode}} can take, see [[#Open flags|the open flags section]].
     
    224224===== 9p:file-create
    225225
    226   procedure: (9p:file-create connection path permissions mode)
     226<procedure>(9p:file-create connection path permissions mode)</procedure>
    227227
    228228Creates and opens the file indicated by {{path}} on the {{connection}} with the given {{permission}} and {{mode}} and returns an opaque handle object which you can use for the other procedures described in this section.  For bit flags that the {{mode}} can take, see [[#Open flags|the open flags section]].  For bit flags that the {{permission}} can take, see [[#Permission bits|the permission bits section]].
     
    231231===== 9p:file-close
    232232
    233   procedure: (9p:file-close handle)
     233<procedure>(9p:file-close handle)</procedure>
    234234
    235235Close the file indicated by {{handle}}.  It is not an error to close a file more than once.
     
    237237===== 9p:file-read
    238238
    239   procedure: (9p:file-read handle size)
     239<procedure>(9p:file-read handle size)</procedure>
    240240
    241241Read {{size}} bytes from the file with the given {{handle}}.  This procedure returns a list with two values: the buffer containing the data and the number of bytes read.
     
    243243===== 9p:file-write
    244244
    245   procedure: (9p:file-write handle buffer [size])
     245<procedure>(9p:file-write handle buffer [size])</procedure>
    246246
    247247Writes the contents of the string or bytevector {{buffer}} into the file with the given {{handle}}. If the optional argument {{size}} is given, then only the specified number of bytes are written.
     
    249249===== 9p:set-file-position!
    250250
    251   procedure: (9p:set-file-position! handle position [whence])
     251<procedure>(9p:set-file-position! handle position [whence])</procedure>
    252252
    253253Sets the current read/write position of {{handle}} to {{position}}, which should be an exact integer. {{whence}} specifies how the position is to interpreted and should be one of the values {{seek/set}}, {{seek/cur}} and {{seek/end}}. It defaults to {{seek/set}}.
     
    255255===== 9p:file-position
    256256
    257   procedure: (9p:file-position handle)
     257<procedure>(9p:file-position handle)</procedure>
    258258
    259259Returns the current read/write position of the {{handle}}.
     
    261261===== 9p:handle-stat
    262262
    263   procedure: (9p:handle-stat handle)
     263<procedure>(9p:handle-stat handle)</procedure>
    264264
    265265Just like [[9p:file-stat]], except it works on a handle instead of on a connection with a filename.
     
    271271====== 9p:path-walk
    272272
    273   procedure: (9p:path-walk connection path [starting-point])
     273<procedure>(9p:path-walk connection path [starting-point])</procedure>
    274274
    275275Obtain a handle for the file identified by {{path}} on the {{connection}} ''without opening it''.  You must not forget to clunk the handle's FID (or just call {{9p:file-close}} on the handle).  {{starting-point}} is an optional handle to a directory from which to start walking.  It defaults to the root directory (/).
     
    279279If all you need is a temporary handle/FID for a message to the server, you can use this utility procedure:
    280280
    281   procedure: (9p:with-handle-to connection path procedure)
     281<procedure>(9p:with-handle-to connection path procedure)</procedure>
    282282
    283283This will call {{procedure}} with one argument: a temporary handle which represents the {{path}} on the {{connection}}.  After the procedure returns, the handle will be deallocated and the FID will no longer be valid.  This returns whatever {{procedure}} returned.  If a condition is signaled, the handle will be deallocated properly and the FID clunked.
     
    287287The 9p-client library keeps track of FIDs for you so you do not have to remember numbers.  If you wish to send low-level messages yourself you should allocate and release FIDs through the library so your FIDs can't clash with the FIDs the library uses:
    288288
    289   procedure: (9p:alloc-handle connection)
     289<procedure>(9p:alloc-handle connection)</procedure>
    290290
    291291Allocate a handle on the connection.  This returns a handle object which you can query with the following procedures:
    292292
    293   procedure: (9p:handle-connection handle)
    294   procedure: (9p:handle-fid handle)
    295   procedure: (9p:handle-position handle)
    296   procedure: (9p:handle-iounit handle)
     293<procedure>(9p:handle-connection handle)</procedure>
     294<procedure>(9p:handle-fid handle)</procedure>
     295<procedure>(9p:handle-position handle)</procedure>
     296<procedure>(9p:handle-iounit handle)</procedure>
    297297
    298298The fid is allocated from an internal pool of free fids.  The position is initialized to 0, and used as an offset for read/write procedures (the server does not keep track of this for us in the 9p protocol).
     
    305305Once you are done with a handle, you must either pass the handle to [[9p:file-close]] (or just disconnect with [[9p:client-disconnect]]) or call {{9p:release-handle}}:
    306306
    307   procedure: (9p:release-handle handle)
     307<procedure>(9p:release-handle handle)</procedure>
    308308
    309309'''important''': be sure to clunk the handle's fid first.  {{9p:release-handle}} does ''not'' clunk the fid.
     
    314314A code using 9p-client normally never needs to send raw messages, but in case it does, there is one convenience procedure that does just a bit more than the raw [[9p-lolevel]] procedures do:
    315315
    316   procedure: (9p:request connection type . args)
     316<procedure>(9p:request connection type . args)</procedure>
    317317
    318318This creates a new {{9p:message}} object (see below) with a tag and the given {{type}}.  {{args}} are the message-contents.  It then sends this request to the server and awaits a response.  The response should match the request (a {{Twhatever}} should result in a {{Rwhatever}} message), or a condition of type {{(exn 9p-response-error)}} is signaled.  If the server returns an error (via {{Rerror}}), a condition of type {{(exn 9p-server-error)}} is signaled.  The response object (a 9p:message object) is returned.
     
    333333Messages are main concept in the 9p protocol.  They can be created as follows:
    334334
    335   procedure: (make-9p:message type tag contents)
     335<procedure>(make-9p:message type tag contents)</procedure>
    336336
    337337The type is a symbol, one of
     
    358358
    359359You can of course query and modify the message objects with the following procedures:
    360   procedure: (9p:message? object)
    361   procedure: (9p:message-type message)
    362   procedure: (9p:message-type-set! message new-type)
    363   procedure: (9p:message-tag message)
    364   procedure: (9p:message-tag-set! message new-tag)
    365   procedure: (9p:message-contents message)
    366   procedure: (9p:message-contents-set! message new-contents)
     360<procedure>(9p:message? object)</procedure>
     361<procedure>(9p:message-type message)</procedure>
     362<procedure>(9p:message-type-set! message new-type)</procedure>
     363<procedure>(9p:message-tag message)</procedure>
     364<procedure>(9p:message-tag-set! message new-tag)</procedure>
     365<procedure>(9p:message-contents message)</procedure>
     366<procedure>(9p:message-contents-set! message new-contents)</procedure>
    367367
    368368===== 9p:send-message
    369369
    370   procedure: (9p:send-message outport message)
     370<procedure>(9p:send-message outport message)</procedure>
    371371
    372372Sends the {{message}} on the output-port {{outport}}.
     
    374374===== 9p:receive-message
    375375
    376   procedure: (9p:receive-message inport)
     376<procedure>(9p:receive-message inport)</procedure>
    377377
    378378Waits for a message on input-port {{inport}} and returns a 9p message-object.
     
    382382A QID is an unique identifier for a file on the server; two QIDs are the same iff they point to the same file.  A QID has three fields which can be queried with the following procedures:
    383383
    384   procedure: (9p:qid-type qid)
    385   procedure: (9p:qid-version qid)
    386   procedure: (9p:qid-path qid)
     384<procedure>(9p:qid-type qid)</procedure>
     385<procedure>(9p:qid-version qid)</procedure>
     386<procedure>(9p:qid-path qid)</procedure>
    387387
    388388You can create a QID using the {{make-9p:qid}} procedure:
    389389
    390   procedure: (make-9p:qid type version path)
     390<procedure>(make-9p:qid type version path)</procedure>
    391391
    392392Finally, you can check if an object is a QID object with the {{9p:qid?}} predicate:
    393393
    394   procedure: (9p:qid? object)
     394<procedure>(9p:qid? object)</procedure>
    395395
    396396The fields of the QID will be described next.
     
    398398First, the type of a QID is a bitwise field which consists of several of the following constants ORed together:
    399399
    400   9p:qtfile
     400<constant>9p:qtfile</constant>
    401401 
    402402{{9p:qtfile}} indicates that the file is, in fact, a file.  Because everything in Plan9 is a file, this is always true, even for directories.  It does ''not'' mean that the file is a regular file.
    403403 
    404   9p:qtdir
     404<constant>9p:qtdir</constant>
    405405
    406406{{9p:qtdir}} indicates that the file is a directory.
    407407
    408   9p:qtappend
     408<constant>9p:qtappend</constant>
    409409
    410410{{9p:qtappend}} indicates that the file is an append-only file.
    411411
    412   9p:qtexcl
     412<constant>9p:qtexcl</constant>
    413413
    414414{{9p:qtexcl}} indicates that the file is marked for exclusive-use.  This means that only one client can have this file open at any time.
    415415
    416   9p:qtauth
     416<constant>9p:qtauth</constant>
    417417
    418418{{9p:qtauth}} indicates that the file is an authentication file established by AUTH messages.
    419419 
    420   9p:qttmp
     420<constant>9p:qttmp</constant>
    421421
    422422{{9p:qttmp}} indicates that the file is a "temporary file".  In practice this means that the file is not included in nightly backups.
     
    432432'''Note:''' The 9p protocol documentation is not very consistent in naming these.  Sometimes it refers to permissions as ''mode'', and sometimes as ''perm'' or ''permission''.  On other occasions, it refers to the [[#Open flags|open flags]] as ''mode''.  Read carefully and check the context!
    433433
    434    9p:perm/irusr
    435    9p:perm/iwusr
    436    9p:perm/ixusr
     434<constant>9p:perm/irusr</constant>
     435<constant>9p:perm/iwusr</constant>
     436<constant>9p:perm/ixusr</constant>
    437437
    438438These constants determine the permissions for the user who owns the file: read, write and execute, respectively.
    439439
    440    9p:perm/irgrp
    441    9p:perm/iwgrp
    442    9p:perm/ixgrp
     440<constant>9p:perm/irgrp</constant>
     441<constant>9p:perm/iwgrp</constant>
     442<constant>9p:perm/ixgrp</constant>
    443443   
    444444These constants determine the permissions for the group that owns the file: read, write and execute, respectively.
    445445
    446    9p:perm/iroth
    447    9p:perm/iwoth
    448    9p:perm/ixoth
     446<constant>9p:perm/iroth</constant>
     447<constant>9p:perm/iwoth</constant>
     448<constant>9p:perm/ixoth</constant>
    449449
    450450These constants determine the permissions for others: read, write and execute, respectively.
     
    452452There are some additional "permissions" that can be used on {{Tcreate}} messages, which are not really permissions but rather modes that change the way the file behaves (hence the inconsistence of the docs).  These are like the 'special' bits in Unix like sticky/setuid etc.  These are the following:
    453453
    454   9p:dmdir
     454<constant>9p:dmdir</constant>
    455455
    456456This is used to create directories instead of files with {{Tcreate}}.
    457457
    458   9p:dmappend
     458<constant>9p:dmappend</constant>
    459459
    460460The file can only be appended to.
    461461
    462   9p:dmexcl
     462<constant>9p:dmexcl</constant>
    463463
    464464The file is 'exclusive', it can only be opened by one client at a time.
    465465
    466   9p:dmauth
     466<constant>9p:dmauth</constant>
    467467
    468468The file is an authentication file, as established by AUTH messages.
    469469
    470   9p:dmtmp
     470<constant>9p:dmtmp</constant>
    471471
    472472The file is to be considered "temporary".  In practice this means that it is not included in nightly backups.
     
    476476These flags are useful when opening a new file (for use in the {{Topen}}/{{Tcreate}} messages).  These can be ORed together bitwise to produce the desired mode.
    477477
    478    9p:open/rdonly
     478<constant>9p:open/rdonly</constant>
    479479
    480480The file is to be opened only for reading.
    481481
    482    9p:open/wronly
     482<constant>9p:open/wronly</constant>
    483483
    484484The file is to be opened only for writing.
    485485
    486    9p:open/rdwr
     486<constant>9p:open/rdwr</constant>
    487487
    488488The file is to be opened both for reading and writing.
    489489
    490    9p:open/trunc
     490<constant>9p:open/trunc</constant>
    491491
    492492The file is to be truncated on opening.
    493493
    494    9p:open/rclose
     494<constant>9p:open/rclose</constant>
    495495
    496496The file is to be removed upon closing (ie, when the FID is clunked).
     
    500500===== 9p:data->directory-listing
    501501
    502   procedure: (9p:data->directory-listing data show-dotfiles?)
     502<procedure>(9p:data->directory-listing data show-dotfiles?)</procedure>
    503503
    504504Because the 9p protocol requires you to use the {{Tread}}/{{Rread}} messages to read both from files and directories, the {{Rread}} response can be considered to be a polymorphic type.  In case of files, the data is simply a bytestream, but in case of directories, the data will be structured.  This means the data needs to be decoded.
     
    514514Here's a simple example that talks to a wmii server.
    515515
    516 <enscript highlight=scheme>
     516<example>
     517<expr>
    517518(use 9p-client posix unix-sockets)
    518519
     
    526527    (9p:with-output-to-file con "/rbar/status" (lambda () (printf "Yo, what's up?")))
    527528    (9p:client-disconnect con)))
    528 </enscript>
     529</expr>
     530</example>
    529531
    530532This prints something like
Note: See TracChangeset for help on using the changeset viewer.