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 low-level implementation of the protocol that is suitable both for writing clients and servers and a high-level client implementation. There currently are no concrete plans for a high-level server implementation, but contributions are of course very welcome :)

The low-level implementation is documented below under 9p-lolevel and the high-level client implementation under 9p-client. The high-level client is discussed first, because this is the one you will most likely need.

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.

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.

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

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

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:

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

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.

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!

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.

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

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

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.

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.

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.

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.

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.

Obtain a handle for the file identified by path on the connectionwithout 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 (/).

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

[procedure](with-handle-to connection path procedure)

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.

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:

[procedure](alloc-handle connection)

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

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.

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:

[procedure](request connection type . args)

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.

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.

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!

[constant]perm/irusr[constant]perm/iwusr[constant]perm/ixusr

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

[constant]perm/irgrp[constant]perm/iwgrp[constant]perm/ixgrp

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

[constant]perm/iroth[constant]perm/iwoth[constant]perm/ixoth

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:

[constant]dmdir

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

[constant]dmappend

The file can only be appended to.

[constant]dmexcl

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

[constant]dmauth

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

[constant]dmtmp

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

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.

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.

Copyright (c) 2008, 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.