1 = Client Library = 2 3 The filesystem client library offers abstractions and a number of layers of 4 functionality to support interaction with [[Components|components]] and the 5 provision of higher-level mechanisms and abstractions for file access. In 6 particular, the client library is intended for use by a conventional C 7 library, with the functions in the C library invoking client library functions 8 and employing client library structures internally. 9 10 <<TableOfContents(2,3)>> 11 12 == Header Files == 13 14 The following header files are pertinent to client library usage: 15 16 || '''File''' || '''Description''' || 17 || `fsclient/client.h` || Client functions and data structures || 18 || `systypes/fcntl.h` || Flag values for opening operations || 19 20 == File Data Structures == 21 22 Since files are accessed using file references, the `file_t` data structure is 23 used to wrap such references and other relevant state. Thus, such structures 24 can be broadly regarded as similar to the traditional `FILE` data structure. 25 26 The members of the `file_t` data structure are as follows: 27 28 || '''Field''' || '''Description''' || 29 || `ref` || A reference to the component providing file content || 30 || `memory` || The memory address of the exposed file region || 31 || `start_pos` || The start position of the region in the file || 32 || `end_pos` || The end position of the region in the file || 33 || `data_end` || The amount or extent of populated data in the region || 34 || `data_current` || The offset used to track client position in the region || 35 || `size` || The total size of the file || 36 || `object_flags` || Flags indicating support for certain file features || 37 || `can_block` || Notification flags for blocking access to the file || 38 || `notifications`|| Notification flags set for the file || 39 || `flags` || The flags used to open the file || 40 || `error` || Any failure or error condition on the file || 41 42 Generally, these members should not be accessed directly, mostly being 43 reserved for use by the client library itself. 44 45 == Client Programming Interface == 46 47 The client programming interface provides functions somewhat resembling the 48 traditional C library and low-level Unix interfaces for file access, and these 49 functions are intended to support such traditional interfaces. 50 51 === Files === 52 53 Files are opened using the following function returning a file data structure: 54 55 {{{ 56 file_t *client_open(const char *name, flags_t flags); 57 }}} 58 59 To test whether the file was successfully open, the following function should 60 be invoked, this returning a true (non-zero) value if the file was 61 successfully opened: 62 63 {{{ 64 int client_opened(file_t *file); 65 }}} 66 67 Each file should be closed using `client_close` regardless of whether the file 68 was successfully opened. 69 70 ==== Example ==== 71 72 {{{ 73 file_t *file = client_open("somefile", O_RDONLY); 74 75 if (client_opened(file)) 76 { 77 /* Perform operations on file. */ 78 } 79 80 client_close(file); 81 }}} 82 83 === Pipes === 84 85 Pipes are opened using a special function returning an error code, setting the 86 supplied reader and writer endpoint parameters: 87 88 {{{ 89 long client_pipe(file_t **reader, file_t **writer, flags_t flags); 90 }}} 91 92 Each returned pipe endpoint may be closed using `client_close`. If an error 93 condition is reported using a non-zero value, the endpoints will not be 94 retained and will therefore not need to be closed: the error condition is 95 communicated purely via the return value. 96 97 ==== Example ==== 98 99 {{{ 100 file_t *reader, *writer; 101 102 if (!client_pipe(&reader, &writer, 0)) 103 { 104 /* Perform operations on pipe. */ 105 } 106 107 client_close(reader); 108 client_close(writer); 109 }}} 110 111 === Closing Files and Pipes === 112 113 Closing files and pipes involves a common operation: 114 115 {{{ 116 void client_close(file_t *file); 117 }}} 118 119 When client programs terminate, the freeing of their object capabilities 120 should cause the closure of files and pipes, but programs may choose to close 121 such resources explicitly. 122 123 === Reading and Writing === 124 125 Reading and writing files and pipes involves functions resembling the 126 traditional low-level `read` and `write` functions: 127 128 {{{ 129 offset_t client_read(file_t *file, void *buf, offset_t count); 130 offset_t client_write(file_t *file, const void *buf, offset_t count); 131 }}} 132 133 === Navigation in Files === 134 135 Support for navigation in files is provided using functions resembling the 136 traditional higher-level `fseek` and `ftell` functions: 137 138 {{{ 139 offset_t client_seek(file_t *file, offset_t offset, int whence); 140 long client_tell(file_t *file); 141 }}} 142 143 === Accessing Exposed Memory Regions === 144 145 Although the client library (and the provision of files) employs mapped 146 memory, a function can be used to explicitly reference memory for file access: 147 148 {{{ 149 void *client_mmap(file_t *file, offset_t position, offset_t length, 150 offset_t start_visible, offset_t end_visible, 151 l4re_rm_flags_t region_flags); 152 }}} 153 154 Here, a portion of the indicated `file` is exposed in a memory region, with 155 the memory region corresponding to the contents of the file starting at the 156 given `position` in the file and having a span of the given `length` in bytes. 157 158 Additional parameters control masking of the file content. If `start_visible` 159 and `end_visible` are both non-zero, then they indicate a visible span in the 160 file. Such limits are applied to the mapped region, with locations 161 corresponding to positions before `start_visible` and positions after 162 `end_visible` yielding zero byte values. 163 164 The `region_flags` indicate the memory access properties of the mapped region 165 in the task obtaining it. For example, where a region will be populated with 166 code, the `L4RE_DS_F_RX` flag would be appropriate, this indicating that the 167 region will be read and also have its contents run or executed. 168 169 '''Note:''' Currently, when masking is applied to a file, any write operations 170 will cause the modified memory to be copied and modified, as opposed to 171 causing modifications to the underlying file content. This behaviour may 172 eventually be more configurable. 173 174 === Accessing Pipe Content in Memory Regions === 175 176 Pipes support a different mechanism for navigation involving the following 177 functions: 178 179 {{{ 180 long client_current_region(file_t *file); 181 long client_next_region(file_t *file); 182 }}} 183 184 Such navigation functions for files and pipes do not need to be used where the 185 higher-level reading, writing and seeking functions are in use. 186 187 === Flushing and Synchronisation === 188 189 For synchronisation purposes, either with the filesystem itself or with other 190 users of the filesystem, a function resembling the traditional `fflush` 191 function is provided: 192 193 {{{ 194 long client_flush(file_t *file); 195 }}} 196 197 This updates the file data structure with new details of the file size, also 198 updating any altered details of the extent of the data in the currently 199 accessed region of the file. 200 201 === Notifications === 202 203 Since files and pipes may be accessed by multiple clients, necessarily for any 204 sensible use of the latter, notifications can be configured to communicate a 205 change in state to other users of these resources when they are accessed. 206 207 Notification types are specified using values encoding a number of flags, and 208 the following flags are available for this purpose: 209 210 || '''Flag''' || '''Notification Type''' || 211 || `NOTIFY_CONTENT_AVAILABLE` || Content available to read || 212 || `NOTIFY_PEER_CLOSED` || Other party has closed their endpoint || 213 || `NOTIFY_SPACE_AVAILABLE` || Space available for writing || 214 215 === Blocking Operations === 216 217 Reading and writing operations can be configured to block if data cannot be 218 read or written respectively. The following function is provided for this 219 purpose: 220 221 {{{ 222 long client_set_blocking(file_t *file, notify_flags_t flags); 223 }}} 224 225 For pipes, blocking behaviour is the default and must be disabled explicitly, 226 either by opening using the `O_NONBLOCK` flag or by calling 227 `client_set_blocking` with no flags set.