1 = Files = 2 3 Access to files is provided by a number of programs acting as components. For 4 convenience, the component-level operations are wrapped up in a client library 5 that aims to provide simpler, more familiar mechanisms for opening, reading, 6 writing, and closing files, together with various other operations. 7 8 <<TableOfContents(2,3)>> 9 10 == Components == 11 12 At the lowest level in L4Re, files are accessed via a suite of components. 13 14 === Filesystems === 15 16 Filesystems implement the `Opener` interface which provides the `context` 17 operation: 18 19 {{{ 20 context(out cap context) 21 }}} 22 23 Each client program, task or thread obtains its own context because it will 24 need its own dedicated channel for communication with the filesystem. 25 26 === Contexts === 27 28 A context acts as a dataspace, meaning that it can be attached to a task using 29 a region manager and provide a buffer via a region of mapped memory that the 30 task can write to. In the case of a context, the task will write a filesystem 31 path indicating the file to be opened. 32 33 Each context allows a client program to request access to individual files via 34 operations provided by the `OpenerContext` interface, of which the most 35 pertinent is the `open` operation: 36 37 {{{ 38 open(in flags_t flags, out offset_t size, out cap file) 39 }}} 40 41 Using the path information written to the context's memory region, the `open` 42 operation will obtain a reference to a file. 43 44 === Files === 45 46 Files themselves act as dataspaces, meaning that they can be attached to a 47 task using a region manager and provide their content via a region of mapped 48 memory. Files implement the `MappedFile` interface. 49 50 Control over the region of the file provided via mapped memory occurs 51 using the `mmap` operation: 52 53 {{{ 54 mmap(in offset_t position, in offset_t length, 55 out offset_t start_pos, out offset_t end_pos, 56 out offset_t size) 57 }}} 58 59 Files also implement the more general `File` interface that provides the 60 `resize` operation: 61 62 {{{ 63 resize(inout offset_t size) 64 }}} 65 66 This allows the portion of the memory region dedicated to the file's contents 67 to be extended. 68 69 == Libraries == 70 71 The filesystem client library offers abstractions and a number of layers of 72 functionality to support interaction with components and the provision of 73 higher-level mechanisms and abstractions for file access. 74 75 === Client Library === 76 77 The client library provides functions somewhat resembling the traditional C 78 library and low-level Unix interfaces for file access, and these functions are 79 intended to support such traditional interfaces. 80 81 Since files are accessed using file references, the `file_t` data structure is 82 used to wrap such references and other relevant state. Thus, such structures 83 can be broadly regarded as similar to the traditional `FILE` data structure. 84 85 Files are opened and closed using the following functions: 86 87 {{{ 88 file_t *client_open(const char *name, flags_t flags); 89 void client_close(file_t *file); 90 }}} 91 92 Reading and writing files involves functions resembling the traditional 93 low-level `read` and `write` functions: 94 95 {{{ 96 offset_t client_read(file_t *file, void *buf, offset_t count); 97 offset_t client_write(file_t *file, const void *buf, offset_t count); 98 }}} 99 100 Support for navigation in files is provided using functions resembling the 101 traditional higher-level `fseek` and `ftell` functions: 102 103 {{{ 104 offset_t client_seek(file_t *file, offset_t offset, int whence); 105 long client_tell(file_t *file); 106 }}} 107 108 Although the client library (and the provision of files) employs mapped 109 memory, a function can be used to explicitly reference memory for file access: 110 111 {{{ 112 void *client_mmap(file_t *file, offset_t position, offset_t length); 113 }}} 114 115 For synchronisation purposes, either with the filesystem itself or with other 116 users of the filesystem, a function resembling the traditional `fflush` 117 function is provided: 118 119 {{{ 120 long client_flush(file_t *file); 121 }}}