Changeset 12515 in project


Ignore:
Timestamp:
11/15/08 17:29:21 (13 years ago)
Author:
sjamaan
Message:

Reverse merge 9p docs so release 3 docs match with the names used in release 3 egg

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/9p

    r11240 r12515  
    3232=== 9p-client
    3333
    34 The basic library was modeled after Chicken's [[Unit posix]] and a few choice other procedures that interact with the filesystem.  Most procedures from Unit posix are available under the same name.  When you include the module together with posix, don't forget to prefix either these procedures or those of posix! Where possible, the procedure's signature has been unmodified, except for an additional leading argument that specifies the connection with the 9p server.
     34The basic library was modeled after Chicken's [[Unit posix]] and a few choice other procedures that interact with the filesystem.  Most procedures from Unit posix are available under the same name, prefixed with {{9p:}}. Where possible, the procedure's signature has been unmodified, except for an additional leading argument that specifies the connection with the 9p server.
    3535
    3636==== Usage
     
    4343==== Connection management
    4444
    45 ===== client-connect
    46 
    47 Before doing anything else, you must establish a connection with the server.  This is done with the {{client-connect}} procedure.
    48 
    49 <procedure>(client-connect inport outport [user] [mountpoint])</procedure>
     45===== 9p:client-connect
     46
     47Before doing anything else, you must establish a connection with the server.  This is done with the {{9p:client-connect}} procedure.
     48
     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>(connection-outport connection)</procedure>
    58 <procedure>(connection-inport connection)</procedure>
    59 
    60 Get back the underlying ports you passed to {{client-connect}}.
    61 
    62 <procedure>(connection-message-size connection)</procedure>
     57<procedure>(9p:connection-outport connection)</procedure>
     58<procedure>(9p:connection-inport connection)</procedure>
     59
     60Get back the underlying ports you passed to {{9p:client-connect}}.
     61
     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).
    6565
    6666
    67 ===== client-disconnect
    68 
    69 <procedure>(client-disconnect connection)</procedure>
     67===== 9p:client-disconnect
     68
     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).
    7272
    73 ===== connection?
    74 
    75 <procedure>(connection? object)</procedure>
     73===== 9p:connection?
     74
     75<procedure>(9p:connection? object)</procedure>
    7676
    7777You can verify an object is a connection to a 9p server with this predicate.
     
    7979==== Files as ports
    8080
    81 ===== with-output-to-file
    82 
    83 <procedure>(with-output-to-file connection file thunk)</procedure>
     81===== 9p:with-output-to-file
     82
     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.
    8686
    87 ===== call-with-output-file
    88 
    89 <procedure>(call-with-output-file connection file procedure)</procedure>
     87===== 9p:call-with-output-file
     88
     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.
    9292
    93 ===== open-output-file
    94 
    95 <procedure>(open-output-file connection file [mode])</procedure>
     93===== 9p:open-output-file
     94
     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.
     
    9999Don't forget to close the output port (with {{close-output-port}}) when you finish writing to it!
    100100
    101 ===== with-input-from-file
    102 
    103 <procedure>(with-input-from-file connection file thunk)</procedure>
     101===== 9p:with-input-from-file
     102
     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.
    106106
    107 ===== call-with-input-file
    108 
    109 <procedure>(call-with-input-file connection file procedure)</procedure>
     107===== 9p:call-with-input-file
     108
     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.
    112112
    113 ===== open-input-file
    114 
    115 <procedure>(open-input-file connection file)</procedure>
     113===== 9p:open-input-file
     114
     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}}.
     
    121121==== Directories
    122122
    123 ===== directory?
    124 
    125 <procedure>(directory? connection path)</procedure>
     123===== 9p:directory?
     124
     125<procedure>(9p:directory? connection path)</procedure>
    126126
    127127Returns {{#t}} if the given {{path}} on the {{connection}} is a directory, {{#f}} if not.
    128128
    129 ===== create-directory
    130 
    131 <procedure>(create-directory connection path permissions)</procedure>
     129===== 9p:create-directory
     130
     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.
    134134
    135 ===== directory
    136 
    137 <procedure>(directory connection directory [show-dotfiles?])</procedure>
     135===== 9p:directory
     136
     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.
     
    141141==== Files
    142142
    143 ===== regular-file?
    144 
    145 <procedure>(regular-file? connection path)</procedure>
    146 
    147 Returns {{#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 (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]]).
    148 
    149 ===== delete-file
    150 
    151 <procedure>(delete-file connection path)</procedure>
     143===== 9p:regular-file?
     144
     145<procedure>(9p:regular-file? connection path)</procedure>
     146
     147Returns {{#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]]).
     148
     149===== 9p:delete-file
     150
     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.
    154154
    155 ===== file-stat
    156 
    157 <procedure>(file-stat connection path)</procedure>
     155===== 9p:file-stat
     156
     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:
     
    169169* The user who last modified the file (a string)
    170170
    171 ===== file-permissions
    172 
    173 <procedure>(file-permissions connection path)</procedure>
     171===== 9p:file-permissions
     172
     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.
    176176
    177 ===== file-access-time
    178 
    179 <procedure>(file-access-time connection path)</procedure>
    180 
    181 Returns the access time of the file indicated by {{path}} on the {{connection}}.  See the notes under [[#file-stat]].
    182 
    183 
    184 ===== file-modification-time
    185 
    186 <procedure>(file-modification-time connection path)</procedure>
    187 
    188 Returns the modification time of the file indicated by {{path}} on the {{connection}}.  See the notes under [[#file-stat]].
    189 
    190 ===== file-size
    191 
    192 <procedure>(file-size connection path)</procedure>
     177===== 9p:file-access-time
     178
     179<procedure>(9p:file-access-time connection path)</procedure>
     180
     181Returns the access time of the file indicated by {{path}} on the {{connection}}.  See the notes under [[#9p:file-stat]].
     182
     183
     184===== 9p:file-modification-time
     185
     186<procedure>(9p:file-modification-time connection path)</procedure>
     187
     188Returns the modification time of the file indicated by {{path}} on the {{connection}}.  See the notes under [[#9p:file-stat]].
     189
     190===== 9p:file-size
     191
     192<procedure>(9p:file-size connection path)</procedure>
    193193
    194194Returns the size, in bytes, of the file indicated by {{path}} on the {{connection}}.
    195195
    196 ===== file-owner
    197 
    198 <procedure>(file-owner connection path)</procedure>
     196===== 9p:file-owner
     197
     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}}.
    201201
    202 ===== file-group
    203 
    204 <procedure>(file-group connection path)</procedure>
     202===== 9p:file-group
     203
     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}}.
    207207
    208 ===== file-last-modified-by
    209 
    210 <procedure>(file-last-modified-by connection path)</procedure>
     208===== 9p:file-last-modified-by
     209
     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}}.
     
    216216These calls are not on the protocol level, as the [[#9p-lolevel]] library procedures, but they are more low-level than the other procedures in the [[#9p-client]] library because they allow you to work on the file handle level.
    217217
    218 ===== file-open
    219 
    220 <procedure>(file-open connection path mode)</procedure>
     218===== 9p:file-open
     219
     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]].
    223223
    224 ===== file-create
    225 
    226 <procedure>(file-create connection path permissions mode)</procedure>
     224===== 9p:file-create
     225
     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]].
    229229
    230230
    231 ===== file-close
    232 
    233 <procedure>(file-close handle)</procedure>
     231===== 9p:file-close
     232
     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.
    236236
    237 ===== file-read
    238 
    239 <procedure>(file-read handle size)</procedure>
     237===== 9p:file-read
     238
     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.
    242242
    243 ===== file-write
    244 
    245 <procedure>(file-write handle buffer [size])</procedure>
     243===== 9p:file-write
     244
     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.
    248248
    249 ===== set-file-position!
    250 
    251 <procedure>(set-file-position! handle position [whence])</procedure>
     249===== 9p:set-file-position!
     250
     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}}.
    254254
    255 ===== file-position
    256 
    257 <procedure>(file-position handle)</procedure>
     255===== 9p:file-position
     256
     257<procedure>(9p:file-position handle)</procedure>
    258258
    259259Returns the current read/write position of the {{handle}}.
    260260
    261 ===== handle-stat
    262 
    263 <procedure>(handle-stat handle)</procedure>
    264 
    265 Just like [[#file-stat]], except it works on a handle instead of on a connection with a filename.
     261===== 9p:handle-stat
     262
     263<procedure>(9p:handle-stat handle)</procedure>
     264
     265Just like [[#9p:file-stat]], except it works on a handle instead of on a connection with a filename.
    266266
    267267===== Low-level handle access
     
    269269If you want to get really dirty and low-level you can modify file handles with the following procedures.  This is not recommended, but sometimes required if you want to do some custom things just above the protocol level and extend the client library instead of writing your own.
    270270
    271 ====== path-walk
    272 
    273 <procedure>(path-walk connection path [starting-point])</procedure>
    274 
    275 Obtain 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 {{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 (/).
    276 
    277 ====== with-handle-to
     271====== 9p:path-walk
     272
     273<procedure>(9p:path-walk connection path [starting-point])</procedure>
     274
     275Obtain 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 (/).
     276
     277====== 9p:with-handle-to
    278278
    279279If all you need is a temporary handle/FID for a message to the server, you can use this utility procedure:
    280280
    281 <procedure>(with-handle-to connection path procedure)</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.
    284284
    285 ====== alloc-handle
     285====== 9p:alloc-handle
    286286
    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>(alloc-handle connection)</procedure>
     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>(handle-connection handle)</procedure>
    294 <procedure>(handle-fid handle)</procedure>
    295 <procedure>(handle-position handle)</procedure>
    296 <procedure>(handle-iounit handle)</procedure>
     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).
    299299
    300 The iounit defaults to {{#f}} and you are expected to set it manually (normally, [[file-open]] and [[file-create]] do this for you). is returned as part of the Ropen and Rcreate replies and is the maximum size of a data transfer (either read or write).  If the server returns 0, the iounit should default to the size returned by {{connection-message-size}} minus 24.
    301 
    302 
    303 ====== release-handle
    304 
    305 Once you are done with a handle, you must either pass the handle to [[file-close]] (or just disconnect with [[client-disconnect]]) or call {{release-handle}}:
    306 
    307 <procedure>(release-handle handle)</procedure>
    308 
    309 '''important''': be sure to clunk the handle's fid first.  {{release-handle}} does ''not'' clunk the fid.
     300The iounit defaults to {{#f}} and you are expected to set it manually (normally, [[9p:file-open]] and [[9p:file-create]] do this for you). is returned as part of the Ropen and Rcreate replies and is the maximum size of a data transfer (either read or write).  If the server returns 0, the iounit should default to the size returned by {{9p:connection-message-size}} minus 24.
     301
     302
     303====== 9p:release-handle
     304
     305Once 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}}:
     306
     307<procedure>(9p:release-handle handle)</procedure>
     308
     309'''important''': be sure to clunk the handle's fid first.  {{9p:release-handle}} does ''not'' clunk the fid.
    310310
    311311
     
    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>(request connection type . args)</procedure>
    317 
    318 This creates a new {{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 message object) is returned.
     316<procedure>(9p:request connection type . args)</procedure>
     317
     318This 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.
    319319
    320320=== 9p-lolevel
     
    333333Messages are main concept in the 9p protocol.  They can be created as follows:
    334334
    335 <procedure>(make-message type tag contents)</procedure>
     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>(message? object)</procedure>
    361 <procedure>(message-type message)</procedure>
    362 <procedure>(message-type-set! message new-type)</procedure>
    363 <procedure>(message-tag message)</procedure>
    364 <procedure>(message-tag-set! message new-tag)</procedure>
    365 <procedure>(message-contents message)</procedure>
    366 <procedure>(message-contents-set! message new-contents)</procedure>
    367 
    368 ===== send-message
    369 
    370 <procedure>(send-message outport message)</procedure>
     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>
     367
     368===== 9p:send-message
     369
     370<procedure>(9p:send-message outport message)</procedure>
    371371
    372372Sends the {{message}} on the output-port {{outport}}.
    373373
    374 ===== receive-message
    375 
    376 <procedure>(receive-message inport)</procedure>
     374===== 9p:receive-message
     375
     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>(qid-type qid)</procedure>
    385 <procedure>(qid-version qid)</procedure>
    386 <procedure>(qid-path qid)</procedure>
    387 
    388 You can create a QID using the {{make-qid}} procedure:
    389 
    390 <procedure>(make-qid type version path)</procedure>
    391 
    392 Finally, you can check if an object is a QID object with the {{qid?}} predicate:
    393 
    394 <procedure>(qid? object)</procedure>
     384<procedure>(9p:qid-type qid)</procedure>
     385<procedure>(9p:qid-version qid)</procedure>
     386<procedure>(9p:qid-path qid)</procedure>
     387
     388You can create a QID using the {{make-9p:qid}} procedure:
     389
     390<procedure>(make-9p:qid type version path)</procedure>
     391
     392Finally, you can check if an object is a QID object with the {{9p:qid?}} predicate:
     393
     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 <constant>qtfile</constant>
    401  
    402 {{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.
    403  
    404 <constant>qtdir</constant>
    405 
    406 {{qtdir}} indicates that the file is a directory.
    407 
    408 <constant>qtappend</constant>
    409 
    410 {{qtappend}} indicates that the file is an append-only file.
    411 
    412 <constant>qtexcl</constant>
    413 
    414 {{qtexcl}} indicates that the file is marked for exclusive-use.  This means that only one client can have this file open at any time.
    415 
    416 <constant>qtauth</constant>
    417 
    418 {{qtauth}} indicates that the file is an authentication file established by AUTH messages.
    419  
    420 <constant>qttmp</constant>
    421 
    422 {{qttmp}} indicates that the file is a "temporary file".  In practice this means that the file is not included in nightly backups.
     400<constant>9p:qtfile</constant>
     401 
     402{{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.
     403 
     404<constant>9p:qtdir</constant>
     405
     406{{9p:qtdir}} indicates that the file is a directory.
     407
     408<constant>9p:qtappend</constant>
     409
     410{{9p:qtappend}} indicates that the file is an append-only file.
     411
     412<constant>9p:qtexcl</constant>
     413
     414{{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.
     415
     416<constant>9p:qtauth</constant>
     417
     418{{9p:qtauth}} indicates that the file is an authentication file established by AUTH messages.
     419 
     420<constant>9p:qttmp</constant>
     421
     422{{9p:qttmp}} indicates that the file is a "temporary file".  In practice this means that the file is not included in nightly backups.
    423423
    424424The version of a QID is a version number for the file which is incremented every time the file is modified.
     
    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 <constant>perm/irusr</constant>
    435 <constant>perm/iwusr</constant>
    436 <constant>perm/ixusr</constant>
     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 <constant>perm/irgrp</constant>
    441 <constant>perm/iwgrp</constant>
    442 <constant>perm/ixgrp</constant>
     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 <constant>perm/iroth</constant>
    447 <constant>perm/iwoth</constant>
    448 <constant>perm/ixoth</constant>
     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 <constant>dmdir</constant>
     454<constant>9p:dmdir</constant>
    455455
    456456This is used to create directories instead of files with {{Tcreate}}.
    457457
    458 <constant>dmappend</constant>
     458<constant>9p:dmappend</constant>
    459459
    460460The file can only be appended to.
    461461
    462 <constant>dmexcl</constant>
     462<constant>9p:dmexcl</constant>
    463463
    464464The file is 'exclusive', it can only be opened by one client at a time.
    465465
    466 <constant>dmauth</constant>
     466<constant>9p:dmauth</constant>
    467467
    468468The file is an authentication file, as established by AUTH messages.
    469469
    470 <constant>dmtmp</constant>
     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 <constant>open/rdonly</constant>
     478<constant>9p:open/rdonly</constant>
    479479
    480480The file is to be opened only for reading.
    481481
    482 <constant>open/wronly</constant>
     482<constant>9p:open/wronly</constant>
    483483
    484484The file is to be opened only for writing.
    485485
    486 <constant>open/rdwr</constant>
     486<constant>9p:open/rdwr</constant>
    487487
    488488The file is to be opened both for reading and writing.
    489489
    490 <constant>open/trunc</constant>
     490<constant>9p:open/trunc</constant>
    491491
    492492The file is to be truncated on opening.
    493493
    494 <constant>open/rclose</constant>
     494<constant>9p:open/rclose</constant>
    495495
    496496The file is to be removed upon closing (ie, when the FID is clunked).
     
    498498==== Utility procedures
    499499
    500 ===== data->directory-listing
    501 
    502 <procedure>(data->directory-listing data show-dotfiles?)</procedure>
     500===== 9p:data->directory-listing
     501
     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.
     
    506506This procedures decodes the {{data}} obtained from the {{Rread}} message and returns a list of filenames which are the directory listing for the directory that was read.  If {{show-dotfiles?}} is {{#f}} files starting with a dot are excluded from the list.
    507507
    508 Note: The converse procedure, {{directory-listing->data}}, is currently not implemented.
     508Note: The converse procedure, {{9p:directory-listing->data}}, is currently not implemented.
    509509
    510510=== Example
     
    518518
    519519<example>
    520 <init>
    521 (require-library 9p-client unix-sockets)
    522 
    523 (import (prefix 9p-client 9p:))
    524 </init>
    525520<expr>
     521(use 9p-client posix unix-sockets)
     522
    526523(receive (in out)
    527524    (unix-connect (sprintf "/tmp/ns.~A.:0/wmii" (getenv "USER")))
     
    545542=== Changelog
    546543
    547 * 0.6 Port to hygienic Chicken, fix handle auto-closing bug
    548544* 0.5 Add mutex handling to ensure thread-safety
    549545* 0.4 When reading files, EOF gets reported only when the file really is at an end (fixes reading from FIFO-like files)
Note: See TracChangeset for help on using the changeset viewer.