# HG changeset patch # User Paul Boddie # Date 1628462444 -7200 # Node ID c391ec1bc36cfef1b503d9fd10f336320f1faf0c # Parent ac9e90982166740f888d024843cc5e70afc8d06e Updated the documentation to reflect recent changes. diff -r ac9e90982166 -r c391ec1bc36c docs/wiki/Files --- a/docs/wiki/Files Sun Aug 08 23:12:34 2021 +0200 +++ b/docs/wiki/Files Mon Aug 09 00:40:44 2021 +0200 @@ -10,6 +10,8 @@ == Components == At the lowest level in L4Re, files are accessed via a suite of components. +These components are principally of interest to library developers since they +only provide a limited level of abstraction. === Filesystems === @@ -17,8 +19,7 @@ `open_for_user` operation: {{{ -open_for_user(in sys_uid_t uid, in sys_gid_t gid, in sys_mode_t umask, - out cap opener) +open_for_user(in user_t user, out cap opener) }}} The operation yields a file opener appropriate for the given user credentials. @@ -47,11 +48,18 @@ pertinent is the `open` operation: {{{ -open(in flags_t flags, out offset_t size, out cap file) +open(in flags_t flags, out offset_t size, out cap file, + out object_flags_t object_flags) }}} Using the path information written to the context's memory region, the `open` -operation will obtain a reference to a file. +operation will obtain a reference to a file-like object whose characteristics +are described by the accompanying `object_flags`, these helping the client to +distinguish between files that support arbitrary memory mapping operations and +pipes that mandate sequential region-by-region access. + +Alongside regular files, directories may also be opened. Reading from them +yields a listing of directory entries. === Files === @@ -78,6 +86,83 @@ This allows the portion of the memory region dedicated to the file's contents to be extended. +=== Directories === + +Directories are also meant to be accessed like files, meaning that it should +be possible to attach them to a task using a region manager and access the +provided content, this being a listing of directory entries, via the mapped +region. + +However, unlike files which may support arbitrary mapping of their contents, +the provided content may be supplied by a pipe endpoint, thereby not +supporting precisely the same navigation mechanisms as those supported by +files. + +=== Pipe Openers === + +Distinct from filesystems but potentially used by them, pipe openers provide a +means of obtaining pipes, which are channels that support unidirectional +communication via shared memory. + +Pipe openers implement the `PipeOpener` interface and support the following +operation: + +{{{ +pipe(in offset_t size, out cap reader, out cap writer) +}}} + +The size is indicated to request pipe regions long enough for the needs of the +communicating parties, with both reader and writer endpoint capabilities being +returned. Such capabilities may be propagated to the eventual parties, these +typically being separate tasks. + +=== Pipes === + +Although not generally obtained from filesystems, pipes may be involved in +providing content from some filesystem objects such as directories. However, +they are also obtained directly from an appropriate pipe server providing pipe +opening facilities. + +Pipes expose single regions of shared memory to their endpoints, with the +writing endpoint populating one region while the reading endpoint accesses the +other. The reading endpoint may advance to the region being written, and this +will free up a new region for the writer when it has filled its region. When +the writer itself advances, it permits the reader to consume all data in the +fully populated region. Naturally, the reader may not advance ahead of the +writer. + +Pipes implement the `Pipe` interface and a number of operations to support +this interaction mechanism. + +The details of an endpoint's current region can be queried using the following +operation: + +{{{ +current_region(out offset_t populated_size, out offset_t size) +}}} + +This provides details of the populated size (or amount of written data) in a +region along with the size of the region. + +Navigation to the next available region of the pipe is performed using the +following operation: + +{{{ +next_region(inout offset_t populated_size, out offset_t size) +}}} + +Here, the populated size may be specified by the writer so that the reader may +query the current region's properties using the appropriate operation. + +The status of the pipe can be queried using the `closed` operation: + +{{{ +closed(out int closed) +}}} + +This indicates through a boolean-equivalent parameter whether one or both +endpoints have been closed. + == Libraries == The filesystem client library offers abstractions and a number of layers of @@ -101,8 +186,16 @@ void client_close(file_t *file); }}} -Reading and writing files involves functions resembling the traditional -low-level `read` and `write` functions: +Pipes are opened using a special function: + +{{{ +long client_pipe(file_t **reader, file_t **writer); +}}} + +Each pipe endpoint may be closed using `client_close`. + +Reading and writing files and pipes involves functions resembling the +traditional low-level `read` and `write` functions: {{{ offset_t client_read(file_t *file, void *buf, offset_t count); @@ -124,6 +217,17 @@ void *client_mmap(file_t *file, offset_t position, offset_t length); }}} +Pipes support a different mechanism for navigation involving the following +functions: + +{{{ +long client_current_region(file_t *file); +long client_next_region(file_t *file); +}}} + +Such navigation functions for files and pipes do not need to be used where the +higher-level reading, writing and seeking functions are in use. + For synchronisation purposes, either with the filesystem itself or with other users of the filesystem, a function resembling the traditional `fflush` function is provided: