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