purgatory
2024-10-12
A simple implementation of the 9p filesystem protocol.
1Introduction
This library aims to be an implementation of the 9p file protocol as described in:
https://man.cat-v.org/plan_9/5/intro
2Status
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.
3Prerequisites:
- 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.
4Installation:
The best way to get purgatory working is using the excellent quicklisp
(ql:quickload "9p-client")
5Usage
A typical usage of the library should starts with a code similar to the one below:
(let ((*messages-sent* '())
(*fid* 1)
(*tag* 8)
(root-fid (mount stream root)))
...)
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:
- mount
- Initialize the connection to the server using `root-path' as the
- read-all-pending-messages-ignoring-errors
- clone-fid
- Make a new fid that points to the same resource pointed by `fid'
- create-directory
- Create a new directory with name `directory-name' under the
- path-exists-p
- create-path :: Create a file or directory as specified by `path'.
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-path
- Open a full, existing, path relative to `root-fid'. `Mode' must be
+create-for-read+
+create-for-write+
~+create-for-read-write+"~- slurp-file
- Read in a vector of (unsigned byte 8) the full content of
- remove-path
- Remove the last element of 'path' relative to `root-fid'.If `path' does not exists this function does nothing.
- open-directory
- Open the directory pointed to `path' relative to `root-fid'.
This fid can be used by `read-directory` to get the directory entries (see the struct `stat')
- read-directory
- 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
- 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
(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
...)))
When this function returns nil there no more entries for this directory (see the code of directory children).
- sort-dir-stats
- Sort a list of stat struct `data' (by default sorting entry names
- collect-directory-children
- Traverse the file system tree starting at`starting-directory' returning a list of strings representing the paths ofall files under `starting-directory'.
- collect-tree
- Traverse the file system tree starting at `starting-directory'returning two values
- a list of strings representing the paths of all the filesunder `starting-directory';
- a list of all the path to the sub-directories under `starting-directory'.
The lists are ordered in topological order (depth first strategy).
- copy-file
- Copy a file pointed by
path-from
to a file pointed bypath-to
.progress-fn
, if defined, must be a function with a singleparameter: the number of octects wrote in a single call of theTwrite
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
6BUGS
Please send bug reports or patches to the issue tracker.
7License
This library is released under Lisp Lesser General Public license (seeCOPYING.LESSER file)8NO WARRANTY
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.
9Acknowledgment
My deep thanks to op for the support and redfog for the name of the library, Thank you!