On this page:
4.1 Filesystem
client-filesystem%
authenticate
attach
clunk
call-with-tag
call-with-tag+ fid
request
fid->file
4.2 File Handles
client-file-handle%
walk
read-stat
write-stat
offset
open
read
write
clunk
remove
->fid
call-with-tag
call-with-tag+ fid
request
fid->file
client-directory-handle%
in-entries
create
4.3 Additional Utilities
file-handle->input-port
file-handle->output-port
9p-open-input-file
call-with-9p-input-file
call-with-9p-input-file*
with-input-from-9p-file
9p-open-output-file
call-with-9p-output-file
call-with-9p-output-file*
with-output-to-9p-file

4 Client

 (require (planet "client.ss" ("murphy" "9p.plt" 1 0)))
This module re-exports all bindings from the "client/filesystem.ss", "client/handle.ss" and "client/util.ss" modules.

4.1 Filesystem

 (require (planet "filesystem.ss" ("murphy" "9p.plt" 1 0) "client"))
Implementation of the filesystem<%> interface for the client side.

client-filesystem% : class?

  superclass: object%

  extends: filesystem<%>
Client side 9P filesystem representation.

(new client-filesystem% [hostname hostname] 
  [[port-no port-no] 
  [local-hostname local-hostname] 
  [local-port-no local-port-no]]) 
  (is-a?/c client-filesystem%)
  hostname : string?
  port-no : (integer-in 1 65535) = 564
  local-hostname : (or/c string? #f) = #f
  local-port-no : (or/c (integer-in 1 65535) #f) = #f
Connects to the 9P server at hostname and port-no via TCP and starts a client event loop.

(send a-client-filesystem authenticate [root 
  #:user user]) 
  (is-a?/c client-file-handle%)
  root : string? = ""
  user : string? = (or (getenv "USER") "nobody")
Opens an authentication channel for the given user suitable to attach to the filesystem root directory root.

(send a-client-filesystem attach [root 
  #:user user 
  #:token auth]) 
  (is-a?/c client-directory-handle%)
  root : string? = ""
  user : string? = (or (getenv "USER") "nobody")
  auth : (is-a?/c client-file-handle%) = #f
Attaches to the filesystem root directory root as the given user, optionally providing an authentication token auth.

(send a-client-filesystem clunk)  void?
Refine this method with augment.
Stops the client event loop and implicitly clunks all file handles still referencing files on the 9P server.

(send a-client-filesystem call-with-tag proc)  any
  proc : (-> (box/c (or/c natural-number/c #f)) any)
Applies proc to a box that is a suitable value to be included in a 9P protocol message as a tag. Returns whatever proc returns.

(send a-client-filesystem call-with-tag+fid proc)  any
  proc : 
(-> (box/c (or/c natural-number/c #f))
    (box/c (or/c natural-number/c #f))
    any)
Applies proc to two boxes that are suitable values to be included in a 9P protocol message as a tag and a new file identifier. Returns whatever proc returns.

If proc throws an exception and the file identifier box already contains an allocated identifier, that identifier is automatically freed for reuse.

(send a-client-filesystem request message)  message:r?
  message : message:t?
Sends a request message to the server this client is connected to or throws an exception if the connection has already been terminated.

Returns the response to the request.

(send a-client-filesystem fid->file fid 
  qid 
  [offset]) 
  (is-a?/c client-file-handle%)
  fid : natural-number/c
  qid : qid?
  offset : (or/c natural-number/c #f) = #f
Refine this method with augment.
Wraps a file identifier into a client file handle. If an offset is specified, the file identifier refers to an already open file.

Augmenting this method can be used to replace the default logic that simply returns a newly allocated instance of client-file-handle% or client-directory-handle% depending on the type flags in the qid.

The method always ensures that the returned file handle is automatically clunked before it is garbage collected.

4.2 File Handles

 (require (planet "handle.ss" ("murphy" "9p.plt" 1 0) "client"))
Implementations of the file-handle<%> and directory-handle<%> interfaces for the client side.

client-file-handle% : class?

  superclass: object%

  extends: file-handle<%>
Client side access object for a file on a 9P server.

(new client-file-handle% [fs fs] 
  [fid fid] 
  [[current-offset current-offset]]) 
  (is-a?/c client-file-handle%)
  fs : (is-a?/c client-filesystem%)
  fid : natural-number/c
  current-offset : (or/c natural-number/c #f) = #f
Creates a new file handle that refers to the file identifier fid in the context of the 9P connection represented by the filesystem object fs.

An optional offset determines whether the file is considered open.

(send a-client-file-handle walk name ...)
  (is-a?/c client-file-handle%)
  name : string?
Overrides <method not found>. This method is final, so it cannot be overiddden.
Moves from the file represented by this handle to a different file and returns a file handle for the target.

(send a-client-file-handle read-stat)  stat?
Overrides <method not found>. This method is final, so it cannot be overiddden.
Obtains the directory entry information for a file.

(send a-client-file-handle write-stat stat)  void?
  stat : stat?
Overrides <method not found>. This method is final, so it cannot be overiddden.
Changes the directory entry information for a file.

(send a-client-file-handle offset)
  (or/c natural-number/c #f)
(send a-client-file-handle offset new-offset)  void?
  new-offset : natural-number/c
Retrieves or changes the current file offset that is used as a default when read or write are called without an explicit offset.

If the file is not open, this method returns #f, if the handle has already been invalidated the method raises a filesystem exception.

(send a-client-file-handle open mode)  natural-number/c
  mode : natural-number/c
Overrides <method not found>. This method is final, so it cannot be overiddden.
Opens the file for reading or writing data.

(send a-client-file-handle read size 
  [offset]) 
  (or/c bytes? eof-object?)
  size : natural-number/c
  offset : natural-number/c = (offset)
Overrides <method not found>. This method is final, so it cannot be overiddden.
Reads data from the file after it has been opened for reading. Advances the default offset by the number of bytes actually read.

(send a-client-file-handle write data    
  [offset])  natural-number/c
  data : bytes?
  offset : natural-number/c = (offset)
Overrides <method not found>. This method is final, so it cannot be overiddden.
Writes data to the file after it has been opened for writing. Advances the default offset by the number of bytes actually written.

(send a-client-file-handle clunk)  void?
Overrides <method not found>.
Refine this method with augment. A refinement will also be called if the file is removed using remove.

Closes the file if it is open and invalidates the file handle.

(send a-client-file-handle remove)  void?
Overrides <method not found>. This method is final, so it cannot be overiddden.
Closes the file if it is open, removes it from the storage device and invalidates the file handle.

(send a-client-file-handle ->fid)  natural-number/c
Converts the file handle into the underlying file identifier. Raises a filesystem exception if the handle has already been invalidated.

(send a-client-file-handle call-with-tag proc)  any
  proc : (-> (box/c (or/c natural-number/c #f)) any)
This message is forwarded to the underlying filesystem object. See call-with-tag for more information.

(send a-client-file-handle call-with-tag+fid proc)  any
  proc : 
(-> (box/c (or/c natural-number/c #f))
    (box/c (or/c natural-number/c #f))
    any)
This message is forwarded to the underlying filesystem object. See call-with-tag+fid for more information.

(send a-client-file-handle request message)  message:r?
  message : message:t?
This message is forwarded to the underlying filesystem object. See request for more information.

(send a-client-file-handle fid->file fid 
  qid 
  offset) 
  (is-a?/c client-file-handle%)
  fid : natural-number/c
  qid : qid?
  offset : #f
This message is forwarded to the underlying filesystem object. See fid->file for more information.

client-directory-handle% : class?

  superclass: client-file-handle%

  extends: directory-handle<%>
Client side access object for a directory on a 9P server.

(new client-directory-handle% ...superclass-args...)
  (is-a?/c client-directory-handle%)
Creates a new directory handle.

(send a-client-directory-handle in-entries)  sequence?
Overrides <method not found>.
Returns an iterable sequence of directory entries.

(send a-client-directory-handle create name 
  perm 
  mode) 
  
(is-a?/c client-file-handle%)
natural-number/c
  name : string?
  perm : natural-number/c
  mode : natural-number/c
Overrides <method not found>. This method is final, so it cannot be overiddden.
Creates a new entry in the directory.

4.3 Additional Utilities

 (require (planet "util.ss" ("murphy" "9p.plt" 1 0) "client"))
Convenience functions to convert from file handles to ports and to access files on a 9P server in a similar fashion as files in the local file system.

(file-handle->input-port handle [name])  input-port?
  handle : (is-a?/c file-handle<%>)
  name : any/c = 
(string->some-system-path
 (stat-name (send handle read-stat))
 'unix)
Converts an open file handle into an input port. Closing the input port clunks the file handle.

(file-handle->output-port handle [name])  output-port?
  handle : (is-a?/c file-handle<%>)
  name : any/c = 
(string->some-system-path
 (stat-name (send handle read-stat))
 'unix)
Converts an open file handle into an output port. Closing the output port clunks the file handle.

(9p-open-input-file anchor path)  input-port?
  anchor : (is-a?/c directory-handle<%>)
  path : (and/c path-string? relative-path?)
Walks from the 9P directory handle anchor along the given path to another file, opens the handle representing that file for reading and converts it into an input port that is returned.

(call-with-9p-input-file anchor path proc)  any
  anchor : (is-a?/c directory-handle<%>)
  path : (and/c path-string? relative-path?)
  proc : (-> input-port? any)
Like call-with-input-file but using 9p-open-input-file to open the file.

(call-with-9p-input-file* anchor path proc)  any
  anchor : (is-a?/c directory-handle<%>)
  path : (and/c path-string? relative-path?)
  proc : (-> input-port? any)
Like call-with-input-file* but using 9p-open-input-file to open the file.

(with-input-from-9p-file anchor path proc)  any
  anchor : (is-a?/c directory-handle<%>)
  path : (and/c path-string? relative-path?)
  proc : (-> any)
Like with-input-from-file but using 9p-open-input-file to open the file.

(9p-open-output-file anchor    
  path    
  [#:exists exists-flag    
  #:permissions perm])  output-port?
  anchor : (is-a?/c directory-handle<%>)
  path : (and/c path-string? relative-path?)
  exists-flag : (symbols 'error 'append 'update 'replace 'truncate 'truncate/replace)
   = 'error
  perm : natural-number/c
   = (file-mode (type file) (user r w) (group r) (others r))
Walks from the 9P directory handle anchor along the given path to the parent of another file, tries to walk the final step to the target file and acts depending on the value of exists-flag. See open-output-file for details how this flag is handled.

If a new file is created by 9p-open-output-file, it is given the type and permissions perm.

(call-with-9p-output-file anchor    
  path    
  proc    
  [#:exists exists-flag    
  #:permissions perm])  any
  anchor : (is-a?/c directory-handle<%>)
  path : (and/c path-string? relative-path?)
  proc : (-> output-port? any)
  exists-flag : (symbols 'error 'append 'update 'replace 'truncate 'truncate/replace)
   = 'error
  perm : natural-number/c
   = (file-mode (type file) (user r w) (group r) (others r))
Like call-with-output-file but using 9p-open-output-file to open the file.

(call-with-9p-output-file* anchor    
  path    
  proc    
  [#:exists exists-flag    
  #:permissions perm])  any
  anchor : (is-a?/c directory-handle<%>)
  path : (and/c path-string? relative-path?)
  proc : (-> output-port? any)
  exists-flag : (symbols 'error 'append 'update 'replace 'truncate 'truncate/replace)
   = 'error
  perm : natural-number/c
   = (file-mode (type file) (user r w) (group r) (others r))
Like call-with-output-file* but using 9p-open-output-file to open the file.

(with-output-to-9p-file anchor    
  path    
  proc    
  [#:exists exists-flag    
  #:permissions perm])  any
  anchor : (is-a?/c directory-handle<%>)
  path : (and/c path-string? relative-path?)
  proc : (-> any)
  exists-flag : (symbols 'error 'append 'update 'replace 'truncate 'truncate/replace)
   = 'error
  perm : natural-number/c
   = (file-mode (type file) (user r w) (group r) (others r))
Like with-output-to-file but using 9p-open-output-file to open the file.