Parameter Server.1-FS
type t
A
t
represents an active instance of the filesystem and should contain the needed information to start a new user session, such as the location of the data in storage and any configuration directives.
type file
A
file
refers to a single file, which may or may not be prepared for I/O. At any given time, there may be multiplefile
values that refer to the same underlying file, each with its own options and capabilities. Onefile
value is associated with a single user session, and should carry sufficient information to check permissions for each file operation.
val init : t -> (t, error) Stdlib.result
init
is called before the server begins running, and *must* return an Ok result before the server will start answering client requests.
val lookup : file -> string -> (file, error) Stdlib.result
lookup dir name
finds the file with filenamename
in the directorydir
.dir
must be a directory, and the user must have read permission to it.
val attr : file -> Qid.t -> unit
attr file qid
sets the relevant attributes forfile
inqid
. It must succeed, so it is advisable to store sufficient information in thefile
type to populateqid
. TheQid
module can be used to write toqid
.
val iounit : file -> int
iounit file
is maximum number of bytes that this filesystem can write to a file in a single request. If this value is 0, the 9P server will calculate the iounit based on the maximum message size. It may be desirable to restrict I/O sizes to some value based on the characteristics of the underlying storage (for instance, to match some block or page size). This is a hint, not a limit; Filesystems should be prepared to receive requests larger or smaller than the iounit, but are free to only fulfill them partially.
val attach : t -> uname:string -> aname:string -> (file, error) Stdlib.result
attach ~uname ~aname
initiates a new user session for the useruname
to the root filesystemaname
. It should return the root directory foraname
.
val openfile : file -> flags:Flag.t -> (file, error) Stdlib.result
openfile
prepares a file for I/O with the provided options. The returnedfile
can be passed as an argument to theread
orwrite
functions.
val create : file -> name:string -> flags:Flag.t -> (file, error) Stdlib.result
create
makes a new file as a child of an existing directory, with the provided options. The requesting user must have write access to the parent directory, and there should be no other file with the same name in the directory.
val read : file -> offset:int -> buf:Iovec.t -> (int, error) Stdlib.result
read ~offset ~buf
retrieves data in the file from the range[offset .. Iovec.length buf)
and writes it intobuf
. It is not required to retrieve the full requested range from the file, and it is preferred to give a short read rather than to wait for more data to become available. Clients may treat a short read as an end-of-file condition.
val write : file -> offset:int -> buf:Iovec.t -> (int, error) Stdlib.result
write
persists data from buf to the specified range in the file. It should return the number of bytes recorded. It is not required to record the full input; clients shall verify the response and resend any dropped data if necessary.
val close : file -> (unit, error) Stdlib.result
close file
ends I/O forfile
. If the file was opened with the ORCLOSE flag, it can be removed. If the file system uses a buffer for writes, any pending data should be flushed before returning fromclose
.
val remove : file -> (unit, error) Stdlib.result
remove
deletes the referenced file. Other open references to the same file should continue to allow I/O as long as they remain open.remove
requires write access to a file's parent directory.
val stat : file -> Iovec.t -> (int, error) Stdlib.result
stat
writes metadata for the file into the buffer. TheStat.write
function can be used to write the structure. on success,stat
returns the number of bytes written to the buffer.
val wstat : file -> Stat.t -> (unit, error) Stdlib.result
wstat
updates metadata for a file. Some fields in the stat structure may be unset -- theStat
.update function can be used to update an existing stat while ignoring unset fields.
val cleanup : t -> (unit, error) Stdlib.result
cleanup
is called before the server process exits, and should be used to gracefully release any resources the file system may consume or flush any data structures to persistent storage. Whilecleanup
will be called if the process exits on its own, it is not guaranteed to be called in all cases; the host operating system may crash, the host machine may fail, or the running process may be killed. The file system should implement some procedure for restoring consistency in the event of an ungraceful shutdown.