1.1 --- a/docs/wiki/Client_Library Thu Sep 01 21:40:39 2022 +0200
1.2 +++ b/docs/wiki/Client_Library Thu Sep 01 21:52:41 2022 +0200
1.3 @@ -9,13 +9,21 @@
1.4
1.5 <<TableOfContents(2,3)>>
1.6
1.7 +== Header Files ==
1.8 +
1.9 +The following header files are pertinent to client library usage:
1.10 +
1.11 +|| '''File''' || '''Description''' ||
1.12 +|| `fsclient/client.h` || Client functions and data structures ||
1.13 +|| `systypes/fcntl.h` || Flag values for opening operations ||
1.14 +
1.15 == File Data Structures ==
1.16
1.17 Since files are accessed using file references, the `file_t` data structure is
1.18 used to wrap such references and other relevant state. Thus, such structures
1.19 can be broadly regarded as similar to the traditional `FILE` data structure.
1.20
1.21 -The fields of the `file_t` data structure are as follows:
1.22 +The members of the `file_t` data structure are as follows:
1.23
1.24 || '''Field''' || '''Description''' ||
1.25 || `ref` || A reference to the component providing file content ||
1.26 @@ -29,6 +37,10 @@
1.27 || `can_block` || Notification flags for blocking access to the file ||
1.28 || `notifications`|| Notification flags set for the file ||
1.29 || `flags` || The flags used to open the file ||
1.30 +|| `error` || Any failure or error condition on the file ||
1.31 +
1.32 +Generally, these members should not be accessed directly, mostly being
1.33 +reserved for use by the client library itself.
1.34
1.35 == Client Programming Interface ==
1.36
1.37 @@ -38,23 +50,63 @@
1.38
1.39 === Files ===
1.40
1.41 -Files are opened and closed using the following functions:
1.42 +Files are opened using the following function returning a file data structure:
1.43
1.44 {{{
1.45 file_t *client_open(const char *name, flags_t flags);
1.46 }}}
1.47
1.48 -Each file endpoint may be closed using `client_close`.
1.49 +To test whether the file was successfully open, the following function should
1.50 +be invoked, this returning a true (non-zero) value if the file was
1.51 +successfully opened:
1.52 +
1.53 +{{{
1.54 +int client_opened(file_t *file);
1.55 +}}}
1.56 +
1.57 +Each file should be closed using `client_close` regardless of whether the file
1.58 +was successfully opened.
1.59 +
1.60 +==== Example ====
1.61 +
1.62 +{{{
1.63 +file_t *file = client_open("somefile", O_RDONLY);
1.64 +
1.65 +if (client_opened(file))
1.66 +{
1.67 + /* Perform operations on file. */
1.68 +}
1.69 +
1.70 +client_close(file);
1.71 +}}}
1.72
1.73 === Pipes ===
1.74
1.75 -Pipes are opened using a special function:
1.76 +Pipes are opened using a special function returning an error code, setting the
1.77 +supplied reader and writer endpoint parameters:
1.78
1.79 {{{
1.80 long client_pipe(file_t **reader, file_t **writer, flags_t flags);
1.81 }}}
1.82
1.83 -Each pipe endpoint may be closed using `client_close`.
1.84 +Each returned pipe endpoint may be closed using `client_close`. If an error
1.85 +condition is reported using a non-zero value, the endpoints will not be
1.86 +retained and will therefore not need to be closed: the error condition is
1.87 +communicated purely via the return value.
1.88 +
1.89 +==== Example ====
1.90 +
1.91 +{{{
1.92 +file_t *reader, *writer;
1.93 +
1.94 +if (!client_pipe(&reader, &writer, 0))
1.95 +{
1.96 + /* Perform operations on pipe. */
1.97 +}
1.98 +
1.99 +client_close(reader);
1.100 +client_close(writer);
1.101 +}}}
1.102
1.103 === Closing Files and Pipes ===
1.104
1.105 @@ -94,9 +146,33 @@
1.106 memory, a function can be used to explicitly reference memory for file access:
1.107
1.108 {{{
1.109 -void *client_mmap(file_t *file, offset_t position, offset_t length);
1.110 +void *client_mmap(file_t *file, offset_t position, offset_t length,
1.111 + offset_t start_visible, offset_t end_visible,
1.112 + l4re_rm_flags_t region_flags);
1.113 }}}
1.114
1.115 +Here, a portion of the indicated `file` is exposed in a memory region, with
1.116 +the memory region corresponding to the contents of the file starting at the
1.117 +given `position` in the file and having a span of the given `length` in bytes.
1.118 +
1.119 +Additional parameters control masking of the file content. If `start_visible`
1.120 +and `end_visible` are both non-zero, then they indicate a visible span in the
1.121 +file. Such limits are applied to the mapped region, with locations
1.122 +corresponding to positions before `start_visible` and positions after
1.123 +`end_visible` yielding zero byte values.
1.124 +
1.125 +The `region_flags` indicate the memory access properties of the mapped region
1.126 +in the task obtaining it. For example, where a region will be populated with
1.127 +code, the `L4RE_DS_F_RX` flag would be appropriate, this indicating that the
1.128 +region will be read and also have its contents run or executed.
1.129 +
1.130 +'''Note:''' Currently, when masking is applied to a file, any write operations
1.131 +will cause the modified memory to be copied and modified, as opposed to
1.132 +causing modifications to the underlying file content. This behaviour may
1.133 +eventually be more configurable.
1.134 +
1.135 +=== Accessing Pipe Content in Memory Regions ===
1.136 +
1.137 Pipes support a different mechanism for navigation involving the following
1.138 functions:
1.139