A client implementation of the 9P file protocol: https://man.cat-v.org/plan_9/5/intro

cage 7990db6224 - increased version number. 1 day ago
src 0117665c2c - added 'change-time-values' (mtime and atime, if changed together, 1 day ago
tests afd2dce867 - updated Changelog. 1 day ago
COPYING 7f6d607ad6 - initial commit. 3 weeks ago
COPYING.LESSER 7f6d607ad6 - initial commit. 3 weeks ago
Changelog afd2dce867 - updated Changelog. 1 day ago
LICENSE 7f6d607ad6 - initial commit. 3 weeks ago
README.org 74ea756c5f - added 'move-file'; 2 weeks ago
README.txt 74ea756c5f - added 'move-file'; 2 weeks ago
purgatory-tests.asd 7f6d607ad6 - initial commit. 3 weeks ago
purgatory.asd 7990db6224 - increased version number. 1 day ago



This library aims to be an implementation of the 9p file protocol as described in:



The library is under development,most of the protocol has been implemented except for Twstat (https://man.cat-v.org/plan_9/5/stat); bugs, of course, exists, API may changes.


  • alexandria
  • cl-ppcre
  • usocket
  • babel
  • uiop
    To run the tests also
  • cl+ssl
  • clunit2

needs to be installed (via quicklisp).

Of course a 9p server is needed.


The best way to get purgatory working is using the excellent quicklisp

#+BEGIN_SRC common-lisp (ql:quickload "9p-client") #+END_SRC


A typical usage of the library should starts with a code similar to the one below:

#+BEGIN_SRC common-lisp (let ((messages-sent '()) (root-fid (mount stream root))) ...) #+END_SRC

Note that `stream` should be a stream of (unsigned-byte 8) and likely is created by a client socket. The file ./tests/all-tests.lisp contains a small macro with-open-ssl-stream that will help creating a TLS stream using usocket.

The file ./tests/protocol-tests.lisp contains a lot of examples about the usage of the library.

There are quite a few high level functions to use the filesystem that are listed below:

Initialize the connection to the server using `root-path' as the
root of the remote filesystem
  • read-all-pending-messages-ignoring-errors ::
  • Read all the messages from the server and ignore any error
    Make a new fid that points to the same resource pointed by `fid'
    Create a new directory with name `directory-name' under the
    directory pointed by `parent-fid'. The parameter `permissions' must be provided in octal (default: #o760))
  • path-exists-p
  • create-path
    Create a file or directory as specified by `path'.
    To create a directory specify a path terminating with a '/'. Parent directories are created if do not exist. The parameter `permissions' must be provided in octal (default: #o640))

    Returns the fid to the last element of `path'

    If the last element of `path' is a directory the directory is created with permissions: #o760.

    It `path' already reference a valid file it is opened for read and write.

    Finally if already reference a valid directory is opened for read only.
    Open a full, existing, path relative to `root-fid'. `Mode' must be
    one of ~+create-for-read+~ ~+create-for-write+~ ~+create-for-read-write+"~
    Read in a vector of (unsigned byte 8) the full content of
    'path' relative to `root-fid'
    Remove the last element of 'path' relative to `root-fid'
    Open the directory pointed to `path' relative to `root-fid'.
    Returns the fid of the directory pointed by `path'.

    This fid can be used by `read-directory` to get the directory entries (see the struct `stat')

    Read the next entry of a directory specified by `dir-fid'.

    `Dir-fid' is usually the values returned by `open-directory`.

    This function on success returns tree values:

    • dir-fid to read the next entry or to check if there are no more
    • entries (see below);
    • the stat struct for the current entry;
    • an offset to the next entry.

    Each call to this function on the same directory fid, except the first, must use the offset returned by the last call, for example

    #+BEGIN_SRC common-lisp (let* ((dir-fid (open-directory stream root-fid path))) (multiple-value-bind (next-dir-fid stat stat-size) (read-directory stream dir-fid) ; offset 0 on the first call (multiple-value-bind (next-dir-fid-2 stat-2 next-stat-size-2) (read-directory stream dir-fid stat-size) ; offset equals ; to stat-size ; from previous ; call ...))) #+END_SRC

    When this function returns nil there no more entries for this directory (see the code of directory children).
    Sort a list of stat struct `data' (by default sorting entry names
    in lexicographic ascending order
    Collect all the directory entries of `path' relative to `root-fid'
    as a list of `stat` structures, this list supposed to be never empty for a directory as should contains at least ".." and "."
    • copy-file ::
    • Copy a file pointed by ~path-from~ to a file pointed by ~path-to~. ~progress-fn~, if defined, must be a function with a single parameter: the number of octects wrote in a single call of the ~Twrite~ command.

    Note: the destination file is overwritten if does exists."

    Also checking the protocol documentation is useful https://man.cat-v.org/plan_9/5/intro


    Please send bug reports or patches to the issue tracker.


    This library is released under Lisp Lesser General Public license (see COPYING.LESSER file)


    This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.


    My deep thanks to op for the support and redfog for the name of the library, Thank you!