1.1 --- a/docs/wiki/ClientLibrary Wed Aug 10 23:58:38 2022 +0200
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,148 +0,0 @@
1.4 -= Client Library =
1.5 -
1.6 -The filesystem client library offers abstractions and a number of layers of
1.7 -functionality to support interaction with [[Components|components]] and the
1.8 -provision of higher-level mechanisms and abstractions for file access.
1.9 -
1.10 -<<TableOfContents(2,3)>>
1.11 -
1.12 -== File Data Structures ==
1.13 -
1.14 -Since files are accessed using file references, the `file_t` data structure is
1.15 -used to wrap such references and other relevant state. Thus, such structures
1.16 -can be broadly regarded as similar to the traditional `FILE` data structure.
1.17 -
1.18 -The fields of the `file_t` data structure are as follows:
1.19 -
1.20 -|| '''Field''' || '''Description''' ||
1.21 -|| `ref` || A reference to the component providing file content ||
1.22 -|| `memory` || The memory address of the exposed file region ||
1.23 -|| `start_pos` || The start position of the region in the file ||
1.24 -|| `end_pos` || The end position of the region in the file ||
1.25 -|| `data_end` || The amount or extent of populated data in the region ||
1.26 -|| `data_current` || The offset used to track client position in the region ||
1.27 -|| `size` || The total size of the file ||
1.28 -|| `object_flags` || Flags indicating support for certain file features ||
1.29 -|| `can_block` || Notification flags for blocking access to the file ||
1.30 -|| `notifications`|| Notification flags set for the file ||
1.31 -|| `flags` || The flags used to open the file ||
1.32 -
1.33 -== Client Programming Interface ==
1.34 -
1.35 -The client programming interface provides functions somewhat resembling the
1.36 -traditional C library and low-level Unix interfaces for file access, and these
1.37 -functions are intended to support such traditional interfaces.
1.38 -
1.39 -=== Files ===
1.40 -
1.41 -Files are opened and closed using the following functions:
1.42 -
1.43 -{{{
1.44 -file_t *client_open(const char *name, flags_t flags);
1.45 -}}}
1.46 -
1.47 -Each file endpoint may be closed using `client_close`.
1.48 -
1.49 -=== Pipes ===
1.50 -
1.51 -Pipes are opened using a special function:
1.52 -
1.53 -{{{
1.54 -long client_pipe(file_t **reader, file_t **writer, flags_t flags);
1.55 -}}}
1.56 -
1.57 -Each pipe endpoint may be closed using `client_close`.
1.58 -
1.59 -=== Closing Files and Pipes ===
1.60 -
1.61 -Closing files and pipes involves a common operation:
1.62 -
1.63 -{{{
1.64 -void client_close(file_t *file);
1.65 -}}}
1.66 -
1.67 -When client programs terminate, the freeing of their object capabilities
1.68 -should cause the closure of files and pipes, but programs may choose to close
1.69 -such resources explicitly.
1.70 -
1.71 -=== Reading and Writing ===
1.72 -
1.73 -Reading and writing files and pipes involves functions resembling the
1.74 -traditional low-level `read` and `write` functions:
1.75 -
1.76 -{{{
1.77 -offset_t client_read(file_t *file, void *buf, offset_t count);
1.78 -offset_t client_write(file_t *file, const void *buf, offset_t count);
1.79 -}}}
1.80 -
1.81 -=== Navigation in Files ===
1.82 -
1.83 -Support for navigation in files is provided using functions resembling the
1.84 -traditional higher-level `fseek` and `ftell` functions:
1.85 -
1.86 -{{{
1.87 -offset_t client_seek(file_t *file, offset_t offset, int whence);
1.88 -long client_tell(file_t *file);
1.89 -}}}
1.90 -
1.91 -=== Accessing Exposed Memory Regions ===
1.92 -
1.93 -Although the client library (and the provision of files) employs mapped
1.94 -memory, a function can be used to explicitly reference memory for file access:
1.95 -
1.96 -{{{
1.97 -void *client_mmap(file_t *file, offset_t position, offset_t length);
1.98 -}}}
1.99 -
1.100 -Pipes support a different mechanism for navigation involving the following
1.101 -functions:
1.102 -
1.103 -{{{
1.104 -long client_current_region(file_t *file);
1.105 -long client_next_region(file_t *file);
1.106 -}}}
1.107 -
1.108 -Such navigation functions for files and pipes do not need to be used where the
1.109 -higher-level reading, writing and seeking functions are in use.
1.110 -
1.111 -=== Flushing and Synchronisation ===
1.112 -
1.113 -For synchronisation purposes, either with the filesystem itself or with other
1.114 -users of the filesystem, a function resembling the traditional `fflush`
1.115 -function is provided:
1.116 -
1.117 -{{{
1.118 -long client_flush(file_t *file);
1.119 -}}}
1.120 -
1.121 -This updates the file data structure with new details of the file size, also
1.122 -updating any altered details of the extent of the data in the currently
1.123 -accessed region of the file.
1.124 -
1.125 -=== Notifications ===
1.126 -
1.127 -Since files and pipes may be accessed by multiple clients, necessarily for any
1.128 -sensible use of the latter, notifications can be configured to communicate a
1.129 -change in state to other users of these resources when they are accessed.
1.130 -
1.131 -Notification types are specified using values encoding a number of flags, and
1.132 -the following flags are available for this purpose:
1.133 -
1.134 -|| '''Flag''' || '''Notification Type''' ||
1.135 -|| `NOTIFY_CONTENT_AVAILABLE` || Content available to read ||
1.136 -|| `NOTIFY_PEER_CLOSED` || Other party has closed their endpoint ||
1.137 -|| `NOTIFY_SPACE_AVAILABLE` || Space available for writing ||
1.138 -
1.139 -=== Blocking Operations ===
1.140 -
1.141 -Reading and writing operations can be configured to block if data cannot be
1.142 -read or written respectively. The following function is provided for this
1.143 -purpose:
1.144 -
1.145 -{{{
1.146 -long client_set_blocking(file_t *file, notify_flags_t flags);
1.147 -}}}
1.148 -
1.149 -For pipes, blocking behaviour is the default and must be disabled explicitly,
1.150 -either by opening using the `O_NONBLOCK` flag or by calling
1.151 -`client_set_blocking` with no flags set.