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. 6 7 <<TableOfContents(2,3)>> 8 9 == File Data Structures == 10 11 Since files are accessed using file references, the `file_t` data structure is 12 used to wrap such references and other relevant state. Thus, such structures 13 can be broadly regarded as similar to the traditional `FILE` data structure. 14 15 The fields of the `file_t` data structure are as follows: 16 17 || '''Field''' || '''Description''' || 18 || `memory` || The memory address of the exposed file region || 19 || `start_pos` || The start position of the region in the file || 20 || `end_pos` || The end position of the region in the file || 21 || `data_end` || The amount or extent of populated data in the region || 22 || `data_current` || The offset used to track client position in the region || 23 || `size` || The total size of the file || 24 || `object_flags` || Flags indicating support for certain file features || 25 || `can_block` || Notification flags for blocking access to the file || 26 || `notifications`|| Notification flags set for the file || 27 28 == Client Programming Interface == 29 30 The client programming interface provides functions somewhat resembling the 31 traditional C library and low-level Unix interfaces for file access, and these 32 functions are intended to support such traditional interfaces. 33 34 === Files === 35 36 Files are opened and closed using the following functions: 37 38 {{{ 39 file_t *client_open(const char *name, flags_t flags); 40 }}} 41 42 Each file endpoint may be closed using `client_close`. 43 44 === Pipes === 45 46 Pipes are opened using a special function: 47 48 {{{ 49 long client_pipe(file_t **reader, file_t **writer, flags_t flags); 50 }}} 51 52 Each pipe endpoint may be closed using `client_close`. 53 54 === Closing Files and Pipes === 55 56 Closing files and pipes involves a common operation: 57 58 {{{ 59 void client_close(file_t *file); 60 }}} 61 62 When client programs terminate, the freeing of their object capabilities 63 should cause the closure of files and pipes, but programs may choose to close 64 such resources explicitly. 65 66 === Reading and Writing === 67 68 Reading and writing files and pipes involves functions resembling the 69 traditional low-level `read` and `write` functions: 70 71 {{{ 72 offset_t client_read(file_t *file, void *buf, offset_t count); 73 offset_t client_write(file_t *file, const void *buf, offset_t count); 74 }}} 75 76 === Navigation in Files === 77 78 Support for navigation in files is provided using functions resembling the 79 traditional higher-level `fseek` and `ftell` functions: 80 81 {{{ 82 offset_t client_seek(file_t *file, offset_t offset, int whence); 83 long client_tell(file_t *file); 84 }}} 85 86 === Accessing Exposed Memory Regions === 87 88 Although the client library (and the provision of files) employs mapped 89 memory, a function can be used to explicitly reference memory for file access: 90 91 {{{ 92 void *client_mmap(file_t *file, offset_t position, offset_t length); 93 }}} 94 95 Pipes support a different mechanism for navigation involving the following 96 functions: 97 98 {{{ 99 long client_current_region(file_t *file); 100 long client_next_region(file_t *file); 101 }}} 102 103 Such navigation functions for files and pipes do not need to be used where the 104 higher-level reading, writing and seeking functions are in use. 105 106 === Flushing and Synchronisation === 107 108 For synchronisation purposes, either with the filesystem itself or with other 109 users of the filesystem, a function resembling the traditional `fflush` 110 function is provided: 111 112 {{{ 113 long client_flush(file_t *file); 114 }}} 115 116 This updates the file data structure with new details of the file size, also 117 updating any altered details of the extent of the data in the currently 118 accessed region of the file. 119 120 === Notifications === 121 122 Since files and pipes may be accessed by multiple clients, necessarily for any 123 sensible use of the latter, notifications can be configured to communicate a 124 change in state to other users of these resources when they are accessed. 125 126 Notification types are specified using values encoding a number of flags, and 127 the following flags are available for this purpose: 128 129 || '''Flag''' || '''Notification Type''' || 130 || `NOTIFY_CONTENT_AVAILABLE` || Content available to read || 131 || `NOTIFY_PEER_CLOSED` || Other party has closed their endpoint || 132 || `NOTIFY_SPACE_AVAILABLE` || Space available for writing || 133 134 === Blocking Operations === 135 136 Reading and writing operations can be configured to block if data cannot be 137 read or written respectively. The following function is provided for this 138 purpose: 139 140 {{{ 141 long client_set_blocking(file_t *file, notify_flags_t flags); 142 }}} 143 144 For pipes, blocking behaviour is the default and must be disabled explicitly, 145 either by opening using the `O_NONBLOCK` flag or by calling 146 `client_set_blocking` with no flags set.