paul@142 | 1 | = Files = |
paul@142 | 2 | |
paul@142 | 3 | Access to files is provided by a number of programs acting as components. For |
paul@142 | 4 | convenience, the component-level operations are wrapped up in a client library |
paul@142 | 5 | that aims to provide simpler, more familiar mechanisms for opening, reading, |
paul@142 | 6 | writing, and closing files, together with various other operations. |
paul@142 | 7 | |
paul@142 | 8 | <<TableOfContents(2,3)>> |
paul@142 | 9 | |
paul@142 | 10 | == Components == |
paul@142 | 11 | |
paul@142 | 12 | At the lowest level in L4Re, files are accessed via a suite of components. |
paul@172 | 13 | These components are principally of interest to library developers since they |
paul@172 | 14 | only provide a limited level of abstraction. |
paul@142 | 15 | |
paul@142 | 16 | === Filesystems === |
paul@142 | 17 | |
paul@144 | 18 | Filesystems implement the `Filesystem` interface which provides the |
paul@144 | 19 | `open_for_user` operation: |
paul@144 | 20 | |
paul@144 | 21 | {{{ |
paul@172 | 22 | open_for_user(in user_t user, out cap opener) |
paul@144 | 23 | }}} |
paul@144 | 24 | |
paul@144 | 25 | The operation yields a file opener appropriate for the given user credentials. |
paul@144 | 26 | |
paul@144 | 27 | === File Openers === |
paul@144 | 28 | |
paul@144 | 29 | File openers implement the `Opener` interface which provides the `context` |
paul@142 | 30 | operation: |
paul@142 | 31 | |
paul@142 | 32 | {{{ |
paul@142 | 33 | context(out cap context) |
paul@142 | 34 | }}} |
paul@142 | 35 | |
paul@142 | 36 | Each client program, task or thread obtains its own context because it will |
paul@142 | 37 | need its own dedicated channel for communication with the filesystem. |
paul@142 | 38 | |
paul@142 | 39 | === Contexts === |
paul@142 | 40 | |
paul@142 | 41 | A context acts as a dataspace, meaning that it can be attached to a task using |
paul@142 | 42 | a region manager and provide a buffer via a region of mapped memory that the |
paul@142 | 43 | task can write to. In the case of a context, the task will write a filesystem |
paul@142 | 44 | path indicating the file to be opened. |
paul@142 | 45 | |
paul@142 | 46 | Each context allows a client program to request access to individual files via |
paul@142 | 47 | operations provided by the `OpenerContext` interface, of which the most |
paul@142 | 48 | pertinent is the `open` operation: |
paul@142 | 49 | |
paul@142 | 50 | {{{ |
paul@172 | 51 | open(in flags_t flags, out offset_t size, out cap file, |
paul@172 | 52 | out object_flags_t object_flags) |
paul@142 | 53 | }}} |
paul@142 | 54 | |
paul@142 | 55 | Using the path information written to the context's memory region, the `open` |
paul@172 | 56 | operation will obtain a reference to a file-like object whose characteristics |
paul@172 | 57 | are described by the accompanying `object_flags`, these helping the client to |
paul@172 | 58 | distinguish between files that support arbitrary memory mapping operations and |
paul@172 | 59 | pipes that mandate sequential region-by-region access. |
paul@172 | 60 | |
paul@172 | 61 | Alongside regular files, directories may also be opened. Reading from them |
paul@172 | 62 | yields a listing of directory entries. |
paul@142 | 63 | |
paul@142 | 64 | === Files === |
paul@142 | 65 | |
paul@142 | 66 | Files themselves act as dataspaces, meaning that they can be attached to a |
paul@142 | 67 | task using a region manager and provide their content via a region of mapped |
paul@142 | 68 | memory. Files implement the `MappedFile` interface. |
paul@142 | 69 | |
paul@142 | 70 | Control over the region of the file provided via mapped memory occurs |
paul@142 | 71 | using the `mmap` operation: |
paul@142 | 72 | |
paul@142 | 73 | {{{ |
paul@142 | 74 | mmap(in offset_t position, in offset_t length, |
paul@142 | 75 | out offset_t start_pos, out offset_t end_pos, |
paul@142 | 76 | out offset_t size) |
paul@142 | 77 | }}} |
paul@142 | 78 | |
paul@142 | 79 | Files also implement the more general `File` interface that provides the |
paul@142 | 80 | `resize` operation: |
paul@142 | 81 | |
paul@142 | 82 | {{{ |
paul@142 | 83 | resize(inout offset_t size) |
paul@142 | 84 | }}} |
paul@142 | 85 | |
paul@142 | 86 | This allows the portion of the memory region dedicated to the file's contents |
paul@142 | 87 | to be extended. |
paul@142 | 88 | |
paul@172 | 89 | === Directories === |
paul@172 | 90 | |
paul@172 | 91 | Directories are also meant to be accessed like files, meaning that it should |
paul@172 | 92 | be possible to attach them to a task using a region manager and access the |
paul@172 | 93 | provided content, this being a listing of directory entries, via the mapped |
paul@172 | 94 | region. |
paul@172 | 95 | |
paul@172 | 96 | However, unlike files which may support arbitrary mapping of their contents, |
paul@172 | 97 | the provided content may be supplied by a pipe endpoint, thereby not |
paul@172 | 98 | supporting precisely the same navigation mechanisms as those supported by |
paul@172 | 99 | files. |
paul@172 | 100 | |
paul@172 | 101 | === Pipe Openers === |
paul@172 | 102 | |
paul@172 | 103 | Distinct from filesystems but potentially used by them, pipe openers provide a |
paul@172 | 104 | means of obtaining pipes, which are channels that support unidirectional |
paul@172 | 105 | communication via shared memory. |
paul@172 | 106 | |
paul@172 | 107 | Pipe openers implement the `PipeOpener` interface and support the following |
paul@172 | 108 | operation: |
paul@172 | 109 | |
paul@172 | 110 | {{{ |
paul@172 | 111 | pipe(in offset_t size, out cap reader, out cap writer) |
paul@172 | 112 | }}} |
paul@172 | 113 | |
paul@172 | 114 | The size is indicated to request pipe regions long enough for the needs of the |
paul@172 | 115 | communicating parties, with both reader and writer endpoint capabilities being |
paul@172 | 116 | returned. Such capabilities may be propagated to the eventual parties, these |
paul@172 | 117 | typically being separate tasks. |
paul@172 | 118 | |
paul@172 | 119 | === Pipes === |
paul@172 | 120 | |
paul@172 | 121 | Although not generally obtained from filesystems, pipes may be involved in |
paul@172 | 122 | providing content from some filesystem objects such as directories. However, |
paul@172 | 123 | they are also obtained directly from an appropriate pipe server providing pipe |
paul@172 | 124 | opening facilities. |
paul@172 | 125 | |
paul@172 | 126 | Pipes expose single regions of shared memory to their endpoints, with the |
paul@172 | 127 | writing endpoint populating one region while the reading endpoint accesses the |
paul@172 | 128 | other. The reading endpoint may advance to the region being written, and this |
paul@172 | 129 | will free up a new region for the writer when it has filled its region. When |
paul@172 | 130 | the writer itself advances, it permits the reader to consume all data in the |
paul@172 | 131 | fully populated region. Naturally, the reader may not advance ahead of the |
paul@172 | 132 | writer. |
paul@172 | 133 | |
paul@172 | 134 | Pipes implement the `Pipe` interface and a number of operations to support |
paul@172 | 135 | this interaction mechanism. |
paul@172 | 136 | |
paul@172 | 137 | The details of an endpoint's current region can be queried using the following |
paul@172 | 138 | operation: |
paul@172 | 139 | |
paul@172 | 140 | {{{ |
paul@172 | 141 | current_region(out offset_t populated_size, out offset_t size) |
paul@172 | 142 | }}} |
paul@172 | 143 | |
paul@172 | 144 | This provides details of the populated size (or amount of written data) in a |
paul@172 | 145 | region along with the size of the region. |
paul@172 | 146 | |
paul@172 | 147 | Navigation to the next available region of the pipe is performed using the |
paul@172 | 148 | following operation: |
paul@172 | 149 | |
paul@172 | 150 | {{{ |
paul@172 | 151 | next_region(inout offset_t populated_size, out offset_t size) |
paul@172 | 152 | }}} |
paul@172 | 153 | |
paul@172 | 154 | Here, the populated size may be specified by the writer so that the reader may |
paul@172 | 155 | query the current region's properties using the appropriate operation. |
paul@172 | 156 | |
paul@172 | 157 | The status of the pipe can be queried using the `closed` operation: |
paul@172 | 158 | |
paul@172 | 159 | {{{ |
paul@172 | 160 | closed(out int closed) |
paul@172 | 161 | }}} |
paul@172 | 162 | |
paul@172 | 163 | This indicates through a boolean-equivalent parameter whether one or both |
paul@172 | 164 | endpoints have been closed. |
paul@172 | 165 | |
paul@142 | 166 | == Libraries == |
paul@142 | 167 | |
paul@142 | 168 | The filesystem client library offers abstractions and a number of layers of |
paul@142 | 169 | functionality to support interaction with components and the provision of |
paul@142 | 170 | higher-level mechanisms and abstractions for file access. |
paul@142 | 171 | |
paul@142 | 172 | === Client Library === |
paul@142 | 173 | |
paul@142 | 174 | The client library provides functions somewhat resembling the traditional C |
paul@142 | 175 | library and low-level Unix interfaces for file access, and these functions are |
paul@142 | 176 | intended to support such traditional interfaces. |
paul@142 | 177 | |
paul@142 | 178 | Since files are accessed using file references, the `file_t` data structure is |
paul@142 | 179 | used to wrap such references and other relevant state. Thus, such structures |
paul@142 | 180 | can be broadly regarded as similar to the traditional `FILE` data structure. |
paul@142 | 181 | |
paul@142 | 182 | Files are opened and closed using the following functions: |
paul@142 | 183 | |
paul@142 | 184 | {{{ |
paul@142 | 185 | file_t *client_open(const char *name, flags_t flags); |
paul@142 | 186 | void client_close(file_t *file); |
paul@142 | 187 | }}} |
paul@142 | 188 | |
paul@172 | 189 | Pipes are opened using a special function: |
paul@172 | 190 | |
paul@172 | 191 | {{{ |
paul@172 | 192 | long client_pipe(file_t **reader, file_t **writer); |
paul@172 | 193 | }}} |
paul@172 | 194 | |
paul@172 | 195 | Each pipe endpoint may be closed using `client_close`. |
paul@172 | 196 | |
paul@172 | 197 | Reading and writing files and pipes involves functions resembling the |
paul@172 | 198 | traditional low-level `read` and `write` functions: |
paul@142 | 199 | |
paul@142 | 200 | {{{ |
paul@142 | 201 | offset_t client_read(file_t *file, void *buf, offset_t count); |
paul@142 | 202 | offset_t client_write(file_t *file, const void *buf, offset_t count); |
paul@142 | 203 | }}} |
paul@142 | 204 | |
paul@142 | 205 | Support for navigation in files is provided using functions resembling the |
paul@142 | 206 | traditional higher-level `fseek` and `ftell` functions: |
paul@142 | 207 | |
paul@142 | 208 | {{{ |
paul@142 | 209 | offset_t client_seek(file_t *file, offset_t offset, int whence); |
paul@142 | 210 | long client_tell(file_t *file); |
paul@142 | 211 | }}} |
paul@142 | 212 | |
paul@142 | 213 | Although the client library (and the provision of files) employs mapped |
paul@142 | 214 | memory, a function can be used to explicitly reference memory for file access: |
paul@142 | 215 | |
paul@142 | 216 | {{{ |
paul@142 | 217 | void *client_mmap(file_t *file, offset_t position, offset_t length); |
paul@142 | 218 | }}} |
paul@142 | 219 | |
paul@172 | 220 | Pipes support a different mechanism for navigation involving the following |
paul@172 | 221 | functions: |
paul@172 | 222 | |
paul@172 | 223 | {{{ |
paul@172 | 224 | long client_current_region(file_t *file); |
paul@172 | 225 | long client_next_region(file_t *file); |
paul@172 | 226 | }}} |
paul@172 | 227 | |
paul@172 | 228 | Such navigation functions for files and pipes do not need to be used where the |
paul@172 | 229 | higher-level reading, writing and seeking functions are in use. |
paul@172 | 230 | |
paul@142 | 231 | For synchronisation purposes, either with the filesystem itself or with other |
paul@142 | 232 | users of the filesystem, a function resembling the traditional `fflush` |
paul@142 | 233 | function is provided: |
paul@142 | 234 | |
paul@142 | 235 | {{{ |
paul@142 | 236 | long client_flush(file_t *file); |
paul@142 | 237 | }}} |