chickadee » 9p

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

9p

Description

A pure Scheme implementation of the 9p networked filesystem protocol.

Author

Peter Bex

Requirements

Requires the iset egg.

Documentation

9p is an implementation of the networked file system protocol known as 9P, specifically version 9P2000 which is also known as "Styx". This protocol is used by the Plan 9 operating system and the wmii window manager, among others.

This implementation includes a high-level implementation of a 9p server and a 9p client, but it also exposes the underlying low-level interface which can be useful for writing your own implementation.

9p-client

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.

Usage

 (use 9p-client)
 (use utf8)

It is highly recommended you require utf8 in your applications, as 9p is a utf8-aware protocol. It is not a dependency of this egg because in some situations you might decide it's safe to leave it out, for performance or memory footprint reasons.

Connection management

client-connect

Before doing anything else, you must establish a connection with the server. This is done with the client-connect procedure.

(client-connect inport outport [user] [mountpoint])procedure

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

The procedure returns a connection object you must keep and use in all subsequent 9p procedure calls.

You can use the following procedures to obtain some more information on the connection:

connection-outport connectionprocedure

connection-inport connectionprocedure

Get back the underlying ports you passed to client-connect.

connection-message-size connectionprocedure

The 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).

client-disconnect

client-disconnect connectionprocedure

Disconnect from the server described by connection. This clunks any fids that are still open (in Unix terms: closes any open file descriptors).

connection?

connection? objectprocedure

You can verify an object is a connection to a 9p server with this predicate.

Files as ports

with-output-to-file

with-output-to-file connection file thunkprocedure

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

call-with-output-file

call-with-output-file connection file procedureprocedure

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

open-output-file

open-output-file connection file #!optional modeprocedure

Create 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 below for the list of file permissions.

Don't forget to close the output port (with close-output-port) when you finish writing to it!

with-input-from-file

with-input-from-file connection file thunkprocedure

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

call-with-input-file

call-with-input-file connection file procedureprocedure

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

open-input-file

open-input-file connection fileprocedure

Create an input port that will read from the given file on the 9p connection connection.

Don't forget to close the input port (with close-input-port when you finish reading from it!

Directories

directory?

directory? connection pathprocedure

Returns #t if the given path on the connection is a directory, #f if not.

create-directory

create-directory connection path permissionsprocedure

Create a directory on the connection with the given path. It will have the specified permissions, see below for the available permissions.

directory

directory connection directory #!optional show-dotfiles?procedure

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

Files

regular-file?

regular-file? connection pathprocedure

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 9P2000.u).

delete-file

delete-file connection pathprocedure

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

file-stat

file-stat connection pathprocedure

Returns a 9-element vector which contains information about the file indicated by path on the connection. It has the following contents:

• The QID of the file (The qid can be queried with the QID procedures from 9p-lolevel.
• The permission mode (See the permission bits section for a description)
• The access time of the file. This is an integer which indicates the server-time when the file was last accessed. There is no way to determine what the server's time is using the 9p protocol, so you can only use this for comparing timestamps of files on the same server unless you use an additional protocol to find out about the server's current time and zone.
• The modification time of the file. This is an integer which indicates the server-time when the file was last modified.
• The file's size in bytes.
• The filename of the file.
• The user who owns the file (a string, not a uid, because Plan9 has only user and group names, not numerical ids).
• The group who owns the file (a string)
• The user who last modified the file (a string)

file-permissions

file-permissions connection pathprocedure

Returns the permissions of the file indicated by path on the connection. See the permission bits section for a description of the possible bits.

file-access-time

file-access-time connection pathprocedure

Returns the access time of the file indicated by path on the connection. See the notes under file-stat.

file-modification-time

file-modification-time connection pathprocedure

Returns the modification time of the file indicated by path on the connection. See the notes under file-stat.

file-size

file-size connection pathprocedure

Returns the size, in bytes, of the file indicated by path on the connection.

file-owner

file-owner connection pathprocedure

Returns the name of the owner, as a string, of the file indicated by path on the connection.

file-group

file-group connection pathprocedure

Returns the name of the owning group, as a string, of the file indicated by path on the connection.

file-last-modified-by

file-last-modified-by connection pathprocedure

Returns the name of the user, as a string, who last changed the file indicated by path on the connection.

File handles and low-level calls

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

file-open

file-open connection path modeprocedure

Opens 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 the open flags section.

file-create

file-create connection path permissions modeprocedure

Creates 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 the open flags section. For bit flags that the permission can take, see the permission bits section.

file-close

file-close handleprocedure

Close the file indicated by handle. It is not an error to close a file more than once.

file-read

file-read handle sizeprocedure

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

file-write

file-write handle buffer #!optional sizeprocedure

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

set-file-position!

set-file-position! handle position #!optional whenceprocedure

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

file-position

file-position handleprocedure

Returns the current read/write position of the handle.

handle-stat

handle-stat handleprocedure

Just like file-stat, except it works on a handle instead of on a connection with a filename.

Low-level handle access

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

path-walk

path-walk connection path #!optional starting-pointprocedure

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 (/).

with-handle-to

If all you need is a temporary handle/FID for a message to the server, you can use this utility procedure:

with-handle-to connection path procedureprocedure

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

alloc-handle

The 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:

alloc-handle connectionprocedure

Allocate a handle on the connection. This returns a handle object which you can query with the following procedures:

handle-connection handleprocedure

handle-fid handleprocedure

handle-position handleprocedure

handle-iounit handleprocedure

The 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).

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.

