Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the purgatory Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 05:53:05 2022 GMT+0.
| • Introduction | What purgatory is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
#+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* '())
(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: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The purgatory system |
cage
cage
LLGPL
A simple implementation of the 9p filesystem protocol.
0.1.0
purgatory.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The purgatory/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
/home/quickref/quicklisp/dists/quicklisp/software/purgatory-20220220-git/purgatory.asd
purgatory (system)
Next: The purgatory/text-utils․lisp file, Previous: The purgatory․asd file, Up: Lisp files [Contents][Index]
purgatory (system)
package.lisp
Next: The purgatory/misc-utils․lisp file, Previous: The purgatory/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
purgatory (system)
text-utils.lisp
strcat (function)
strcat* (function)
Next: The purgatory/filesystem-utils․lisp file, Previous: The purgatory/text-utils․lisp file, Up: Lisp files [Contents][Index]
text-utils.lisp (file)
purgatory (system)
misc-utils.lisp
safe-all-but-last-elt (function)
Next: The purgatory/conditions․lisp file, Previous: The purgatory/misc-utils․lisp file, Up: Lisp files [Contents][Index]
misc-utils.lisp (file)
purgatory (system)
filesystem-utils.lisp
Next: The purgatory/message-types․lisp file, Previous: The purgatory/filesystem-utils․lisp file, Up: Lisp files [Contents][Index]
filesystem-utils.lisp (file)
purgatory (system)
conditions.lisp
9p-error (condition)
Next: The purgatory/client․lisp file, Previous: The purgatory/conditions․lisp file, Up: Lisp files [Contents][Index]
conditions.lisp (file)
purgatory (system)
message-types.lisp
Previous: The purgatory/message-types․lisp file, Up: Lisp files [Contents][Index]
message-types.lisp (file)
purgatory (system)
client.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The purgatory.misc-utils package | ||
| • The purgatory.filesystem-utils package | ||
| • The purgatory.text-utils package | ||
| • The purgatory package |
Next: The purgatory․filesystem-utils package, Previous: Packages, Up: Packages [Contents][Index]
package.lisp (file)
common-lisp
safe-all-but-last-elt (function)
Next: The purgatory․text-utils package, Previous: The purgatory․misc-utils package, Up: Packages [Contents][Index]
package.lisp (file)
common-lisp
Next: The purgatory package, Previous: The purgatory․filesystem-utils package, Up: Packages [Contents][Index]
package.lisp (file)
common-lisp
strcat (function)
strcat* (function)
Previous: The purgatory․text-utils package, Up: Packages [Contents][Index]
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported constants | ||
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported conditions |
Next: Exported special variables, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
Next: Exported macros, Previous: Exported constants, Up: Exported definitions [Contents][Index]
client.lisp (file)
filesystem-utils.lisp (file)
client.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Useful convenience macro to generate a new fid
client.lisp (file)
client.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
client.lisp (file)
client.lisp (file)
Note: path is relative to root, see attach,
Also note that successfully creating a file will open it.
client.lisp (file)
Note: before opening you have to ’walk’ the file to get the corresponding fid.
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
filesystem-utils.lisp (file)
filesystem-utils.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
Make a new fid that points to the same resource pointed by ‘fid’
client.lisp (file)
client.lisp (file)
Collect all the directory entries of ‘path’ relative to ‘root-fid’ as a list of ‘stat‘ structures.
client.lisp (file)
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).
client.lisp (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.
client.lisp (file)
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))
client.lisp (file)
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.
client.lisp (file)
client.lisp (file)
Decode a serialized file/directory entry in a structure ‘stat’.
client.lisp (file)
A callback that does nothing
client.lisp (file)
A callback that print the data on the standard output, useful for debugging
client.lisp (file)
client.lisp (file)
filesystem-utils.lisp (file)
client.lisp (file)
filesystem-utils.lisp (file)
client.lisp (file)
client.lisp (file)
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.
client.lisp (file)
Move the file from ‘path-from‘ ‘path-to‘, this function can be used to rename a file too.
client.lisp (file)
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’)
client.lisp (file)
Open a full, existing, path relative to ‘root-fid’. ‘Mode’ must be one of +create-for-read+, +create-for-write+, +create-for-read-write+
client.lisp (file)
filesystem-utils.lisp (file)
Returns non nil if ‘path’ exists.
client.lisp (file)
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’.
client.lisp (file)
filesystem-utils.lisp (file)
filesystem-utils.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
The responses from the server are not processed immediately, they are collected until this function is called.
client.lisp (file)
Read all the messages from the server and ignore any error
client.lisp (file)
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).
client.lisp (file)
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+
client.lisp (file)
client.lisp (file)
Remove the last element of ’path’ relative to ‘root-fid’. If ‘path’ does not exists this function does nothing.
client.lisp (file)
misc-utils.lisp (file)
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+
client.lisp (file)
Sort a list of stat struct ‘data’ (by default sorting entry names in lexicographic ascending order
client.lisp (file)
filesystem-utils.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
text-utils.lisp (file)
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.
client.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
Encode an octect to be trasmitted on the stream
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Error for 9p protocol
conditions.lisp (file)
error (condition)
:error-value
error-value (generic function)
:message-type
message-type (generic function)
:tag
tag (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal constants | ||
| • Internal special variables | ||
| • Internal macros | ||
| • Internal functions | ||
| • Internal generic functions | ||
| • Internal conditions | ||
| • Internal structures | ||
| • Internal classes |
Next: Internal special variables, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
client.lisp (file)
client.lisp (file)
filesystem-utils.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
mode bit for append only files
client.lisp (file)
mode bit for authentication file
client.lisp (file)
mode bit for directories
client.lisp (file)
mode bit for exclusive use files
client.lisp (file)
mode bit for execute permission
client.lisp (file)
mode bit for non-backed-up files
client.lisp (file)
mode bit for mounted channel
client.lisp (file)
mode bit for read permission
client.lisp (file)
mode bit for non-backed-up files
client.lisp (file)
mode bit for non-backed-up files
client.lisp (file)
mode bit for write permission
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
Next: Internal macros, Previous: Internal constants, Up: Internal definitions [Contents][Index]
filesystem-utils.lisp (file)
client.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
client.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
message-types.lisp (file)
client.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
misc-utils.lisp (file)
misc-utils.lisp (file)
client.lisp (file)
client.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
Convenience function to convert a vector of bytes to a number using the correct bytes order.
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
Generate a fresh fid
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
text-utils.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
client.lisp (file)
Next: Internal conditions, Previous: Internal functions, Up: Internal definitions [Contents][Index]
client.lisp (file)
conditions.lisp (file)
misc-utils.lisp (file)
conditions.lisp (file)
misc-utils.lisp (file)
conditions.lisp (file)
client.lisp (file)
conditions.lisp (file)
Return sequence if position is out of bound
misc-utils.lisp (file)
misc-utils.lisp (file)
automatically generated reader method
client.lisp (file)
automatically generated writer method
client.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
misc-utils.lisp (file)
automatically generated reader method
client.lisp (file)
automatically generated writer method
client.lisp (file)
Next: Internal structures, Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
Error for 9p protocol in the authorization phase.
conditions.lisp (file)
error (condition)
connection-data (method)
:connection-data
connection-data (generic function)
Error for 9p protocol in the initialization phase.
Error when you go out of bound
misc-utils.lisp (file)
error (condition)
:seq
seq (generic function)
:idx
idx (generic function)
Error that set text
misc-utils.lisp (file)
error (condition)
text (method)
:text
text (generic function)
Next: Internal classes, Previous: Internal conditions, Up: Internal definitions [Contents][Index]
client.lisp (file)
structure-object (structure)
encode (method)
permissions-user (function)
(setf permissions-user) (function)
permissions-group (function)
(setf permissions-group) (function)
permissions-others (function)
(setf permissions-others) (function)
permissions-user-string (function)
(setf permissions-user-string) (function)
permissions-group-string (function)
(setf permissions-group-string) (function)
permissions-others-string (function)
(setf permissions-others-string) (function)
purgatory::+wstat-ignore-4+
permissions-original-value (function)
(setf permissions-original-value) (function)
client.lisp (file)
structure-object (structure)
purgatory::+wstat-ignore-2+
stat-entry-size (function)
(setf stat-entry-size) (function)
purgatory::+wstat-ignore-2+
stat-ktype (function)
(setf stat-ktype) (function)
purgatory::+wstat-ignore-4+
stat-kdev (function)
(setf stat-kdev) (function)
:do-not-care
stat-entry-type (function)
(setf stat-entry-type) (function)
purgatory::+wstat-ignore-4+
stat-version (function)
(setf stat-version) (function)
purgatory::+wstat-ignore-8+
stat-path (function)
(setf stat-path) (function)
(purgatory:make-permissions)
stat-mode (function)
(setf stat-mode) (function)
purgatory::+wstat-ignore-4+
stat-atime (function)
(setf stat-atime) (function)
purgatory::+wstat-ignore-4+
stat-mtime (function)
(setf stat-mtime) (function)
purgatory::+wstat-ignore-8+
stat-size (function)
(setf stat-size) (function)
""
stat-name (function)
(setf stat-name) (function)
""
stat-user-id (function)
(setf stat-user-id) (function)
""
stat-group-id (function)
(setf stat-group-id) (function)
""
stat-last-modified-from-id (function)
(setf stat-last-modified-from-id) (function)
Previous: Internal structures, Up: Internal definitions [Contents][Index]
client.lisp (file)
standard-object (class)
:value
0
value (generic function)
(setf value) (generic function)
:size
0
size (generic function)
(setf size) (generic function)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L P |
|---|
| Jump to: | F L P |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [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 type index, Previous: Function index, 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 |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | 9
C O P S T |
|---|
| Jump to: | 9
C O P S T |
|---|