sdk/fidl/fuchsia.io/file2.fidl - fuchsia - Git at Google

 // Copyright 2019 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 library fuchsia.io;

 using zx;

 // TODO: We should run some experiments to see what's the optimum value, or
 // what's the point of diminishing marginal returns.
 /// The maximum I/O size that is allowed for read/write operations using
 /// byte vectors.
 const MAX_TRANSFER_SIZE uint64 = 8192;

 /// The byte vector type used for read/write operations.
 alias Transfer = vector<uint8>:MAX_TRANSFER_SIZE;

 /// Denotes which hash algorithm is used to build the merkle tree for
 /// fsverity-enabled files.
 @available(added=HEAD)
 type HashAlgorithm = flexible enum : uint8 {
     SHA256 = 1;
     SHA512 = 2;
 };

 /// Set of options used to enable verity on a file.
 @available(added=HEAD)
 type VerificationOptions = table {
     1: hash_algorithm HashAlgorithm;
     /// `salt` is prepended to each block before it is hashed.
     2: salt vector<uint8>:32;
 };

 /// Auxiliary data for the file representation of a node.
 type FileInfo = resource table {
     /// True if the file is opened in append mode.
     /// In append mode, the seek offset is moved to the end before every
     /// write, the two steps performed in an atomic manner.
     1: is_append bool;

     /// An optional event which transmits information about an object's
     /// readability or writability. This event relays information about the
     /// underlying object, not the capability granted to client: this event
     /// may be signalled "readable" on a connection that does not have
     /// the capability to read.
     ///
     /// This event will be present if the following conditions are met:
     ///
     /// - The `available_operations` on the file connection is not empty.
     /// - The filesystem supports signalling readability/writability events.
     ///
     /// The [`FileSignal`] values may be observed on this event.
     2: observer zx.Handle:EVENT;

     /// An optional stream object, which can be used to read to and write from
     /// the file.
     ///
     /// Reading and writing the file using the stream object can be up to 20x
     /// faster than reading and writing the file using the Read and Write
     /// operations in the [`File`] protocol.
     3: stream zx.Handle:STREAM;

     /// Requested attributes for the file. This is only populated if requested.
     @available(added=18)
     4: attributes NodeAttributes2;
 };

 // TODO(https://fxbug.dev/42056856): Use a generated constant.
 const FILE_PROTOCOL_NAME string = "fuchsia.io/File";

 /// A [`Node`] which contains a sequence of bytes of definite length.
 ///
 /// NOTE: cloned connections do not share their seek offset with their source
 /// connection.
 closed protocol File {
     compose AdvisoryLocking;
     @available(added=18)
     compose Linkable;
     compose Node;
     compose Readable;
     compose Writable;

     @selector("fuchsia.io/File.Describe")
     strict Describe() -> (FileInfo);

     /// Moves the offset at which the next invocation of [`Read`] or [`Write`]
     /// will occur. The seek offset is specific to each file connection.
     ///
     /// + request `origin` the reference point where `offset` will be based on.
     /// + request `offset` the number of bytes to seek.
     /// - response `offset_from_start` the adjusted seek offset, from the start
     ///   of the file.
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io/File.Seek")
     strict Seek(struct {
         origin SeekOrigin;
         offset int64;
     }) -> (struct {
         offset_from_start uint64;
     }) error zx.Status;

     /// Reads up to 'count' bytes at the provided offset.
     /// Does not affect the seek offset.
     ///
     /// ## Invariants
     ///
     /// * The returned `data.length` will never be greater than `count`.
     /// * If `data.length` is less than `count`, it means that `ReadAt` has hit
     ///   the end of file as part of this operation.
     /// * If `data.length` is zero while `count` is not, it means that `offset`
     ///   is at or past the end of file, and no data can be read.
     /// * If `count` is zero, the server should perform all the checks ensuring
     ///   read access without actually reading anything, and return an empty
     ///   `data` vector.
     ///
     /// This method requires the [`Rights.READ_BYTES`] right.
     ///
     /// Returns `ZX_ERR_OUT_OF_RANGE` if `count` is greater than `MAX_TRANSFER_SIZE`.
     @selector("fuchsia.io/File.ReadAt")
     strict ReadAt(struct {
         count uint64;
         offset uint64;
     }) -> (struct {
         data Transfer;
     }) error zx.Status;

     /// Writes data at the provided offset.
     /// Does not affect the seek offset.
     ///
     /// The file size may grow if `offset` plus `data.length` is past the
     /// current end of file.
     ///
     /// + request `data` the byte buffer to write to the file.
     /// + request `offset` the offset from start of the file to begin writing.
     /// - response `actual_count` the number of bytes written.
     ///
     /// ## Invariants
     ///
     /// * The returned `actual_count` will never be greater than `data.length`.
     /// * If the server is unable to write all the data due to e.g. not enough
     ///   space, `actual_count` may be less than `data.length`.  If no bytes
     ///   could be written, an error is returned.
     /// * If `data.length` is zero, the server should perform all the checks
     ///   ensuring write access without mutating the file, and will return a
     ///   successful write of zero bytes.
     ///
     /// This method requires the [`Rights.WRITE_BYTES`] right.
     @selector("fuchsia.io/File.WriteAt")
     strict WriteAt(struct {
         data Transfer;
         offset uint64;
     }) -> (struct {
         actual_count uint64;
     }) error zx.Status;

     /// Shrinks or grows the file size to 'length' bytes.
     ///
     /// If file size is reduced by this operation, the extra trailing data'
     /// is discarded.
     /// If file size is increased by this operation, the extended area appears
     /// as if it was zeroed.
     ///
     /// This method requires the [`Rights.WRITE_BYTES`] right.
     @selector("fuchsia.io/File.Resize")
     strict Resize(struct {
         length uint64;
     }) -> () error zx.Status;

     /// Acquires a [`zx.Handle:VMO`] representing this file, if there is one,
     /// with the requested access rights.
     ///
     /// Implementations are not required to implement files backed by VMOs so
     /// this request may fail. Additionally, implementations may only support
     /// a certain subset of the flags. Clients should be prepared with fallback
     /// behavior if this request fails.
     ///
     /// If a client specifies neither `PRIVATE_CLONE` nor `SHARED_BUFFER`, the
     /// implementation is free to choose the semantics of the returned VMO.
     ///
     /// + request `flags` a [`VmoFlags`] indicating the desired mode of access.
     /// - response `vmo` the requested [`zx.Handle:VMO`].
     /// * error a [`zx.Status`] value indicating the failure.
     ///
     /// This method requires the following rights:
     ///
     /// * [`Rights.READ_BYTES`] if `flags` includes [`VmoFlags.READ`].
     /// * [`Rights.WRITE_BYTES`] if `flags` includes [`VmoFlags.WRITE`].
     /// * [`Rights.EXECUTE`] if `flags` includes [`VmoFlags.EXECUTE`].
     @selector("fuchsia.io/File.GetBackingMemory")
     strict GetBackingMemory(struct {
         flags @generated_name("VmoFlags") strict bits : uint32 {
             /// Requests that the VMO be readable.
             READ = 0x00000001;

             /// Requests that the VMO be writable.
             WRITE = 0x00000002;

             /// Request that the VMO be executable.
             EXECUTE = 0x00000004;

             /// Require a copy-on-write clone of the underlying VMO. The request
             /// should fail if the VMO cannot be cloned. May not be supplied
             /// with `SHARED_BUFFER`.
             ///
             /// A private clone uses at least the guarantees of the
             /// `ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE` flag to
             /// `zx_vmo_create_child()`. This means that the returned VMO will
             /// be copy-on-write (if `WRITE` is requested) but that it may or
             /// may not reflect subsequent content changes to the underlying
             /// file. The returned VMO will not reflect size changes to the
             /// file. These semantics match those of the POSIX `mmap()`
             /// `MAP_PRIVATE` flag.
             ///
             /// In some cases, clients requiring a guaranteed snapshot of the
             /// file can use `SHARED_BUFFER` and then use
             /// `zx_vmo_create_child()` with `ZX_VMO_CHILD_SNAPSHOT`. However,
             /// in addition to cases where the implementation can't return a
             /// `SHARED_BUFFER`, creating a full snapshot will fail if the VMO
             /// is attached to the pager. Since most filesystems will use the
             /// paging system, the full snapshot approach should only be used in
             /// specific cases where the client is talking to a known server.
             PRIVATE_CLONE = 0x00010000;

             /// Require a VMO that provides direct access to the contents of the
             /// file's underlying VMO. The request should fail if such a VMO
             /// cannot be provided. May not be supplied with `PRIVATE_CLONE`.
             ///
             /// The returned VMO may not be resizable even when `WRITE` access is
             /// requested. In this case, [`File.Resize`] should be used to resize
             /// the file.
             SHARED_BUFFER = 0x00020000;
         };
     }) -> (resource struct {
         vmo zx.Handle:VMO;
     }) error zx.Status;

     /// Pre-allocate on-disk space for this file.
     @available(added=HEAD)
     @selector("fuchsia.io/File.Allocate")
     strict Allocate(resource struct {
         offset uint64;
         length uint64;

         /// If an empty bits is passed for mode, the default behavior is used. Otherwise the
         /// behavior is modified as described for each mode bit. If the backing filesystem doesn't
         /// support a particular provided mode bit, or combination of mode bits, an error is
         /// returned.
         mode @generated_name("AllocateMode") flexible bits : uint32 {
             KEEP_SIZE = 0x00000001;
             UNSHARE_RANGE = 0x00000002;
             PUNCH_HOLE = 0x00000004;
             COLLAPSE_RANGE = 0x00000008;
             ZERO_RANGE = 0x00000010;
             INSERT_RANGE = 0x00000020;
         };
     }) -> () error zx.Status;

     /// Enables verification for the file (permanently) which involves computing a merkle tree for
     /// the file. Forces a flush prior to building the merkle tree to ensure cached data is
     /// captured. Future reads will be verified against the computed merkle tree and writes will be
     /// rejected. This method can take some time to complete as it depends on the size of the file.
     /// This method can be aborted by closing the connection that this method was issued on.
     ///
     /// This method requires the [`Rights.UPDATE_ATTRIBUTES`] right.
     /// Returns `ZX_ERR_NOT_SUPPORTED` if the filesystem does not support verity.
     /// Returns `ZX_ERR_ALREADY_EXISTS` if the file was already fsverity-enabled.
     /// Also returns any error that might arise from reading the file, or from flushing the file,
     /// such as `ZX_ERR_IO`.
     @selector("fuchsia.io/File.EnableVerity")
     @available(added=HEAD)
     strict EnableVerity(resource struct {
         options VerificationOptions;
     }) -> () error zx.Status;
 };

 closed protocol Readable {
     /// Reads up to 'count' bytes at the seek offset.
     /// The seek offset is moved forward by the number of bytes read.
     ///
     /// ## Invariants
     ///
     /// * The returned `data.length` will never be greater than `count`.
     /// * If `data.length` is less than `count`, it means that the seek offset
     ///   has reached the end of file as part of this operation.
     /// * If `data.length` is zero while `count` is not, it means that the
     ///   seek offset is already at or beyond the end of file, and no data could
     ///   be read.
     /// * If `count` is zero, the server should perform all the checks ensuring
     ///   read access without actually read anything, and return an empty
     ///   `data` vector.
     ///
     /// This method requires the [`Rights.READ_BYTES`] right.
     ///
     /// Returns `ZX_ERR_OUT_OF_RANGE` if `count` is greater than `MAX_TRANSFER_SIZE`.
     @selector("fuchsia.io/File.Read")
     strict Read(struct {
         count uint64;
     }) -> (struct {
         data Transfer;
     }) error zx.Status;
 };

 closed protocol Writable {
     /// Writes data at the seek offset.
     /// The seek offset is moved forward by the number of bytes written.
     /// If the file is in append mode, the seek offset is first set to the end
     /// of the file, followed by the write, in one atomic step.
     ///
     /// The file size may grow if the seek offset plus `data.length` is beyond
     /// the current end of file.
     ///
     /// + request `data` the byte buffer to write to the file.
     /// - response `actual_count` the number of bytes written.
     ///
     /// ## Invariants
     ///
     /// * The returned `actual_count` will never be greater than `data.length`.
     /// * If the server is unable to write all the data due to e.g. not enough
     ///   space, `actual_count` may be less than `data.length`.  If no bytes
     ///   could be written, an error is returned.
     /// * If `data.length` is zero, the server should perform all the checks
     ///   ensuring write access without mutating the file and return a
     ///   successful write of zero bytes.  The seek offset is still updated if
     ///   in append mode.
     ///
     /// This method requires the [`Rights.WRITE_BYTES`] right.
     @selector("fuchsia.io/File.Write")
     strict Write(struct {
         data Transfer;
     }) -> (struct {
         actual_count uint64;
     }) error zx.Status;
 };

 /// The reference point for updating the seek offset. See [`File.Seek`].
 ///
 /// This enum matches the `zx_stream_seek_origin_t` enum.
 type SeekOrigin = strict enum : uint32 {
     /// Seek from the start of the file.
     /// The seek offset will be set to `offset` bytes.
     /// The seek offset cannot be negative in this case.
     START = 0;

     /// Seek from the current position in the file.
     /// The seek offset will be the current seek offset plus `offset` bytes.
     CURRENT = 1;

     /// Seek from the end of the file.
     /// The seek offset will be the file size plus `offset` bytes.
     END = 2;
 };

 type FileSignal = strict bits : uint32 {
     /// Indicates the file is ready for reading.
     READABLE = 0x01000000; // ZX_USER_SIGNAL_0

     /// Indicates the file is ready for writing.
     WRITABLE = 0x02000000; // ZX_USER_SIGNAL_1
 };
	// Copyright 2019 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.
	library fuchsia.io;

	using zx;

	// TODO: We should run some experiments to see what's the optimum value, or
	// what's the point of diminishing marginal returns.
	/// The maximum I/O size that is allowed for read/write operations using
	/// byte vectors.
	const MAX_TRANSFER_SIZE uint64 = 8192;

	/// The byte vector type used for read/write operations.
	alias Transfer = vector<uint8>:MAX_TRANSFER_SIZE;

	/// Denotes which hash algorithm is used to build the merkle tree for
	/// fsverity-enabled files.
	@available(added=HEAD)
	type HashAlgorithm = flexible enum : uint8 {
	SHA256 = 1;
	SHA512 = 2;
	};

	/// Set of options used to enable verity on a file.
	@available(added=HEAD)
	type VerificationOptions = table {
	1: hash_algorithm HashAlgorithm;
	/// `salt` is prepended to each block before it is hashed.
	2: salt vector<uint8>:32;
	};

	/// Auxiliary data for the file representation of a node.
	type FileInfo = resource table {
	/// True if the file is opened in append mode.
	/// In append mode, the seek offset is moved to the end before every
	/// write, the two steps performed in an atomic manner.
	1: is_append bool;

	/// An optional event which transmits information about an object's
	/// readability or writability. This event relays information about the
	/// underlying object, not the capability granted to client: this event
	/// may be signalled "readable" on a connection that does not have
	/// the capability to read.
	///
	/// This event will be present if the following conditions are met:
	///
	/// - The `available_operations` on the file connection is not empty.
	/// - The filesystem supports signalling readability/writability events.
	///
	/// The [`FileSignal`] values may be observed on this event.
	2: observer zx.Handle:EVENT;

	/// An optional stream object, which can be used to read to and write from
	/// the file.
	///
	/// Reading and writing the file using the stream object can be up to 20x
	/// faster than reading and writing the file using the Read and Write
	/// operations in the [`File`] protocol.
	3: stream zx.Handle:STREAM;

	/// Requested attributes for the file. This is only populated if requested.
	@available(added=18)
	4: attributes NodeAttributes2;
	};

	// TODO(https://fxbug.dev/42056856): Use a generated constant.
	const FILE_PROTOCOL_NAME string = "fuchsia.io/File";

	/// A [`Node`] which contains a sequence of bytes of definite length.
	///
	/// NOTE: cloned connections do not share their seek offset with their source
	/// connection.
	closed protocol File {
	compose AdvisoryLocking;
	@available(added=18)
	compose Linkable;
	compose Node;
	compose Readable;
	compose Writable;

	@selector("fuchsia.io/File.Describe")
	strict Describe() -> (FileInfo);

	/// Moves the offset at which the next invocation of [`Read`] or [`Write`]
	/// will occur. The seek offset is specific to each file connection.
	///
	/// + request `origin` the reference point where `offset` will be based on.
	/// + request `offset` the number of bytes to seek.
	/// - response `offset_from_start` the adjusted seek offset, from the start
	/// of the file.
	///
	/// This method does not require any rights.
	@selector("fuchsia.io/File.Seek")
	strict Seek(struct {
	origin SeekOrigin;
	offset int64;
	}) -> (struct {
	offset_from_start uint64;
	}) error zx.Status;

	/// Reads up to 'count' bytes at the provided offset.
	/// Does not affect the seek offset.
	///
	/// ## Invariants
	///
	/// * The returned `data.length` will never be greater than `count`.
	/// * If `data.length` is less than `count`, it means that `ReadAt` has hit
	/// the end of file as part of this operation.
	/// * If `data.length` is zero while `count` is not, it means that `offset`
	/// is at or past the end of file, and no data can be read.
	/// * If `count` is zero, the server should perform all the checks ensuring
	/// read access without actually reading anything, and return an empty
	/// `data` vector.
	///
	/// This method requires the [`Rights.READ_BYTES`] right.
	///
	/// Returns `ZX_ERR_OUT_OF_RANGE` if `count` is greater than `MAX_TRANSFER_SIZE`.
	@selector("fuchsia.io/File.ReadAt")
	strict ReadAt(struct {
	count uint64;
	offset uint64;
	}) -> (struct {
	data Transfer;
	}) error zx.Status;

	/// Writes data at the provided offset.
	/// Does not affect the seek offset.
	///
	/// The file size may grow if `offset` plus `data.length` is past the
	/// current end of file.
	///
	/// + request `data` the byte buffer to write to the file.
	/// + request `offset` the offset from start of the file to begin writing.
	/// - response `actual_count` the number of bytes written.
	///
	/// ## Invariants
	///
	/// * The returned `actual_count` will never be greater than `data.length`.
	/// * If the server is unable to write all the data due to e.g. not enough
	/// space, `actual_count` may be less than `data.length`. If no bytes
	/// could be written, an error is returned.
	/// * If `data.length` is zero, the server should perform all the checks
	/// ensuring write access without mutating the file, and will return a
	/// successful write of zero bytes.
	///
	/// This method requires the [`Rights.WRITE_BYTES`] right.
	@selector("fuchsia.io/File.WriteAt")
	strict WriteAt(struct {
	data Transfer;
	offset uint64;
	}) -> (struct {
	actual_count uint64;
	}) error zx.Status;

	/// Shrinks or grows the file size to 'length' bytes.
	///
	/// If file size is reduced by this operation, the extra trailing data'
	/// is discarded.
	/// If file size is increased by this operation, the extended area appears
	/// as if it was zeroed.
	///
	/// This method requires the [`Rights.WRITE_BYTES`] right.
	@selector("fuchsia.io/File.Resize")
	strict Resize(struct {
	length uint64;
	}) -> () error zx.Status;

	/// Acquires a [`zx.Handle:VMO`] representing this file, if there is one,
	/// with the requested access rights.
	///
	/// Implementations are not required to implement files backed by VMOs so
	/// this request may fail. Additionally, implementations may only support
	/// a certain subset of the flags. Clients should be prepared with fallback
	/// behavior if this request fails.
	///
	/// If a client specifies neither `PRIVATE_CLONE` nor `SHARED_BUFFER`, the
	/// implementation is free to choose the semantics of the returned VMO.
	///
	/// + request `flags` a [`VmoFlags`] indicating the desired mode of access.
	/// - response `vmo` the requested [`zx.Handle:VMO`].
	/// * error a [`zx.Status`] value indicating the failure.
	///
	/// This method requires the following rights:
	///
	/// * [`Rights.READ_BYTES`] if `flags` includes [`VmoFlags.READ`].
	/// * [`Rights.WRITE_BYTES`] if `flags` includes [`VmoFlags.WRITE`].
	/// * [`Rights.EXECUTE`] if `flags` includes [`VmoFlags.EXECUTE`].
	@selector("fuchsia.io/File.GetBackingMemory")
	strict GetBackingMemory(struct {
	flags @generated_name("VmoFlags") strict bits : uint32 {
	/// Requests that the VMO be readable.
	READ = 0x00000001;

	/// Requests that the VMO be writable.
	WRITE = 0x00000002;

	/// Request that the VMO be executable.
	EXECUTE = 0x00000004;

	/// Require a copy-on-write clone of the underlying VMO. The request
	/// should fail if the VMO cannot be cloned. May not be supplied
	/// with `SHARED_BUFFER`.
	///
	/// A private clone uses at least the guarantees of the
	/// `ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE` flag to
	/// `zx_vmo_create_child()`. This means that the returned VMO will
	/// be copy-on-write (if `WRITE` is requested) but that it may or
	/// may not reflect subsequent content changes to the underlying
	/// file. The returned VMO will not reflect size changes to the
	/// file. These semantics match those of the POSIX `mmap()`
	/// `MAP_PRIVATE` flag.
	///
	/// In some cases, clients requiring a guaranteed snapshot of the
	/// file can use `SHARED_BUFFER` and then use
	/// `zx_vmo_create_child()` with `ZX_VMO_CHILD_SNAPSHOT`. However,
	/// in addition to cases where the implementation can't return a
	/// `SHARED_BUFFER`, creating a full snapshot will fail if the VMO
	/// is attached to the pager. Since most filesystems will use the
	/// paging system, the full snapshot approach should only be used in
	/// specific cases where the client is talking to a known server.
	PRIVATE_CLONE = 0x00010000;

	/// Require a VMO that provides direct access to the contents of the
	/// file's underlying VMO. The request should fail if such a VMO
	/// cannot be provided. May not be supplied with `PRIVATE_CLONE`.
	///
	/// The returned VMO may not be resizable even when `WRITE` access is
	/// requested. In this case, [`File.Resize`] should be used to resize
	/// the file.
	SHARED_BUFFER = 0x00020000;
	};
	}) -> (resource struct {
	vmo zx.Handle:VMO;
	}) error zx.Status;

	/// Pre-allocate on-disk space for this file.
	@available(added=HEAD)
	@selector("fuchsia.io/File.Allocate")
	strict Allocate(resource struct {
	offset uint64;
	length uint64;

	/// If an empty bits is passed for mode, the default behavior is used. Otherwise the
	/// behavior is modified as described for each mode bit. If the backing filesystem doesn't
	/// support a particular provided mode bit, or combination of mode bits, an error is
	/// returned.
	mode @generated_name("AllocateMode") flexible bits : uint32 {
	KEEP_SIZE = 0x00000001;
	UNSHARE_RANGE = 0x00000002;
	PUNCH_HOLE = 0x00000004;
	COLLAPSE_RANGE = 0x00000008;
	ZERO_RANGE = 0x00000010;
	INSERT_RANGE = 0x00000020;
	};
	}) -> () error zx.Status;

	/// Enables verification for the file (permanently) which involves computing a merkle tree for
	/// the file. Forces a flush prior to building the merkle tree to ensure cached data is
	/// captured. Future reads will be verified against the computed merkle tree and writes will be
	/// rejected. This method can take some time to complete as it depends on the size of the file.
	/// This method can be aborted by closing the connection that this method was issued on.
	///
	/// This method requires the [`Rights.UPDATE_ATTRIBUTES`] right.
	/// Returns `ZX_ERR_NOT_SUPPORTED` if the filesystem does not support verity.
	/// Returns `ZX_ERR_ALREADY_EXISTS` if the file was already fsverity-enabled.
	/// Also returns any error that might arise from reading the file, or from flushing the file,
	/// such as `ZX_ERR_IO`.
	@selector("fuchsia.io/File.EnableVerity")
	@available(added=HEAD)
	strict EnableVerity(resource struct {
	options VerificationOptions;
	}) -> () error zx.Status;
	};

	closed protocol Readable {
	/// Reads up to 'count' bytes at the seek offset.
	/// The seek offset is moved forward by the number of bytes read.
	///
	/// ## Invariants
	///
	/// * The returned `data.length` will never be greater than `count`.
	/// * If `data.length` is less than `count`, it means that the seek offset
	/// has reached the end of file as part of this operation.
	/// * If `data.length` is zero while `count` is not, it means that the
	/// seek offset is already at or beyond the end of file, and no data could
	/// be read.
	/// * If `count` is zero, the server should perform all the checks ensuring
	/// read access without actually read anything, and return an empty
	/// `data` vector.
	///
	/// This method requires the [`Rights.READ_BYTES`] right.
	///
	/// Returns `ZX_ERR_OUT_OF_RANGE` if `count` is greater than `MAX_TRANSFER_SIZE`.
	@selector("fuchsia.io/File.Read")
	strict Read(struct {
	count uint64;
	}) -> (struct {
	data Transfer;
	}) error zx.Status;
	};

	closed protocol Writable {
	/// Writes data at the seek offset.
	/// The seek offset is moved forward by the number of bytes written.
	/// If the file is in append mode, the seek offset is first set to the end
	/// of the file, followed by the write, in one atomic step.
	///
	/// The file size may grow if the seek offset plus `data.length` is beyond
	/// the current end of file.
	///
	/// + request `data` the byte buffer to write to the file.
	/// - response `actual_count` the number of bytes written.
	///
	/// ## Invariants
	///
	/// * The returned `actual_count` will never be greater than `data.length`.
	/// * If the server is unable to write all the data due to e.g. not enough
	/// space, `actual_count` may be less than `data.length`. If no bytes
	/// could be written, an error is returned.
	/// * If `data.length` is zero, the server should perform all the checks
	/// ensuring write access without mutating the file and return a
	/// successful write of zero bytes. The seek offset is still updated if
	/// in append mode.
	///
	/// This method requires the [`Rights.WRITE_BYTES`] right.
	@selector("fuchsia.io/File.Write")
	strict Write(struct {
	data Transfer;
	}) -> (struct {
	actual_count uint64;
	}) error zx.Status;
	};

	/// The reference point for updating the seek offset. See [`File.Seek`].
	///
	/// This enum matches the `zx_stream_seek_origin_t` enum.
	type SeekOrigin = strict enum : uint32 {
	/// Seek from the start of the file.
	/// The seek offset will be set to `offset` bytes.
	/// The seek offset cannot be negative in this case.
	START = 0;

	/// Seek from the current position in the file.
	/// The seek offset will be the current seek offset plus `offset` bytes.
	CURRENT = 1;

	/// Seek from the end of the file.
	/// The seek offset will be the file size plus `offset` bytes.
	END = 2;
	};

	type FileSignal = strict bits : uint32 {
	/// Indicates the file is ready for reading.
	READABLE = 0x01000000; // ZX_USER_SIGNAL_0

	/// Indicates the file is ready for writing.
	WRITABLE = 0x02000000; // ZX_USER_SIGNAL_1
	};