1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/Files Fri Jul 16 00:40:22 2021 +0200
1.3 @@ -0,0 +1,121 @@
1.4 += Files =
1.5 +
1.6 +Access to files is provided by a number of programs acting as components. For
1.7 +convenience, the component-level operations are wrapped up in a client library
1.8 +that aims to provide simpler, more familiar mechanisms for opening, reading,
1.9 +writing, and closing files, together with various other operations.
1.10 +
1.11 +<<TableOfContents(2,3)>>
1.12 +
1.13 +== Components ==
1.14 +
1.15 +At the lowest level in L4Re, files are accessed via a suite of components.
1.16 +
1.17 +=== Filesystems ===
1.18 +
1.19 +Filesystems implement the `Opener` interface which provides the `context`
1.20 +operation:
1.21 +
1.22 +{{{
1.23 +context(out cap context)
1.24 +}}}
1.25 +
1.26 +Each client program, task or thread obtains its own context because it will
1.27 +need its own dedicated channel for communication with the filesystem.
1.28 +
1.29 +=== Contexts ===
1.30 +
1.31 +A context acts as a dataspace, meaning that it can be attached to a task using
1.32 +a region manager and provide a buffer via a region of mapped memory that the
1.33 +task can write to. In the case of a context, the task will write a filesystem
1.34 +path indicating the file to be opened.
1.35 +
1.36 +Each context allows a client program to request access to individual files via
1.37 +operations provided by the `OpenerContext` interface, of which the most
1.38 +pertinent is the `open` operation:
1.39 +
1.40 +{{{
1.41 +open(in flags_t flags, out offset_t size, out cap file)
1.42 +}}}
1.43 +
1.44 +Using the path information written to the context's memory region, the `open`
1.45 +operation will obtain a reference to a file.
1.46 +
1.47 +=== Files ===
1.48 +
1.49 +Files themselves act as dataspaces, meaning that they can be attached to a
1.50 +task using a region manager and provide their content via a region of mapped
1.51 +memory. Files implement the `MappedFile` interface.
1.52 +
1.53 +Control over the region of the file provided via mapped memory occurs
1.54 +using the `mmap` operation:
1.55 +
1.56 +{{{
1.57 +mmap(in offset_t position, in offset_t length,
1.58 + out offset_t start_pos, out offset_t end_pos,
1.59 + out offset_t size)
1.60 +}}}
1.61 +
1.62 +Files also implement the more general `File` interface that provides the
1.63 +`resize` operation:
1.64 +
1.65 +{{{
1.66 +resize(inout offset_t size)
1.67 +}}}
1.68 +
1.69 +This allows the portion of the memory region dedicated to the file's contents
1.70 +to be extended.
1.71 +
1.72 +== Libraries ==
1.73 +
1.74 +The filesystem client library offers abstractions and a number of layers of
1.75 +functionality to support interaction with components and the provision of
1.76 +higher-level mechanisms and abstractions for file access.
1.77 +
1.78 +=== Client Library ===
1.79 +
1.80 +The client library provides functions somewhat resembling the traditional C
1.81 +library and low-level Unix interfaces for file access, and these functions are
1.82 +intended to support such traditional interfaces.
1.83 +
1.84 +Since files are accessed using file references, the `file_t` data structure is
1.85 +used to wrap such references and other relevant state. Thus, such structures
1.86 +can be broadly regarded as similar to the traditional `FILE` data structure.
1.87 +
1.88 +Files are opened and closed using the following functions:
1.89 +
1.90 +{{{
1.91 +file_t *client_open(const char *name, flags_t flags);
1.92 +void client_close(file_t *file);
1.93 +}}}
1.94 +
1.95 +Reading and writing files involves functions resembling the traditional
1.96 +low-level `read` and `write` functions:
1.97 +
1.98 +{{{
1.99 +offset_t client_read(file_t *file, void *buf, offset_t count);
1.100 +offset_t client_write(file_t *file, const void *buf, offset_t count);
1.101 +}}}
1.102 +
1.103 +Support for navigation in files is provided using functions resembling the
1.104 +traditional higher-level `fseek` and `ftell` functions:
1.105 +
1.106 +{{{
1.107 +offset_t client_seek(file_t *file, offset_t offset, int whence);
1.108 +long client_tell(file_t *file);
1.109 +}}}
1.110 +
1.111 +Although the client library (and the provision of files) employs mapped
1.112 +memory, a function can be used to explicitly reference memory for file access:
1.113 +
1.114 +{{{
1.115 +void *client_mmap(file_t *file, offset_t position, offset_t length);
1.116 +}}}
1.117 +
1.118 +For synchronisation purposes, either with the filesystem itself or with other
1.119 +users of the filesystem, a function resembling the traditional `fflush`
1.120 +function is provided:
1.121 +
1.122 +{{{
1.123 +long client_flush(file_t *file);
1.124 +}}}