volumes::read

Tag 5: a client names a volume from its listing and one file in it; the server sends the bytes of the file as responses of at most CHUNK_SIZE bytes each and the finish, or an error last, while the volume is mounted nowhere.

A client opens the scope with a request whose payload is the tag byte 5 followed by the name of a volume and the path of one file in it. The server sends the bytes of the file as zero or more responses and the response finish, or the responses sent so far, exactly one error response and the response finish. Neither party opens a channel on a read scope.

The request. The request carries the name of one volume and the path of one file. Request states its form.
The volume named. The client names a volume by the name its volumes::list listing gave it. The server resolves the name against the identity under which the connection was authorized, as Authorization provides. A name that is not in the client’s listing is answered with an error. A client cannot name another client’s volume.
The path. The path is a sequence of components from the root of the volume: the same components a volume mount’s volume_relative_path names. The path names a file: it has at least one component, and no component is empty, . or .., or contains / or NUL. A request whose path is not of that form is answered with an error, and nothing is read.
The file. The server opens the file the path names, a symbolic link followed. A path at which nothing is, and a path at which what is there is not a regular file once opened, are answered with an error.
The bytes. The server sends the bytes of the file as responses, each at most CHUNK_SIZE bytes, in order, until the file is read. A file of zero bytes is sent as exactly one response of zero bytes. A read that fails is answered by exactly one error response after the responses already sent. The bytes are the file at rest: no container writes to the volume while the read runs, and the responses concatenated are the whole file as it was at the time of the request. Response states the sequence.
A held volume is not read. The server does not read a file out of a volume that a running container of the client holds, that a volumes::fuse_serve of the client holds, or that is under a volumes::stat, volumes::read, volumes::write, volumes::filetree, volumes::edit or volumes::delete, at the time of the request. A request naming such a volume is answered with the refusal the response states for who holds it — Mounted, FuseServed or Held — decided in the order Capabilities states for an operation, and nothing is changed. The server holds the volume to itself from the moment it accepts the request until the response finish, and a run, a FUSE serve or another operation naming the volume is refused for as long as it does.
The error. An error states that the file was not read, or not all of it. A volume absent from the client’s listing, a path that is not of the stated form, and a path that names no regular file are each answered with an error. A volume that something holds is answered with the refusal the response states, which is not an error.
No volume at all. A server that holds out none of the three mode objects of Capabilities keeps no volume and answers every request of this endpoint with exactly one response, the byte 4 alone, and the response finish, before anything is looked up. Every other requirement of this page holds for a server that keeps volumes.

In this section

Request — The payload is the tag byte 5 followed by the name of the volume as a varint length and UTF-8 bytes and the path of the file as a varint count of components each a varint length and UTF-8 bytes, in the postcard wire format.
Response — The server sends the bytes of the file as responses whose first byte is 0, each at most CHUNK_SIZE bytes, and the finish; a file of zero bytes is one empty response; the byte 1, 2 or 3 alone, when a running container, a FUSE serve or an operation holds the volume, or the byte 4 alone, when the server keeps no volume, is the only response; a response whose first byte is 5 carries an error and is the last.