Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the purgatory Reference Manual, version 0.1.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 05:56:07 2022 GMT+0.
Next: Systems, Previous: The purgatory Reference Manual, Up: The purgatory Reference Manual [Contents][Index]
#+OPTIONS: html-postamble:nil html-preamble:nil
#+AUTHOR:
#+TITLE: purgatory
* Introduction
This library aims to be an implementation of the 9p file protocol as described in:
https://man.cat-v.org/plan_9/5/intro
* Status
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.
* Prerequisites:
- 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.
* Installation:
The best way to get purgatory working is using the excellent
[[http://www.quicklisp.org/][quicklisp]]
#+BEGIN_SRC common-lisp
(ql:quickload "9p-client")
#+END_SRC
* Usage
A typical usage of the library should starts with a code similar to the one below:
#+BEGIN_SRC common-lisp
(let ((*messages-sent* '())
(*fid* 1)
(*tag* 8)
(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:
- mount :: 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
- 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
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-path :: Open a full, existing, path relative to `root-fid'. `Mode' must be
one of ~+create-for-read+~ ~+create-for-write+~
~+create-for-read-write+"~
- slurp-file :: Read in a vector of (unsigned byte 8) the full content of
'path' relative to `root-fid'
- 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'.
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-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
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-dir-stats :: Sort a list of stat struct `data' (by default sorting entry names
in lexicographic ascending order
- collect-directory-children :: Traverse the file system tree starting at
`starting-directory' returning a list of strings representing the paths of
all 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 *files*
under `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 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]]
* BUGS
Please send bug reports or patches to the [[https://notabug.org/cage/purgatory/issues][issue tracker]].
* License
This library is released under Lisp Lesser General Public license (see
COPYING.LESSER file)
* NO 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.
* Acknowledgment
My deep thanks to op for the support and redfog for the name of the
library, Thank you!
Next: Files, Previous: Introduction, Up: The purgatory Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
A simple implementation of the 9p filesystem protocol.
cage
cage
LLGPL
0.1.2
Next: Packages, Previous: Systems, Up: The purgatory Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: purgatory/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
purgatory (system).
Next: purgatory/text-utils.lisp, Previous: purgatory/purgatory.asd, Up: Lisp [Contents][Index]
purgatory (system).
Next: purgatory/misc-utils.lisp, Previous: purgatory/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
purgatory (system).
strcat (function).
strcat* (function).
Next: purgatory/filesystem-utils.lisp, Previous: purgatory/text-utils.lisp, Up: Lisp [Contents][Index]
text-utils.lisp (file).
purgatory (system).
safe-all-but-last-elt (function).
Next: purgatory/conditions.lisp, Previous: purgatory/misc-utils.lisp, Up: Lisp [Contents][Index]
misc-utils.lisp (file).
purgatory (system).
Next: purgatory/message-types.lisp, Previous: purgatory/filesystem-utils.lisp, Up: Lisp [Contents][Index]
filesystem-utils.lisp (file).
purgatory (system).
9p-error (condition).
Next: purgatory/client.lisp, Previous: purgatory/conditions.lisp, Up: Lisp [Contents][Index]
conditions.lisp (file).
purgatory (system).
Previous: purgatory/message-types.lisp, Up: Lisp [Contents][Index]
message-types.lisp (file).
purgatory (system).
Next: Definitions, Previous: Files, Up: The purgatory Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: purgatory.text-utils, Previous: Packages, Up: Packages [Contents][Index]
common-lisp.
Next: purgatory.filesystem-utils, Previous: purgatory, Up: Packages [Contents][Index]
Next: purgatory.misc-utils, Previous: purgatory.text-utils, Up: Packages [Contents][Index]
common-lisp.
Previous: purgatory.filesystem-utils, Up: Packages [Contents][Index]
common-lisp.
safe-all-but-last-elt (function).
Next: Indexes, Previous: Packages, Up: The purgatory Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Special variables, Previous: Public Interface, Up: Public Interface [Contents][Index]
Next: Macros, Previous: Constants, Up: Public Interface [Contents][Index]
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Useful convenience macro to generate a new fid
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Note: path is relative to root, see attach,
Also note that successfully creating a file will open it.
Note: before opening you have to ’walk’ the file to get the corresponding fid.
Make a new fid that points to the same resource pointed by ‘fid’
Collect all the directory entries of ‘path’ relative to ‘root-fid’ as a list of ‘stat‘ structures.
Traverse the file system tree starting at ‘starting-directory’
returning two values
- a list of strings representing the paths of all the *files*
under ‘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 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.
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))
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.
Decode a serialized file/directory entry in a structure ‘stat’.
A callback that does nothing
A callback that print the data on the standard output, useful for debugging
Initialize the connection to the server using ‘root-path’ as the
root of the remote file system
If ‘username’ is not nil ‘authorization-handshake’ must be a function
of two parameters
- stream
- authorization-fid
The user can write and read to authorization-fid using ‘9p-write’ or
‘9p-read’ to be authorized. If authorized ‘authorization-handshake’
must returns a non nil value. If returns a nil value this is
interpreted as access not granted and ‘mount’ returns nil.
If mount has success two values are returned: the fid of the root file system and the protocol version.
Move the file from ‘path-from‘ ‘path-to‘, this function can be used to rename a file too.
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’)
Open a full, existing, path relative to ‘root-fid’. ‘Mode’ must be one of +create-for-read+, +create-for-write+, +create-for-read-write+
Returns non nil if ‘path’ exists.
If returns non nil values a stat structure representing the element pointed by ‘path’ and a list of stats structures corresponding to the directory of ‘path’.
user.
The responses from the server are not processed immediately, they are collected until this function is called.
Read all the messages from the server and ignore any error
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
(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).
Read an entire file pointed by ‘path’ applying the function ‘read-function’
to three arguments:
- the data chunk as a vector of (unsigned-byte 8);
- the offset to the start of the chunk red;
- the length of the chunk.
Note: ‘path’ is relative to ‘root-fid’
Note also that a failed assertion is signalled if ‘buffer-size’ is
bigger than:
*buffer-size* - +9p-read-header-fixed-size+
Remove the last element of ’path’ relative to ‘root-fid’. If ‘path’ does not exists this function does nothing.
Read in a vector of (unsigned-byte 8) the full content of
’path’ relative to ‘root-fid’
Note: a failed assertion is signalled if ‘buffer-size’ is bigger than:
*buffer-size* - +9p-read-header-fixed-size+
Sort a list of stat struct ‘data’ (by default sorting entry names in lexicographic ascending order
kdev.
mode.
name.
path.
size.
Truncate the size of the element pointed by ‘path’ to the size indicated by the value of ‘new-size’ (default 0). Note that only files could be truncated, not directory.
Next: Conditions, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Previous: Generic functions, Up: Public Interface [Contents][Index]
Error for 9p protocol
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Special variables, Previous: Internals, Up: Internals [Contents][Index]
mode bit for append only files
mode bit for authentication file
mode bit for directories
mode bit for exclusive use files
mode bit for execute permission
mode bit for non-backed-up files
mode bit for mounted channel
mode bit for read permission
mode bit for non-backed-up files
mode bit for non-backed-up files
mode bit for write permission
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Convenience function to convert a vector of bytes to a number using the correct bytes order.
Generate a fresh fid
Next: Conditions, Previous: Ordinary functions, Up: Internals [Contents][Index]
idx.
rtag.
Return sequence if position is out of bound
seq.
text.
Next: Structures, Previous: Generic functions, Up: Internals [Contents][Index]
Error for 9p protocol in the authorization phase.
error.
:connection-data
This slot is read-only.
Error for 9p protocol in the initialization phase.
Error when you go out of bound
error.
Error that set text
error.
text.
Next: Classes, Previous: Conditions, Up: Internals [Contents][Index]
structure-object.
purgatory::+wstat-ignore-4+
structure-object.
purgatory::+wstat-ignore-2+
purgatory::+wstat-ignore-2+
purgatory::+wstat-ignore-4+
:do-not-care
purgatory::+wstat-ignore-4+
purgatory::+wstat-ignore-8+
(purgatory:make-permissions)
purgatory::+wstat-ignore-4+
purgatory::+wstat-ignore-4+
purgatory::+wstat-ignore-8+
""
""
""
""
Previous: Definitions, Up: The purgatory Reference Manual [Contents][Index]
| Jump to: | %
(
9
A B C D E F G I L M N O P R S T U V W |
|---|
| Jump to: | %
(
9
A B C D E F G I L M N O P R S T U V W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
+
A C E G I K L M N O P R S T U V |
|---|
| Jump to: | *
+
A C E G I K L M N O P R S T U V |
|---|
| Jump to: | 9
C F M O P S T |
|---|
| Jump to: | 9
C F M O P S T |
|---|