1.1 --- a/docs/wiki/Files Sun Aug 08 23:12:34 2021 +0200
1.2 +++ b/docs/wiki/Files Mon Aug 09 00:40:44 2021 +0200
1.3 @@ -10,6 +10,8 @@
1.4 == Components ==
1.5
1.6 At the lowest level in L4Re, files are accessed via a suite of components.
1.7 +These components are principally of interest to library developers since they
1.8 +only provide a limited level of abstraction.
1.9
1.10 === Filesystems ===
1.11
1.12 @@ -17,8 +19,7 @@
1.13 `open_for_user` operation:
1.14
1.15 {{{
1.16 -open_for_user(in sys_uid_t uid, in sys_gid_t gid, in sys_mode_t umask,
1.17 - out cap opener)
1.18 +open_for_user(in user_t user, out cap opener)
1.19 }}}
1.20
1.21 The operation yields a file opener appropriate for the given user credentials.
1.22 @@ -47,11 +48,18 @@
1.23 pertinent is the `open` operation:
1.24
1.25 {{{
1.26 -open(in flags_t flags, out offset_t size, out cap file)
1.27 +open(in flags_t flags, out offset_t size, out cap file,
1.28 + out object_flags_t object_flags)
1.29 }}}
1.30
1.31 Using the path information written to the context's memory region, the `open`
1.32 -operation will obtain a reference to a file.
1.33 +operation will obtain a reference to a file-like object whose characteristics
1.34 +are described by the accompanying `object_flags`, these helping the client to
1.35 +distinguish between files that support arbitrary memory mapping operations and
1.36 +pipes that mandate sequential region-by-region access.
1.37 +
1.38 +Alongside regular files, directories may also be opened. Reading from them
1.39 +yields a listing of directory entries.
1.40
1.41 === Files ===
1.42
1.43 @@ -78,6 +86,83 @@
1.44 This allows the portion of the memory region dedicated to the file's contents
1.45 to be extended.
1.46
1.47 +=== Directories ===
1.48 +
1.49 +Directories are also meant to be accessed like files, meaning that it should
1.50 +be possible to attach them to a task using a region manager and access the
1.51 +provided content, this being a listing of directory entries, via the mapped
1.52 +region.
1.53 +
1.54 +However, unlike files which may support arbitrary mapping of their contents,
1.55 +the provided content may be supplied by a pipe endpoint, thereby not
1.56 +supporting precisely the same navigation mechanisms as those supported by
1.57 +files.
1.58 +
1.59 +=== Pipe Openers ===
1.60 +
1.61 +Distinct from filesystems but potentially used by them, pipe openers provide a
1.62 +means of obtaining pipes, which are channels that support unidirectional
1.63 +communication via shared memory.
1.64 +
1.65 +Pipe openers implement the `PipeOpener` interface and support the following
1.66 +operation:
1.67 +
1.68 +{{{
1.69 +pipe(in offset_t size, out cap reader, out cap writer)
1.70 +}}}
1.71 +
1.72 +The size is indicated to request pipe regions long enough for the needs of the
1.73 +communicating parties, with both reader and writer endpoint capabilities being
1.74 +returned. Such capabilities may be propagated to the eventual parties, these
1.75 +typically being separate tasks.
1.76 +
1.77 +=== Pipes ===
1.78 +
1.79 +Although not generally obtained from filesystems, pipes may be involved in
1.80 +providing content from some filesystem objects such as directories. However,
1.81 +they are also obtained directly from an appropriate pipe server providing pipe
1.82 +opening facilities.
1.83 +
1.84 +Pipes expose single regions of shared memory to their endpoints, with the
1.85 +writing endpoint populating one region while the reading endpoint accesses the
1.86 +other. The reading endpoint may advance to the region being written, and this
1.87 +will free up a new region for the writer when it has filled its region. When
1.88 +the writer itself advances, it permits the reader to consume all data in the
1.89 +fully populated region. Naturally, the reader may not advance ahead of the
1.90 +writer.
1.91 +
1.92 +Pipes implement the `Pipe` interface and a number of operations to support
1.93 +this interaction mechanism.
1.94 +
1.95 +The details of an endpoint's current region can be queried using the following
1.96 +operation:
1.97 +
1.98 +{{{
1.99 +current_region(out offset_t populated_size, out offset_t size)
1.100 +}}}
1.101 +
1.102 +This provides details of the populated size (or amount of written data) in a
1.103 +region along with the size of the region.
1.104 +
1.105 +Navigation to the next available region of the pipe is performed using the
1.106 +following operation:
1.107 +
1.108 +{{{
1.109 +next_region(inout offset_t populated_size, out offset_t size)
1.110 +}}}
1.111 +
1.112 +Here, the populated size may be specified by the writer so that the reader may
1.113 +query the current region's properties using the appropriate operation.
1.114 +
1.115 +The status of the pipe can be queried using the `closed` operation:
1.116 +
1.117 +{{{
1.118 +closed(out int closed)
1.119 +}}}
1.120 +
1.121 +This indicates through a boolean-equivalent parameter whether one or both
1.122 +endpoints have been closed.
1.123 +
1.124 == Libraries ==
1.125
1.126 The filesystem client library offers abstractions and a number of layers of
1.127 @@ -101,8 +186,16 @@
1.128 void client_close(file_t *file);
1.129 }}}
1.130
1.131 -Reading and writing files involves functions resembling the traditional
1.132 -low-level `read` and `write` functions:
1.133 +Pipes are opened using a special function:
1.134 +
1.135 +{{{
1.136 +long client_pipe(file_t **reader, file_t **writer);
1.137 +}}}
1.138 +
1.139 +Each pipe endpoint may be closed using `client_close`.
1.140 +
1.141 +Reading and writing files and pipes involves functions resembling the
1.142 +traditional low-level `read` and `write` functions:
1.143
1.144 {{{
1.145 offset_t client_read(file_t *file, void *buf, offset_t count);
1.146 @@ -124,6 +217,17 @@
1.147 void *client_mmap(file_t *file, offset_t position, offset_t length);
1.148 }}}
1.149
1.150 +Pipes support a different mechanism for navigation involving the following
1.151 +functions:
1.152 +
1.153 +{{{
1.154 +long client_current_region(file_t *file);
1.155 +long client_next_region(file_t *file);
1.156 +}}}
1.157 +
1.158 +Such navigation functions for files and pipes do not need to be used where the
1.159 +higher-level reading, writing and seeking functions are in use.
1.160 +
1.161 For synchronisation purposes, either with the filesystem itself or with other
1.162 users of the filesystem, a function resembling the traditional `fflush`
1.163 function is provided: