Module type Styx.Filesystem

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.

A file refers to a single file, which may or may not be prepared for I/O. At any given time, there may be multiple file values that refer to the same underlying file, each with its own options and capabilities. One file value is associated with a single user session, and should carry sufficient information to check permissions for each file operation.

init is called before the server begins running, and *must* return an Ok result before the server will start answering client requests.

lookup dir name finds the file with filename name in the directory dir. dir must be a directory, and the user must have read permission to it.

attr file qid sets the relevant attributes for file in qid. It must succeed, so it is advisable to store sufficient information in the file type to populate qid. The Qid module can be used to write to qid.

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.

attach ~uname ~aname initiates a new user session for the user uname to the root filesystem aname. It should return the root directory for aname.

openfile prepares a file for I/O with the provided options. The returned file can be passed as an argument to the read or write functions.

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.

read ~offset ~buf retrieves data in the file from the range [offset .. Iovec.length buf) and writes it into buf. 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.

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.

close file ends I/O for file. 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 from close.

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.

stat writes metadata for the file into the buffer. The Stat.write function can be used to write the structure. on success, stat returns the number of bytes written to the buffer.

wstat updates metadata for a file. Some fields in the stat structure may be unset -- the Stat.update function can be used to update an existing stat while ignoring unset fields.

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. While cleanup 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.