| // 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 Overview |
| /// |
| library fuchsia.io2; |
| |
| using zx; |
| |
| /// The type for the name of a node, i.e. a single path component. |
| /// E.g. `foo` |
| /// |
| /// ## Invariants |
| /// |
| /// A valid node name must meet the following criteria: |
| /// |
| /// * It cannot be longer than [`MAX_NAME_LENGTH`]. |
| /// * It cannot be empty. |
| /// * It cannot be ".." (dot-dot). |
| /// * It cannot be "." (single dot). |
| /// * It cannot contain "/". |
| /// * It cannot contain embedded NUL. |
| alias Name = string:MAX_NAME_LENGTH; |
| |
| /// The maximum length, in bytes, of a single filesystem component. |
| const uint64 MAX_NAME_LENGTH = 255; |
| |
| /// A path is a string of one or more components, separated by "/". |
| /// E.g. `foo/bar/baz` |
| /// |
| /// ## Invariants |
| /// |
| /// A valid path must meet the following criteria: |
| /// |
| /// * It cannot be empty. |
| /// * It cannot be longer than [`MAX_PATH_LENGTH`]. |
| /// * It cannot have a leading "/". |
| /// * It cannot have a trailing "/". |
| /// * Each component must be a valid [`Name`]. |
| /// |
| /// Paths should be transformed into their canonical forms at client side. |
| /// For example, a client should convert `"foo/bar/.././baz/"` to `"foo/baz"` |
| /// before using it as a path. |
| alias Path = string:MAX_PATH_LENGTH; |
| |
| /// The maximum length, in bytes, of a filesystem path. |
| const uint64 MAX_PATH_LENGTH = 4095; |
| |
| /// The type to identify a connection to a node. |
| /// It represents a capability: a reference to a node with associated rights. |
| alias Token = zx.handle:EVENT; |
| |
| /// The type to identify a node, if the implementation supports some notion of |
| /// unique node ID. |
| /// |
| /// ## Uniqueness Guarantees |
| /// |
| /// A client is usually presented with a directory tree that is the result |
| /// of composing together multiple backing implementation instances. An ID |
| /// would be unique within the corresponding instance only. |
| /// Their boundaries are rather implicit on Fuchsia, as a result of |
| /// transparently-forwarding directory proxies. It could be common for a client |
| /// to observe identical `Id`s when traversing a directory tree, when it |
| /// encounters nodes from different backing instances. Therefore, the ID is best |
| /// used for debugging and informational purposes. |
| /// |
| /// If the implementation also supports [`fuchsia.fs/Query`], the |
| /// [`fuchsia.fs/FilesystemInfo.fs_id`] field may be used to disambiguate IDs |
| /// from different backing instances. |
| alias Id = uint64; |