release-handle

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:

release-handle handleprocedure

important: be sure to clunk the handle's fid first. release-handle does not clunk the fid.

Sending messages

A 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:

request connection type #!rest argsprocedure

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.

9p-server

This library lets you create your own 9p servers, allowing filesystems implemented in Chicken Scheme to be mounted as part of a computer's filesystem tree, or to be accessed by other 9p clients.

Here we document the Scheme interfaces, but you need to read the 9P protocol documentation to understand the semantics of the operations.

Usage

 (use 9p-server)
 (use utf8)

Again, utf8 is highly recommended but not strictly required.

Serving interface

serve inport outport handlersprocedure

The 9p-server module exports a single procedure, serve, which provides the 9p server protocol on a provided pair of ports (one for input, one for output). The caller must provide an alist mapping symbolic names of 9p protocol operations to closures that implement those operations. Some operations are optional, and default implementations will be used if they are not provided, but some are essential and must be provided or an error will be raised.

The 9p protocol is somewhat asynchronous; multiple requests may be submitted without the client waiting for responses, and the server may respond to open requests in any order. In order to support this, the handler procedures do not issue replies by returning a value, but by calling one of a number of closures they are passed as arguments. Most have a reply! argument to send a normal reply and an error! argument to send an error response, but there may be others, which will be discussed below.

Most handlers that originate from a 9p protocol message are passed the contents of the 9p request, which is a list, the format of which depends on the request.

The main exceptions are the initial version request that is part of the connection setup process, which does block until the handler directly returns the required value, and the disconnect request that is called when a connection is closed and has no reply. When the connection is closed, as soon as the disconnect handler returns, serve returns to its caller.

Connection management

