1<html> 2<head> 3<title>firstworks Programming with Rudiments using the file class</title> 4<link href="../css/styles.css" rel="stylesheet"> 5</head> 6<body> 7 8<a name="file"> 9<span class="heading">Using the file class</span><br><br> 10 11<ul> 12<li><a href="#intro">Introduction</a></li> 13<li><a href="#create">Creating a File</a></li> 14<li><a href="#remove">Removing a File</a></li> 15<li><a href="#open">Opening and Closing Files</a></li> 16<li><a href="#props">File Properties</a></li> 17<li><a href="#read">Read Access</a></li> 18<li><a href="#write">Write Access</a></li> 19<li><a href="#random">Random Access</a></li> 20<li><a href="#lock">File Locks</a></li> 21<li><a href="#truncate">Truncating a File</a></li> 22<li><a href="#buffers">Buffered File Access</a></li> 23<li><a href="#optimizations">Optimizing File Access</a></li> 24<li><a href="#temp">Temporary Files</a></li> 25<li><a href="#links">Links</a></li> 26<li><a href="#fifos">Fifos</a></li> 27<li><a href="#pipes">Named Pipes</a></li> 28<li><a href="#convenience">Convenience Methods</a></li> 29</ul> 30 31 32<br> 33<a name="intro"></a> 34<h3>Introduction</h3> 35 36<p>The <a href="../classes/html/classfile.html">file class</a> provides methods for creating and accessing files.</p> 37 38<p>The filedescriptor class provides methods for generic input and output to file descriptors. The file class inherits from filedescriptor and adds methods that are specific to files. However, when using the file class, you will likely make heavy use of filedescriptor methods such as read() and write().</p> 39 40 41<br> 42<a name="create"></a> 43<h3>Creating a File</h3> 44 45<p>The following example demonstrates the different ways to create a file.</p> 46 47<p>Note that when creating a file, the file permissions must be supplied. Rudiments supports unix-style file permissions, even on Windows. See the <a href="permissions.html">permissions class</a> for more information.</p> 48 49<blockquote class="code"> 50@file-create.cpp.html@ 51</blockquote> 52 53 54<br> 55<a name="remove"></a> 56<h3>Removing a File</h3> 57 58<p>The file class provides a static method for removing a file.</p> 59 60<blockquote class="code"> 61@file-remove.cpp.html@ 62</blockquote> 63 64 65<br> 66<a name="open"></a> 67<h3>Opening a File</h3> 68 69<p>To open a file, call one of the open() methods.</p> 70 71<p>The open() methods take the filename to open and a set of flags.</p> 72 73<p>Flags may include one or more of the following flags, or'ed together.</p> 74 75<ul> 76<li>O_RDONLY - Open the file in read-only mode.</li> 77<li>O_WRONLY - Open the file in write-only mode.</li> 78<li>O_RDWR - Open the file in write-only mode.</li> 79<li>O_APPEND - Set the position to the end of the file.</li> 80<li>O_TRUNC - Truncate the file. Requires O_WRONLY or O_RDWR.</li> 81<li>O_CREAT - Creates the file if it doesn't exist. See O_EXCL.</li> 82<li>O_EXCL - Requires O_CREAT. Causes O_CREAT to fail if the file already exists. Without O_EXCL, O_CREAT will succeed, and just open the file, if the file already exists.</li> 83</ul> 84 85<p>Many platforms support additional, platform-specific flags.</p> 86 87<p>There are two varieties of the open() method. They both take filename and flags. The second also takes permissions. If the flags include O_CREAT then the permissions are used when creating the file. If the flags don't include O_CREAT then the permissions are ignored.</p> 88 89<p>Files are closed when the instance of the file class is deleted, or when the same instance is used to open another file, but they can also be closed manually using the close() method.</p> 90 91<p>The following example demonstrates various ways to open and close a file.</p> 92 93<blockquote class="code"> 94@file-open.cpp.html@ 95</blockquote> 96 97 98<br> 99<a name="props"></a> 100<h3>File Properties</h3> 101 102<p>The file class provides methods for getting various file properties including permissions, ownership, size, type, and access and modification times.</p> 103 104<p>The following example opens a file and prints out various file properties. Note that other classes must be used to convert the codes, ids and raw times to human-readable form.</p> 105 106<p>Note that this program depends on the existence of testfile1, so you'll have to touch it, or run one of the programs above to create it.</p> 107 108<blockquote class="code"> 109@file-getprops.cpp.html@ 110</blockquote> 111 112<p>There are 3 other methods worth mentioning as well:</p> 113 114<dl> 115<dt>getCurrentProperties()</dt> 116<dd>By default, the file class fetches file properties when open() or create() are called. If a property is changed, then the old value will still be reflected when the method to get it is called, unless this method is called first.</dd> 117<dt>dontGetCurrentPropertiesOnOpen()</dt> 118<dd>By default, the file class fetches file properties when open() or create() are called. If this method is called, then file properties will not be fetched unless getCurrentProperties() is called manually.</dd> 119<dt>getCurrentPropertiesOnOpen()</dt> 120<dd>Returns the class to its default behavior of fetching file properties when open() or create() are called.</dd> 121</dl> 122 123 124<br> 125<a name="read"></a> 126<h3>Read Access</h3> 127 128<p>The filedescriptor class (which the file class inherits from) provides read() methods to read data from files and file descriptors.</p> 129 130<p>Methods are provided for reading all primitive types directly. This example opens a file in read-only mode and reads primitive data types from it.</p> 131 132<blockquote class="code"> 133@file-read.cpp.html@ 134</blockquote> 135 136<p>Methods are also provided for reading arbitrary data into buffers. This example approximates the unix "cat" or Windows "type" utility. It opens a file in read-only mode, reads it in chunks, and prints out each chunk.</p> 137 138<blockquote class="code"> 139@cat.cpp.html@ 140</blockquote> 141 142<p>A read() method is also provided that reads until it encounters a specified terminator. This example reads a file, one line at a time, and prints out each line.</p> 143 144<blockquote class="code"> 145@file-readline.cpp.html@ 146</blockquote> 147 148 149<br> 150<a name="write"></a> 151<h3>Write Access</h3> 152 153<p>The filedescriptor class (which the file class inherits from) provides write() methods to write data to files and file descriptors.</p> 154 155<p>Methods are provided for writing primitive types as well as blocks of character or binary data. This example creates a file in write-only mode and writes various types of data to it.</p> 156 157<blockquote class="code"> 158@file-write.cpp.html@ 159</blockquote> 160 161 162<br> 163<a name="random"></a> 164<h3>Random Access</h3> 165 166<p>It is possible to open a file for both reading and writing, write to it, jump around, overwrite parts, jump around some more, and read from it.</p> 167 168<p>This example illustrates random file access.</p> 169 170<blockquote class="code"> 171@file-random.cpp.html@ 172</blockquote> 173 174 175<br> 176<a name="lock"></a> 177<h3>File Locks</h3> 178 179<p>...</p> 180 181<blockquote class="code"> 182@file-lock.cpp.html@ 183</blockquote> 184 185 186<br> 187<a name="truncate"></a> 188<h3>Truncating a File</h3> 189 190<p>If you want to erase the current contents of a file, there are two options. The first is to open the file using the O_TRUNC flag. But, if you want to truncate the file after you've already opened it, you can use the truncate() method.</p> 191 192<blockquote class="code"> 193@file-truncate.cpp.html@ 194</blockquote> 195 196 197<br> 198<a name="buffers"></a> 199<h3>Buffered File Access</h3> 200 201<p>If your program does a lot of reads and writes, then you probably want to buffer them. There are two main reasons for this:</p> 202 203<ul> 204<li>Accessing storage is much slower than accessing memory.</li> 205<li>System calls are generally slower than library calls.</li> 206</ul> 207 208<p>Both file systems and physical storage are typically organized in blocks. Each block is some number of bytes. A read or write of the entire block costs the same as reading or writing a single byte. If you use buffers that are the same size as the file system's block size, then reading or writing the entire buffer takes only marginally more time than reading or writing a single byte.</p> 209 210<p>Also, even if the kernel or disk does some kind of buffering, each read or write still requires a system call. In effect, the program tells the kernel to do the read or write, hands control over to the kernel, waits for it to do it, and then waits for it to hand control back. The overhead of the switching involved usually makes the whole process slower than if the program read or wrote directly from a buffer under its own control.</p> 211 212<p>Buffering always helps writes and usually helps reads. How much is platform-specific.</p> 213 214<p>The filesystem class makes buffered I/O simple. There are only three methods involved:</p> 215 216<dl> 217<dt>setReadBufferSize()</dt> 218<dd>Sets the size of the buffer used when reading.</dd> 219<dt>setWriteBufferSize()</dt> 220<dd>Sets the size of the buffer used when writing.</dd> 221<dt>flushWriteBuffer()</dt> 222<dd>Makes sure that any data that is buffered but hasn't been written to storage, actually gets written to storage.</dd> 223</dl> 224 225<p>Reading is completely transparent. The read buffer is filled during the first read, and filled again when all bytes have been read from it.</p> 226 227<p>Writing is nearly transparent. Bytes are written to the buffer. When the buffer is full, it is written to storage. However, when the program is done writing, it should call flushWriteBuffer() to make sure that any data still in the buffer is written to storage.</p> 228 229<p>The example below illustrates buffered I/O.</p> 230 231<blockquote class="code"> 232@file-buffers.cpp.html@ 233</blockquote> 234 235 236<br> 237<a name="optimizations"></a> 238<h3>Optimizing File Access</h3> 239 240<p>...</p> 241 242<blockquote class="code"> 243@file-optimizations.cpp.html@ 244</blockquote> 245 246 247<br> 248<a name="temp"></a> 249<h3>Temporary Files</h3> 250 251<p>...</p> 252 253<blockquote class="code"> 254@file-temp.cpp.html@ 255</blockquote> 256 257 258 259<br> 260<a name="links"></a> 261<h3>Links</h3> 262 263<p>...</p> 264 265<blockquote class="code"> 266@file-links.cpp.html@ 267</blockquote> 268 269 270<br> 271<a name="fifos"></a> 272<h3>Fifos</h3> 273 274<p>...</p> 275 276<blockquote class="code"> 277@file-fifos.cpp.html@ 278</blockquote> 279 280 281<br> 282<a name="pipes"></a> 283<h3>Named Pipes</h3> 284 285<p>...</p> 286 287<blockquote class="code"> 288@file-pipes.cpp.html@ 289</blockquote> 290 291 292<br> 293<a name="convenience"></a> 294<h3>Convenience Methods</h3> 295 296<p>...</p> 297 298<blockquote class="code"> 299@file-convenience.cpp.html@ 300</blockquote> 301 302 303</body> 304</html> 305