On this page:
filesystem<%>
authenticate
attach
clunk
file-handle<%>
walk
read-stat
write-stat
open
read
write
clunk
remove
directory-handle<%>
in-entries
create

3 Common Interfaces

 (require (planet "interface.rkt" ("murphy" "9p.plt" 2 0)))
This module contains interfaces that are implemented both on the client and server side of the 9P protocol. Client and server side file and directory handle objects can be used interchangeably if they are only accessed through these interfaces.

filesystem<%> : interface?

(send a-filesystem authenticate root 
  #:user user) 
  (is-a?/c file-handle<%>)
  root : string?
  user : string?
Opens an authentication channel suitable as a token when attaching to the filesystem root directory root as the given user.

This method may raise an exception if the filesystem does not require authentication. If an authentication channel is returned, it will likely be necessary to complete some challenge response protocol over that channel before it can be used as an authentication token.

(send a-filesystem attach root 
  #:user user 
  #:token auth) 
  (is-a?/c directory-handle<%>)
  root : string?
  user : string?
  auth : (or/c (is-a?/c file-handle<%>) #f)
Opens the filesystem root directory root as the given user. Authentication context is optionally provided by the file handle auth.

(send a-filesystem clunk)  void?
Drops the connection to the whole filesystem.

file-handle<%> : interface?

(send a-file-handle walk name ...)  (is-a?/c file-handle<%>)
  name : string?
Moves from the file represented by this handle to a different file and returns a file handle for the target. The given name arguments define the path to take to the target: ".." stands for the parent directory of the current file, any other string is the name of a file or directory to move to.

You can usually walk from any file to itself calling walk with no arguments or to its parent directory calling walk with a single ".." argument, but walking to named children normally only works for directories.

(send a-file-handle read-stat)  stat?
Obtains the directory entry information for a file.

(send a-file-handle write-stat stat)  void?
  stat : stat?
Changes the directory entry information for a file. Only the fields stat-mode, stat-mtime, stat-length, stat-name and stat-gid can be changed at all, any other field should be set to #f. The directory bit in the stat-mode field cannot be changed. The stat-length field, if it is set at all, can only be set to zero, truncating the file.

In addition to the basic parameter validation, the file server may perform permission checks to determine if a change is allowed.

If the method does not raise an exception, all of the requested changes have been performed by the file server, otherwise nothing should have changed.

(send a-file-handle open mode)  natural-number/c
  mode : natural-number/c
Opens the file for reading or writing data and returns the maximum I/O unit size. The mode argument is a combination of flags as it can be produced by the open-mode macro.

(send a-file-handle read size offset)
  (or/c bytes? eof-object?)
  size : natural-number/c
  offset : natural-number/c
Reads data from the file after it has been opened for reading. The returned data should be at most size bytes long.

(send a-file-handle write data offset)  natural-number/c
  data : bytes?
  offset : natural-number/c
Writes data to the file after it has been opened for writing. The return value is the number of bytes actually written.

(send a-file-handle clunk)  void?
Closes the file if it is open and invalidates the file handle. Even if this method signals an error, the file handle is still invalid after the call.

(send a-file-handle remove)  void?
Closes the file if it is open, removes it from the storage device and invalidates the file handle. Even if this method signals an error, the file handle is still invalid after the call.

directory-handle<%> : interface?
  implements: file-handle<%>

(send a-directory-handle in-entries)  sequence?
Returns an iterable sequence of directory entries.

(send a-directory-handle create name 
  perm 
  mode) 
  
(is-a?/c file-handle<%>) natural-number/c
  name : string?
  perm : natural-number/c
  mode : natural-number/c
Creates a new entry in the directory. The type of the new file and its access permissions are determined by perm. You can pass a value computed using the macro file-mode here.

If the newly created file is not a directory, it is immediately open for I/O operations with the given mode. The open mode is not checked against the permissions of the new file. You can pass a value computed using the macro open-mode here.

In case of success, the method returns both a new file handle and an I/O unit value.