Skip to content

<fs/fsd_client.h>

Minimal client for the fsd protocol.

fsd requires the client to own the shared buffer: create it and grant it to fsd with FSD_ATTACH, which returns a badged port for the session. This header wraps that handshake and the per-command request/response marshalling so callers (zzsh, ...) don't each re-implement it.

#include <fs/fsd_client.h>

Structures

FsdConn

A session with fsd.

Field Type Description
port Handle Badged handle to fsd's port: the session.
shm Handle The shared buffer's memory object.
buf uint8_t * Mapped shared buffer.
size uint32_t Buffer size, page-aligned.
live Handle Port this client owns; fsd watches it to notice the client's death.
ready bool Whether the session is attached.

Functions

FsdAttach

Err FsdAttach(FsdConn *c, Handle port, Spid pid, uint32_t want_size);

Attaches a client's shared buffer to an already-resolved fsd port.

Parameter Direction Description
c inout The connection state to initialize.
port in Unmarked handle to fsd's port; the caller keeps ownership.
pid in Unused; kept for source compatibility.
want_size in Requested shared buffer size; clamped to [FSD_SHM_MIN, FSD_SHM_MAX] and page-aligned.

Returns: ZUZU_OK, or an error code.

FsdConnect

Err FsdConnect(FsdConn *c, uint32_t want_size);

Establishes a session by resolving fsd over the nameserver, then attaching.

For ordinary clients.

Parameter Direction Description
c inout The connection state to initialize.
want_size in Requested shared buffer size; see FsdAttach().

Returns: ZUZU_OK, or an error code.

FsdDetach

Err FsdDetach(FsdConn *c);

Ends the session: fsd closes the fds it owns and frees the session.

Parameter Direction Description
c inout An attached connection.

Returns: ZUZU_OK, or an error code.

FsdOpen

Err FsdOpen(FsdConn *c, const char *path, uint32_t mode, uint32_t *fd);

Opens a file by path.

Parameter Direction Description
c inout An attached connection.
path in Path to open.
mode in FSD_MODE_* flags.
fd out Receives the opened file descriptor on success.

Returns: ZUZU_OK, or an error code.

FsdClose

Err FsdClose(FsdConn *c, uint32_t fd);

Closes a file descriptor previously returned by FsdOpen().

Parameter Direction Description
c inout An attached connection.
fd in The file descriptor to close.

Returns: ZUZU_OK, or an error code.

FsdRead

Err FsdRead(FsdConn *c, uint32_t fd, void *dst, uint32_t count, uint32_t *got);

Reads up to count bytes from fd into dst.

Parameter Direction Description
c inout An attached connection.
fd in The file descriptor to read from.
dst out Destination buffer; may be NULL to discard the data.
count in Maximum number of bytes to read.
got out Receives the number of bytes actually read.

Returns: ZUZU_OK, or an error code.

FsdReadObj

Err FsdReadObj(FsdConn *c, uint32_t fd, Handle obj, uint32_t obj_off, uint32_t count, uint32_t *got);

Reads up to count bytes from fd straight into a shm object, at byte offset obj_off, with no copy through the session buffer.

Parameter Direction Description
c inout An attached connection.
fd in The file descriptor to read from.
obj in A memory object you own; fsd gets a PERM_MAP | PERM_WRITE copy for the call.
obj_off in Byte offset into the object where the data goes.
count in Maximum number of bytes to read; obj_off + count must fit in the object.
got out Receives the number of bytes actually read.

Returns: ZUZU_OK, or an error code.

FsdWrite

Err FsdWrite(FsdConn *c, uint32_t fd, const void *src, uint32_t count, uint32_t *put);

Writes up to count bytes from src to fd.

Parameter Direction Description
c inout An attached connection.
fd in The file descriptor to write to.
src in Source buffer.
count in Maximum number of bytes to write.
put out Receives the number of bytes actually written.

Returns: ZUZU_OK, or an error code.

FsdSeek

Err FsdSeek(FsdConn *c, uint32_t fd, int64_t offset, uint32_t whence, int64_t *newpos);

Repositions the file offset of fd.

Parameter Direction Description
c inout An attached connection.
fd in The file descriptor.
offset in Offset relative to whence.
whence in An FsdWhence value.
newpos out Receives the new absolute position; may be NULL.

Returns: ZUZU_OK, or an error code.

Err FsdUnlink(FsdConn *c, const char *path);

Removes a file or empty directory.

Parameter Direction Description
c inout An attached connection.
path in Path to remove.

Returns: ZUZU_OK, or an error code.

FsdGetStat

Err FsdGetStat(FsdConn *c, const char *path, FsdStat *st);

Stats a file by path.

Parameter Direction Description
c inout An attached connection.
path in Path to stat.
st out Receives the file's stat info.

Returns: ZUZU_OK, or an error code.

FsdFstat

Err FsdFstat(FsdConn *c, uint32_t fd, FsdStat *st);

Stats an open file by descriptor.

Parameter Direction Description
c inout An attached connection.
fd in The file descriptor.
st out Receives the file's stat info.

Returns: ZUZU_OK, or an error code.

FsdReadDir

Err FsdReadDir(FsdConn *c, const char *path, uint32_t start, FsdDirEntry *out, uint32_t max, uint32_t *count);

Reads directory entries starting at start.

Parameter Direction Description
c inout An attached connection.
path in Directory path.
start in Index of the first entry to return.
out out Destination array of entries.
max in Capacity of out, in entries.
count out Receives the number of entries actually returned.

Returns: ZUZU_OK, or an error code.

FsdReadImage

Err FsdReadImage(FsdConn *c, const char *path, Handle *obj, size_t *len);

Reads a whole regular file into a fresh shm object, e.g.

a program image for SpawnProcessObj().

Parameter Direction Description
c inout An attached connection.
path in Path of the file to read.
obj out Receives the new object's handle on success; the caller closes it.
len out Receives the file size in bytes on success.

Returns: ZUZU_OK, or an error code.

Error Condition
ERR_BADARG path is not a non-empty regular file.
ERR_IO The file ended before its stated size.