# volumes::edit

> Tag 9: a client names a volume from its listing and states its size in bytes; the server sends exactly one response stating that the volume has that size, that the server has insufficient capacity for it, that the content of the volume exceeds it, or an error, and the scope finishes; the size is the only property an edit changes.

Canonical: https://provider.diverge.network/2.3.0/endpoints/volumes-edit/
Specification revision: 2.3.0

A client opens the scope with a request whose payload is the tag byte
`9` followed by the name of a volume and a size. The server sends
exactly one response, which states that the volume has the size
stated, that the server has insufficient capacity for it, that the
content of the volume exceeds it, or an error. The response finish
follows the response, and no frame follows the finish.

- **The request.** The request carries the name of one volume and a
  size in bytes. [Request](/2.3.0/endpoints/volumes-edit/request/) states
  its form.
- **The volume named.** The client names a volume by the `name` its
  [volumes::list](/2.3.0/endpoints/volumes-list/) listing gave it. The
  server resolves the name against the identity under which the
  connection was authorized, as [Authorization](/2.3.0/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. A
  server may refuse to edit a volume that it offered on its own
  account and that the client did not create; the refusal is an
  error.
- **The size.** The size is absolute: the request states the size
  the volume has after the edit, not a change to its size. When the
  server sends the byte `0`, the volume has the size stated. From
  that moment, every [volumes::list](/2.3.0/endpoints/volumes-list/)
  listing and every [volumes::stat](/2.3.0/endpoints/volumes-stat/)
  response of the client reports that size as `bytes`, until a later
  edit changes it. The size is the only property an edit changes: the
  name, the content, the bytes in use and the hash of the content are
  as they were before the request.
  [Response](/2.3.0/endpoints/volumes-edit/response/) states the form of
  the response.
- **Insufficient capacity.** When the server cannot reserve the size
  stated, it does not change the size and sends the byte `1`. The
  volume has the size it had before the request. The server does not
  send the byte `0` for a size it cannot reserve. The number of bytes
  by which the volume can grow at a given time is reported by
  [volumes::edit_capacity](/2.3.0/endpoints/volumes-edit-capacity/).
- **Content too large.** When the size stated is smaller than the
  number of bytes the volume holds, the server does not change the
  size and sends the byte `2`. The volume has the size it had before
  the request, and its content is as it was. The server does not send
  the byte `0` for a size that the content of the volume exceeds. A
  client that wants the smaller size removes content from the volume,
  by a container in which the volume is mounted, and asks again.
- **The error.** An error states that the size was not changed, for a
  reason other than capacity or content: the volume has the size it
  had before the request, and every listing and every stat reports
  that size.