Typically, one would write a handler that binds a TCP socket and spawns a thread for each connection accepted, which then invokes the serve procedure with suitable arguments, like so:

  (parameterize ((tcp-read-timeout #f)
                 (tcp-buffer-size 65536))
   (let ((listener (tcp-listen 1564)))
     (let accept-loop ()
       (receive (in out) (tcp-accept listener)
                (thread-start! (make-thread
                                (lambda ()
                                  (serve in out handlers)
                                  (close-input-port in)
                                  (close-output-port out)))))
       (accept-loop))))

It is advisable to turn off the TCP read timeout, or the 9p server, sitting blocked on a TCP read for the next request from the client, will time out!

The above code binds to TCP port 1564 rather than the traditional 9p port of 564, in order to avoid needing to run as root. It can be mounted on a Linux system with a command such as:

  mount -t 9p localhost -o port=1564 /mnt

It also assumes that the symbol handlers is bound to a suitable alist of handlers in the current lexical environment. We shall now examine the closures that should be found in that alist...

FIDs

The 9P protocol uses client-assigned handles called "fids" to refer to server-side resources such as open files, open directories, or authentication protocols. Operations that create a server-side object provide a fid that the client would like to use to refer to that object in future.

The 9p-server module attempts to help with fid management by handling a mapping between fid values and Scheme objects representing the state of that server-side resource. Handlers that create an object are passed a bind-fid! callback which, if invoked with an arbitrary Scheme object, will bind that object to the fid. Handlers that operate on a server-side object are passed the value bound to that fid as an argument. Generally, you will use some mutable record type as the state of a fid, and mutate its slots as required.

Handlers

The handlers in the alist are documented as if they were declared procedures here for clarity, but they need to be listed in the handlers alist passed to serve, with the alist key being a symbol with the name of the handler.

version (optional)

version messageprocedure

The version request corresponds to a 9P Tversion request. The message is a list of two elements; the first is the maximum message size the client supports, and the second is a protocol version string indicating what version of the 9P protocol is expected (my Linux system sends "9P2000.u")

The handler must return a block size which is less than or equal to that requested by the client.

The default implementation just returns the block size requested by the client.

disconnect

disconnectprocedure

The disconnect handler is called when the underlying connection is closed. There is no message, and the return value is ignored.

The default implementation does nothing.

auth (optional)

auth message bind-fid! reply! error!procedure

This corresponds to a 9P Tauth request. The message is a list of three elements, the fid to bind to the authentication protocol connection, the user name, and the tree name. If the server does not require authentication, it should call the error! callback with a string such as "No authentication required". If it does require authentication, it should bind the fid to an authentication connection by calling bind-fid! with a suitable value for the initial state of the authentication protocol, and call reply! with list containing a single element, a qid of type QTAUTH.

The default implementation returns an error indicating that authentication is not required.

attach

attach message auth-fid-value bind-fid! reply! error!procedure

This corresponds to a 9P Tattach request. The message is a list of four elements, the fid to bind to the root directory, a fid used for authentication, the user name attaching, and the name of the file tree to attach (often just the empty string). If an auth request occurred then auth-fid-value will be the state of the authentication protocol. bind-fid! should be called with a value to be the initial state of the root directory fid. reply! should be called with a list containing a single element, the QID of the root directory if it succeeded, otherwise error! should be called with an error message string.

flush (optional)

flush message reply! error!procedure

This corresponds to a 9P Tflush request. The message is a list of one element, the tag of the operation to flush. This is not currently well-supported by the 9p-server implementation, as the tags of operations are not currently exposed to handlers.

If the flush succeeds, it should call reply! with an empty list. If not, it can call error! with an error string.

The default implementation calls its reply! callback with an empty list.

walk

walk message parent-fid-value bind-fid! reply! error!procedure

This corresponds to a 9P Twalk request. The message is a list of three elements, those being the fid of the already open parent directory, the fid to bind the located file or directory to, and a list of path components to traverse.

parent-fid-value is the value bound to the parent fid.

If the walk operation succeeds, bind-fid! should be called with the initial state of the new fid, and reply! called with a list containing a single element, that being the list of QIDs of the traversed directories.

If the walk operation fails, error! should be called with a suitable error string.

open

open message fid-value reply! error!procedure

This corresponds to a 9P Topen request. The message is a list of two elements, the fid of the file and the requested access mode. fid-value is the value bound to the fid.

If the open operation succeeds, reply! should be called with a list of two elements, the first being the QID of the newly opened file and the second being the desired I/O block size in bytes.

If it fails, error! should be called with a suitable error string.

create (optional)

create message fid-value reply! error!procedure

This corresponds to a 9P Tcreate request. The message is a list of four elements, the fid of the directory in which to create the new object, the name, the permissions, and the access mode for the new object. fid-value is the value bound to the parent directory fid.

If the creation succeeds, the fid value should be mutated into the initial state of the new file, and reply! should be called with a list of two elements, the QID of the new file and the desired I/O block size in bytes.

If it fails, error! should be called with a suitable error string.

The default implementation calls error! with a message stating that creation is not supported.

read (optional)

read message fid-value reply! error!procedure

This corresponds to a 9P Tread request. The message is a list of three elements, the fid of the file, the offset to read from, and the number of bytes to read. fid-value is the value bound to the fid.

If the read succeeds, reply! should be called with a list of one argument, that being a u8vector of bytes of the desired length or less.

If the read fails, error! should be called with a suitable error message.

The default implementation calls error! with a message stating that reading is not supported.

write (optional)

write message fid-value reply! error!procedure

This corresponds to a 9P Twrite request. The message is a list of three elements, the fid of the file, the offset to write to, and the data to write as a u8vector.

If the write succeeds, reply! should be called with a list of a single element, the number of bytes actually written.

If the write fails, error! should be called with a suitable error message.

The default implementation calls error! with a message stating that writing is not supported.

clunk (optional)

clunk fid-value reply! error!procedure

This corresponds to a 9P Tclunk request. The message consists purely of the fid, so it is not passed to the handler. fid-value is the value bound to the fid being clunked.

If the clunk succeeds, reply! should be called and passed an empty list.

If the clunk fails, error! should be called with a suitable error message.

The default implemention calls reply! with an empty list.

remove (optional)

remove fid-value reply! error!procedure

This corresponds to a 9P Tremove request. The message consists purely of the fid, so it is not passed to the handler. fid-value is the value bound to the fid being removed.

If the remove succeeds, reply! should be called and passed an empty list.

If the remove fails, error! should be called with a suitable error message.

The default implemention calls error! with a message stating that removal is not supported.

stat (optional)

stat message fid-value reply! error!procedure

This corresponsd to a 9P Tstate request. The message consists purely of the fid, so it is not passed to the handler. fid-value is the value bound to the fid.

If the stat succeeds, reply! should be called and passed a list of nine elements:

• The QID of the file
• The permissions of the file
• The atime of the file
• The mtime of the file
• The size of the file
• The name of the file
• The user name of the file
• The group name of the file
• The name of the user who last modified the file

If it fails, error! should be called with a suitable error message.

The default implementation calls error! with an error message indicating that stat is not supported.

wstat (optional)

wstat message fid-value reply! error!procedure

This corresponds to a 9P Twstat request. The message is a list of ten elements:

• The fid of the file
• The QID of the file
• The permissions of the file
• The atime of the file
• The mtime of the file
• The size of the file
• The name of the file
• The user name of the file
• The group name of the file
• The name of the user who last modified the file

fid-value is the value bound to the fid.

If the wstat succeeds, reply! should be called with a list of no elements.

If if fails, error! should be called with a suitable error string.

The default implementation calls error! with an error message indicating that wstat is not supported.

Example

Within the 9p egg is a file called 9p-demo-server.scm that runs a 9p server on port 1564, providing a root directory with two read-only files inside.

The source code contains the beginnings of an infrastructure for building general virtual filesystems with files whose contents are computed on the fly by Scheme closures.

9p-lolevel

This library allows you to build your own client or server abstraction library. This documentation will not make a lot of sense if you haven't read the 9p protocol documentation.

Usage

 (use 9p-lolevel)
 (use utf8)

Again, utf8 is highly recommended but not strictly required.

Messages

Messages are main concept in the 9p protocol. They can be created as follows:

make-message type tag contentsprocedure

The type is a symbol, one of

 Tversion Rversion
 Tauth Rauth
 Tattach Rattach
 Rerror
 Tflush Rflush
 Twalk Rwalk
 Topen Ropen
 Tcreate Rcreate
 Tread Rread
 Twrite Rwrite
 Tclunk Rclunk
 Tremove Rremove
 Tstat Rstat
 Twstat Rwstat

As you can see, all messages (except Rerror) come in pairs: there is a transmit message (that starts with a T) and a response message (that starts with an R). The client sends transmit messages and the server sends response message in return. It must either send the matching response message or Rerror. It is not allowed to return a different message, nor is it allowed for the client to send a response message or the server to send a transmit message.

The tag is a unique identifier that allows the client to keep track of what it sent and what responses belong to what transmissions. The client sends a message with a given tag and the server will respond with the matching response message bearing the same tag. This allows a client to send messages asynchronously, as long as they all have a different tag. Then the responses can come in any order and be handled at any time and still be understood if the client keeps a list of sent tags and what transmissions belonged to them. The 9p-client library always sends messages synchronously, waiting for replies before sending new transmissions. This allows it to use a constant tag all the time.

The contents are a list whose contents differ per message type. For instance, a Tversion message's contents consist of an msize (a maximum message size) and a string which indicates the protocol version. Currently the 9p-lolevel implicitly assumes the 9P2000 version of the protocol because of the way it is constructed. If it turns out to be useful to support different versions, the egg's API will most likely change in order to allow for more flexibility.

You can of course query and modify the message objects with the following procedures:

message? objectprocedure

message-type messageprocedure

message-type-set! message new-typeprocedure

message-tag messageprocedure

message-tag-set! message new-tagprocedure

message-contents messageprocedure

message-contents-set! message new-contentsprocedure

send-message

send-message outport messageprocedure

Sends the message on the output-port outport.

receive-message

receive-message inportprocedure

Waits for a message on input-port inport and returns a 9p message-object.

QIDs

A 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:

qid-type qidprocedure

qid-version qidprocedure

qid-path qidprocedure

You can create a QID using the make-qid procedure:

make-qid type version pathprocedure

Finally, you can check if an object is a QID object with the qid? predicate:

qid? objectprocedure

The fields of the QID will be described next.

First, the type of a QID is a bitwise field which consists of several of the following constants ORed together:

qtfileconstant

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.

qtdirconstant

qtdir indicates that the file is a directory.

qtappendconstant

qtappend indicates that the file is an append-only file.

qtexclconstant

qtexcl indicates that the file is marked for exclusive-use. This means that only one client can have this file open at any time.

qtauthconstant

qtauth indicates that the file is an authentication file established by AUTH messages.

qttmpconstant

qttmp indicates that the file is a "temporary file". In practice this means that the file is not included in nightly backups.

The version of a QID is a version number for the file which is incremented every time the file is modified.

The path of a QID is an integer that is unique among all files in the file hierarchy (ie, this uniquely identifies the file in the FS).

Permission bits

The permissions below can be ORed together bitwise to produce the desired permission mode. When creating new files, the execute bit is ignored by the server unless you're creating a directory, so it is safe to always include it.

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 as mode. Read carefully and check the context!

perm/irusrconstant

perm/iwusrconstant

perm/ixusrconstant

These constants determine the permissions for the user who owns the file: read, write and execute, respectively.

perm/irgrpconstant

perm/iwgrpconstant

perm/ixgrpconstant

These constants determine the permissions for the group that owns the file: read, write and execute, respectively.

perm/irothconstant

perm/iwothconstant

perm/ixothconstant

These constants determine the permissions for others: read, write and execute, respectively.

There 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:

dmdirconstant

This is used to create directories instead of files with Tcreate.

dmappendconstant

The file can only be appended to.

dmexclconstant

The file is 'exclusive', it can only be opened by one client at a time.

dmauthconstant

The file is an authentication file, as established by AUTH messages.

dmtmpconstant

The file is to be considered "temporary". In practice this means that it is not included in nightly backups.

Open flags

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

open/rdonlyconstant

The file is to be opened only for reading.

open/wronlyconstant

The file is to be opened only for writing.

open/rdwrconstant

The file is to be opened both for reading and writing.

open/truncconstant

The file is to be truncated on opening.

open/rcloseconstant

The file is to be removed upon closing (ie, when the FID is clunked).

Utility procedures

data->directory-listing

data->directory-listing data show-dotfiles?procedure

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

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

Note: The converse procedure, directory-listing->data, is currently not implemented.

Example

9p-client

Here's a simple example that talks to a wmii server. Note that if you're really looking for a Scheme library to script your wmiirc files, you probably want the wmiirc egg instead of using the raw 9p protocol directly.

(require-library 9p-client unix-sockets)

(import (prefix 9p-client 9p:))

(receive (in out)
    (unix-connect (sprintf "/tmp/ns.~A.:0/wmii" (get-environment-variable "USER")))
  (let ((con (9p:client-connect in out)))
    (printf "Current tabs on left bar: ~A\n" (9p:directory con "/lbar"))
    (printf "Label on first tab on left bar: ~A\n"
            (9p:with-input-from-file con `("lbar" ,(car (9p:directory con "/lbar"))) read-string ))
    ;; Write something to the right bar
    (9p:with-output-to-file con "/rbar/status" (lambda () (printf "Yo, what's up?")))
    (9p:client-disconnect con)))

This prints something like

 Current tabs on left bar: (3 2 1)
 Label on first tab on left bar: #888888 #222222 #333333 3

And it shows the string "Yo, what's up?" on your status bar.

Changelog

• trunk Fix a bug in handling of Rwalk messages; sizes didn't match up (thanks to Evan Hanson). Add 9p-server mode (thanks to Alaric)
• 0.8 Change to install only one extension "9p". This simplifies uninstallation.
• 0.7 Fix import handling for unit "files"
• 0.6 Port to hygienic Chicken, fix handle auto-closing bug
• 0.5 Add mutex handling to ensure thread-safety
• 0.4 When reading files, EOF gets reported only when the file really is at an end (fixes reading from FIFO-like files)
• 0.3 Don't allow output 9p ports to return values when all other values are (void), allow multiple return values in with-output/with-input thunks
• 0.2 Fix 9p:open-output-file bug, make path-walk accept handles
• 0.1 Initial release

License

 Copyright (c) 2012, Peter Bex & Alaric Snell-Pym
 Copyright (c) 2007, 2008, 2011 Peter Bex
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.