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