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