Add debugging information for nacl_io library.

native_client_sdk/src/doc/devguide/coding/nacl_io.rst

 .. _nacl_io:
 
 ###################
 The nacl_io Library
 ###################
 
 .. contents::
   :local:
   :backlinks: none
   :depth: 2
 
 Introduction
 ============
 
 ``nacl_io`` is a utility library that provides implementations of standard
 C APIs such as POSIX I/O (``stdio.h``) and BSD sockets (``sys/socket.h``).
 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.
 
 Since Native Client modules cannot access the host machine'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
-`HTML5 File System API
-<http://www.html5rocks.com/en/tutorials/file/filesystem/>`_ 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 :doc:`File IO API <file-io>`. With nacl_io
-a Native Client application can mount an HTML5 filesystem and access it via
-standard POSIX I/O function such as ``fopen``, ``fseek``, ``fread``,
-``fwrite``, and ``fclose``, or their low level UNIX counterparts ``open``,
-``lseek``, ``read``, ``write`` and ``close``.
+directly, nacl_io provides several alternative filesystem types which can be
+used by the application. For example, the Chrome browser supports the `HTML5
+File System API <http://www.html5rocks.com/en/tutorials/file/filesystem/>`_
+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 :doc:`File IO API <file-io>`.
+
+With nacl_io a Native Client application can mount an HTML5 filesystem and
+access it via standard POSIX I/O function such as ``fopen``, ``fseek``,
+``fread``, ``fwrite``, and ``fclose``, or their low level UNIX counterparts
+``open``, ``lseek``, ``read``, ``write`` and ``close``. Unlike most input/output
+for nacl_io, logging writes directly to the ``stderr`` stream of the NaCl

[Sam Clegg, 2014/10/01 21:52:14]

, internal logging and error reporting writes directly...

[jpmedley, 2014/10/07 17:01:42]

Done.

+process. It deliberately bypasses the standard library functions implemented in
+nacl_io to avoid circular calls to itself.

[Sam Clegg, 2014/10/01 21:52:14]

Perhaps put this in sub-sub-section called "Logging and Error Reporting" (or
maybe just in its own paragraph at the end).

The flow from this paragraph to the next is (IMHO) otherwise a little
interrupted.

[jpmedley, 2014/10/07 17:01:42]

Done.

 
 As well as the HTML5 file system, nacl_io provides several other file system
 types which are described in the table below:
 
 =========== ==================================================================
 File System Description
 =========== ==================================================================
 memfs       An in-memory file system
 html5fs     An HTML5 local file system, which can be persistent or temporary
 http        Maps files on a remote webserver into the local filesystem.
@@ skipping 162 matching lines @@
       return 2;
     }
 
     bytes_written = fwrite(data, 1, data_len, file);
 
     *output = PrintfToNewString("fwrite\1%s\1%d", file_index_string,
                                 bytes_written);
     return 0;
   }
 
-Reference information
+Reference Information
 =====================
 
 The example discussed here is included in the SDK in the directory
 ``examples/demo/nacl_io_demo``.
 
 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
 ``include/nacl_io/nacl_io.h``.
 
 For more about the HTML5 file system read the `specification
 <http://dev.w3.org/2009/dap/file-system/pub/FileSystem/>`_.