<dd><p class="Body"><a name="83748"> </a>The possible access flags are shown in <a href="c-iosys3.html#93297">Table&nbsp;3-2</a>. <p class="table"><h4 class="EntityTitle"><a name="93297"><font face="Helvetica, sans-serif" size="-1" class="sans">Table 3-2:&nbsp;&nbsp;File Access Flags</font></a></h4><table border="0" cellpadding="0" cellspacing="0"><tr><td colspan="20"><hr class="tablerule"></td></tr><tr valign="middle"><th rowspan="1" colspan="1"><div class="CellHeading"><b><a name="93303"> </a><font face="Helvetica, sans-serif" size="-1" class="sans">Flag</font></b></div></th><th rowspan="1" colspan="1"><div class="CellHeading"><b><a name="93305"> </a><font face="Helvetica, sans-serif" size="-1" class="sans">Hex Value</font></b></div></th><th rowspan="1" colspan="1"><div class="CellHeading"><b><a name="93307"> </a><font face="Helvetica, sans-serif" size="-1" class="sans">Description</font></b></div></th></tr><tr><td colspan="20"><hr class="tablerule2"></td></tr><tr valign="top"><td colspan=1 rowspan=1><div class="CellBody"><a name="93309"> </a><b class="symbol_UC">O_RDONLY</b> &nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93311"> </a>0&nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93313"> </a>Open for reading only.&nbsp;</div></td></tr><tr valign="top"><td colspan=1 rowspan=1><div class="CellBody"><a name="93315"> </a><b class="symbol_UC">O_WRONLY</b> &nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93317"> </a>1&nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93319"> </a>Open for writing only.&nbsp;</div></td></tr><tr valign="top"><td colspan=1 rowspan=1><div class="CellBody"><a name="93321"> </a><b class="symbol_UC">O_RDWR</b> &nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93323"> </a>2&nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93325"> </a>Open for reading and writing.&nbsp;</div></td></tr><tr valign="top"><td colspan=1 rowspan=1><div class="CellBody"><a name="93327"> </a><b class="symbol_UC">O_CREAT</b> &nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93329"> </a>200&nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93331"> </a>Create a new file.&nbsp;</div></td></tr><tr valign="top"><td colspan=1 rowspan=1><div class="CellBody"><a name="93333"> </a><b class="symbol_UC">O_TRUNC</b> &nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93335"> </a>400&nbsp;</div></td><td colspan=1 rowspan=1><div class="CellBody"><a name="93337"> </a>Truncate the file.&nbsp;</div></td></tr><tr><td colspan="20"><hr class="tablerule"></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p></p><dd><p class="Body"><a name="83749"> </a>The <i class="textVariable">mode</i> parameter is used in the following special cases to specify the mode (permission bits) of a file or to create subdirectories:</p></dl><dl class="margin"><p class="listspace"><ul class="Bullet" type="disc"><li><a name="83806"> </a>In general, you can open only preexisting devices and files with <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b>. However, with NFS network, dosFs, and rt11Fs devices, you can also create files with <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b> by or'ing <b class="symbol_UC">O_CREAT</b> with one of the access flags. In the case of NFS devices, <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b> requires the third parameter specifying the mode of the file:</li></ul></p><dl class="margin"><dd><pre class="Code2"><b><a name="83808"><i class="textVariable">fd</i> = open ("<i class="textVariable">name</i>", O_CREAT | O_RDWR, 0644);</a></b></pre></dl><p class="listspace"><ul class="Bullet" type="disc"><li><a name="83809"> </a>With both dosFs and NFS devices, you can use the <b class="symbol_UC">O_CREAT</b> option to create a subdirectory by setting <i class="textVariable">mode</i> to <b class="symbol_UC">FSTAT_DIR</b>. Other uses of the mode parameter with dosFs devices are ignored.</li></ul></p></dl><dl class="margin"><dd><p class="Body"><a name="83810"> </a>The <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b> routine, if successful, returns an <i class="acronym_lc">fd</i> (a small integer). This <i class="acronym_lc">fd</i> is then used in subsequent I/O calls to specify that file. The <i class="acronym_lc">fd</i> is a <i class="term">global</i> identifier that is <i class="emphasis">not</i> task specific. One task can open a file, and then any other tasks can use the resulting <i class="acronym_lc">fd</i> (for example, pipes). The <i class="acronym_lc">fd</i> remains valid until <b class="routine"><i class="routine">close</i></b><b>(</b>&nbsp;<b>)</b> is invoked with that <i class="acronym_lc">fd</i>:</p><dl class="margin"><dd><pre class="Code2"><b><a name="83814">close (<i class="textVariable">fd</i>);</a></b></pre></dl><dd><p class="Body"><a name="83815"> </a>At that point, I/O to the file is flushed (completely written out) and the <i class="acronym_lc">fd</i> can no longer be used by any task. However, the same <i class="acronym_lc">fd</i> number can again be assigned by the I/O system in any subsequent <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b>.</p><dd><p class="Body"><a name="83816"> </a>When a task exits or is deleted, the files opened by that task are not automatically closed, because <i class="acronym_lc">fd</i>s are not task specific. Thus, it is recommended that tasks explicitly close all files when they are no longer required. As stated previously, there is a limit to the number of files that can be open at one time.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="83817">3.3.4  &nbsp;&nbsp;Create and Remove</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="83819"> </a>File-oriented devices must be able to create and remove files as well as open existing files. The <b class="routine"><i class="routine">creat</i></b><b>(</b>&nbsp;<b>)</b> routine directs a file-oriented device to make a new file on the device and return a file descriptor for it. The arguments to <b class="routine"><i class="routine">creat</i></b><b>(</b>&nbsp;<b>)</b> are similar to those of <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b> except that the file name specifies the name of the new file rather than an existing one; the <b class="routine"><i class="routine">creat</i></b><b>(</b>&nbsp;<b>)</b> routine returns an <i class="acronym_lc">fd</i> identifying the new file.</p><dl class="margin"><dd><pre class="Code2"><b><a name="83821"><i class="textVariable">fd</i> = creat ("<i class="textVariable">name</i>", <i class="textVariable">flag</i>);</a></b></pre></dl><dd><p class="Body"><a name="83824"> </a>The <b class="routine"><i class="routine">remove</i></b><b>(</b>&nbsp;<b>)</b> routine removes a named file on a file-oriented device:</p><dl class="margin"><dd><pre class="Code2"><b><a name="83825">remove ("<i class="textVariable">name</i>");</a></b></pre></dl><dd><p class="Body"><a name="83826"> </a>Do not remove files while they are open.</p><dd><p class="Body"><a name="83827"> </a>With non-file-system oriented device names, <b class="routine"><i class="routine">creat</i></b><b>(</b>&nbsp;<b>)</b> acts exactly like <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b>; however, <b class="routine"><i class="routine">remove</i></b><b>(</b>&nbsp;<b>)</b> has no effect.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="83828">3.3.5  &nbsp;&nbsp;Read and Write</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="83830"> </a>After an <i class="acronym_lc">fd</i> is obtained by invoking <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b> or <b class="routine"><i class="routine">creat</i></b><b>(</b>&nbsp;<b>)</b>, tasks can read bytes from a file with <b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b> and write bytes to a file with <b class="routine"><i class="routine">write</i></b><b>(</b>&nbsp;<b>)</b>. The arguments to <b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b> are the <i class="acronym_lc">fd</i>, the address of the buffer to receive input, and the maximum number of bytes to read:</p><dl class="margin"><dd><pre class="Code2"><b><a name="83832"><i class="textVariable">nBytes</i> = read (<i class="textVariable">fd</i>, &amp;<i class="textVariable">buffer</i>, <i class="textVariable">maxBytes</i>);</a></b></pre></dl><dd><p class="Body"><a name="83833"> </a>The <b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b> routine waits for input to be available from the specified file, and returns the number of bytes actually read. For file-system devices, if the number of bytes read is less than the number requested, a subsequent <b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b> returns 0 (zero), indicating end-of-file. For non-file-system devices, the number of bytes read can be less than the number requested even if more bytes are available; a subsequent <b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b> may or may not return 0. In the case of serial devices and TCP sockets, repeated calls to <b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b> are sometimes necessary to read a specific number of bytes. (See the reference entry for <b class="routine"><i class="routine">fioRead</i></b><b>(</b>&nbsp;<b>)</b> in <b class="library">fioLib</b>). A return value of <b class="symbol_UC">ERROR</b> (-1) indicates an unsuccessful read.</p><dd><p class="Body"><a name="83836"> </a>The arguments to <b class="routine"><i class="routine">write</i></b><b>(</b>&nbsp;<b>)</b> are the <i class="acronym_lc">fd</i>, the address of the buffer that contains the data to be output, and the number of bytes to be written:</p><dl class="margin"><dd><pre class="Code2"><b><a name="83837"><i class="textVariable">actualBytes</i> = write (<i class="textVariable">fd</i>, &amp;<i class="textVariable">buffer</i>, <i class="textVariable">nBytes</i>);</a></b></pre></dl><dd><p class="Body"><a name="83838"> </a>The <b class="routine"><i class="routine">write</i></b><b>(</b>&nbsp;<b>)</b> routine ensures that all specified data is at least queued for output before returning to the caller, though the data may not yet have been written to the device (this is driver dependent). <b class="routine"><i class="routine">write</i></b><b>(</b>&nbsp;<b>)</b> returns the number of bytes written; if the number returned is not equal to the number requested, an error has occurred. </p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="83840">3.3.6  &nbsp;&nbsp;File Truncation</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="83841"> </a>It is sometimes convenient to discard part of the data in a file. After a file is open for writing, you can use the <b class="routine"><i class="routine">ftruncate</i></b><b>(&nbsp;)</b><b class="routine"><i class="routine"> </i></b>routine to truncate a file to a specified size. Its arguments are an <i class="acronym_lc">fd </i>and the desired length of the file:</p><dl class="margin"><dd><pre class="Code2"><b><a name="83843"><i class="textVariable">status </i>= ftruncate (<i class="textVariable">fd</i>, <i class="textVariable">length</i>);</a></b></pre></dl><dd><p class="Body"><a name="83844"> </a>If it succeeds in truncating the file, <b class="routine"><i class="routine">ftruncate</i></b><b>(&nbsp;)</b>returns <b class="symbol_UC">OK</b>. If the size specified is larger than the actual size of the file, or if the <i class="acronym_lc">fd</i> refers to a device that cannot be truncated, <b class="routine"><i class="routine">ftruncate</i></b><b>(&nbsp;)</b>returns <b class="symbol_UC">ERROR</b>, and sets <b class="symbol_lc">errno</b> to <b class="symbol_UC">EINVAL</b>.</p><dd><p class="Body"><a name="83845"> </a>The <b class="routine"><i class="routine">ftruncate</i></b><b>(&nbsp;)</b> routine is part of the POSIX 1003.1b standard, but this implementation is only partially POSIX-compliant: creation and modification times are not updated. This call is supported only by <b class="library">dosFsLib</b>, the DOS-compatible file system library.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="83847">3.3.7  &nbsp;&nbsp;I/O Control</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="83849"> </a>The <b class="routine"><i class="routine">ioctl</i></b><b>(</b>&nbsp;<b>)</b> routine is an open-ended mechanism for performing any I/O functions that do not fit the other basic I/O calls. Examples include determining how many bytes are currently available for input, setting device-specific options, obtaining information about a file system, and positioning random-access files to specific byte positions. The arguments to the <b class="routine"><i class="routine">ioctl</i></b><b>(</b>&nbsp;<b>)</b> routine are the <i class="acronym_lc">fd</i>, a code that identifies the control function requested, and an optional function-dependent argument:</p><dl class="margin">