Add debugging information for nacl_io library.

native_client_sdk/doc_generated/devguide/coding/nacl_io.html

 {{+bindTo:partials.standard_nacl_article}}
 
 <section id="the-nacl-io-library">
 <span id="nacl-io"></span><h1 id="the-nacl-io-library"><span id="nacl-io"></span>The nacl_io Library</h1>
 <div class="contents local" id="contents" style="display: none">
 <ul class="small-gap">
 <li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
 <li><a class="reference internal" href="#using-nacl-io" id="id2">Using nacl_io</a></li>
-<li><p class="first"><a class="reference internal" href="#the-nacl-io-demo" id="id3">The nacl_io demo</a></p>
+<li><a class="reference internal" href="#logging-in-nacl-io" id="id3">Logging in nacl_io</a></li>
+<li><p class="first"><a class="reference internal" href="#the-nacl-io-demo" id="id4">The nacl_io demo</a></p>
 <ul class="small-gap">
-<li><a class="reference internal" href="#building-and-running-the-demo" id="id4">Building and running the demo</a></li>
-<li><a class="reference internal" href="#a-look-at-the-code" id="id5">A look at the code</a></li>
+<li><a class="reference internal" href="#building-and-running-the-demo" id="id5">Building and running the demo</a></li>
+<li><a class="reference internal" href="#a-look-at-the-code" id="id6">A look at the code</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#reference-information" id="id6">Reference information</a></li>
+<li><a class="reference internal" href="#reference-information" id="id7">Reference Information</a></li>
 </ul>
 
 </div><h2 id="introduction">Introduction</h2>
 <p><code>nacl_io</code> is a utility library that provides implementations of standard
 C APIs such as POSIX I/O (<code>stdio.h</code>) and BSD sockets (<code>sys/socket.h</code>).
 Its primary function is to allow code that uses these standard APIs to be
 compiled and used in a Native Client module. The library is included as part
 of Native Client SDK and is implemented in on top of Pepper API.</p>
 <p>Since Native Client modules cannot access the host machine&#8217;s file system
-directly, nacl_io provides several alternative filesystem types which
-can be used by the application. For example, the Chrome browser supports the
-<a class="reference external" href="http://www.html5rocks.com/en/tutorials/file/filesystem/">HTML5 File System API</a> which provides
-access to a protected area of the local file system. This filesystem can
-be accessed by an HTML page using JavaScript commands, and also by a Native
-Client module using the Pepper <a class="reference internal" href="/native-client/devguide/coding/file-io.html"><em>File IO API</em></a>. With nacl_io
-a Native Client application can mount an HTML5 filesystem and access it via
-standard POSIX I/O function such as <code>fopen</code>, <code>fseek</code>, <code>fread</code>,
-<code>fwrite</code>, and <code>fclose</code>, or their low level UNIX counterparts <code>open</code>,
-<code>lseek</code>, <code>read</code>, <code>write</code> and <code>close</code>.</p>
-<p>As well as the HTML5 file system, nacl_io provides several other file system
-types which are described in the table below:</p>
+directly, nacl_io provides several alternative filesystem types which can be
+used by the application. For example, the Chrome browser supports the <a class="reference external" href="http://www.html5rocks.com/en/tutorials/file/filesystem/">HTML5
+File System API</a>
+which provides access to a protected area of the local file system. This
+filesystem can be accessed by an HTML page using JavaScript commands, and also
+by a Native Client module using the Pepper <a class="reference internal" href="/native-client/devguide/coding/file-io.html"><em>File IO API</em></a>.</p>
+<p>With nacl_io a Native Client application can mount an HTML5 filesystem and
+access it via standard POSIX I/O function such as <code>fopen</code>, <code>fseek</code>,
+<code>fread</code>, <code>fwrite</code>, and <code>fclose</code>, or their low level UNIX counterparts
+<code>open</code>, <code>lseek</code>, <code>read</code>, <code>write</code> and <code>close</code>. As well as the HTML5
+file system, nacl_io provides several other file system types which are
+described in the table below:</p>
 <table border="1" class="docutils">
 <colgroup>
 </colgroup>
 <thead valign="bottom">
 <tr class="row-odd"><th class="head">File System</th>
 <th class="head">Description</th>
 </tr>
 </thead>
 <tbody valign="top">
 <tr class="row-even"><td>memfs</td>
@@ skipping 23 matching lines @@
 to <code>mount</code> for the different filesystem types are detailed in
 <code>include/nacl_io/nacl_io.h</code>.</li>
 <li>If you are going to mount an HTML5 file system, be sure to allocate space
 for it. You can either set the <code>unlimitedStorage</code> permission in the app&#8217;s
 Web Store manifest file, or call the HTML5 QuotaManagement API. These
 options are explained in the <a class="reference internal" href="/native-client/devguide/coding/file-io.html#quota-management"><em>File IO documentation</em></a>.</li>
 <li>Make sure that file and socket API calls are all made from the background
 thread. This is because the main Pepper thread does not support the blocking
 behavior needed by the POSIX I/O operations.</li>
 </ol>
+<h2 id="logging-in-nacl-io">Logging in nacl_io</h2>
+<p>Unlike most input/output for nacl_io, internal logging writes directly to the
+<code>stderr</code> stream of the NaCl process. It deliberately bypasses the standard
+library functions implemented in nacl_io to avoid circular calls to itself.</p>
 <h2 id="the-nacl-io-demo">The nacl_io demo</h2>
 <h3 id="building-and-running-the-demo">Building and running the demo</h3>
 <p>The demo application launches a Native Client module that mounts three file
 systems and displays a set of controls that let you work with them:</p>
 <img alt="/native-client/images/nacl_io1.png" src="/native-client/images/nacl_io1.png" />
 <p>Follow these steps to build and run the demo:</p>
 <ul class="small-gap">
 <li><p class="first">Open a terminal in the demo directory:</p>
 <pre class="prettyprint">
 $ cd $NACL_SDK_ROOT/examples/demo/nacl_io_demo
@@ skipping 106 matching lines @@
     return 2;
   }
 
   bytes_written = fwrite(data, 1, data_len, file);
 
   *output = PrintfToNewString(&quot;fwrite\1%s\1%d&quot;, file_index_string,
                               bytes_written);
   return 0;
 }
 </pre>
-<h2 id="reference-information">Reference information</h2>
+<h2 id="reference-information">Reference Information</h2>
 <p>The example discussed here is included in the SDK in the directory
 <code>examples/demo/nacl_io_demo</code>.</p>
 <p>The nacl_io library is included in the SDK toolchain and is not a part of the
 Pepper API. For reference information related to the nacl_io interface see
 its header file in the SDK directory, located at
 <code>include/nacl_io/nacl_io.h</code>.</p>
 <p>For more about the HTML5 file system read the <a class="reference external" href="http://dev.w3.org/2009/dap/file-system/pub/FileSystem/">specification</a>.</p>
 </section>
 
 {{/partials.standard_nacl_article}}