update comments; add lib_zeroinstream

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@1842 42af7a65-404d-4744-a932-0658087f49c3

12 files changed, 214 insertions, 3 deletions

diff --git a/nuttx/lib/Makefile b/nuttx/lib/Makefile
index 32c2e620d..9b023d04e 100644
--- a/nuttx/lib/Makefile
+++ b/nuttx/lib/Makefile
@@ -56,7 +56,8 @@ STDIO_SRCS	= lib_printf.c lib_rawprintf.c lib_lowprintf.c lib_dbg.c \
 		  lib_sprintf.c lib_snprintf.c lib_libsprintf.c lib_vsprintf.c \
 		  lib_vsnprintf.c lib_libvsprintf.c lib_meminstream.c \
 		  lib_memoutstream.c lib_lowinstream.c lib_lowoutstream.c \
-		  lib_nullinstream.c lib_nulloutstream.c lib_sscanf.c
+		  lib_zeroinstream.c lib_nullinstream.c lib_nulloutstream.c \
+		  lib_sscanf.c
 
 ifneq ($(CONFIG_NFILE_DESCRIPTORS),0)
 STDIO_SRCS	+= lib_rawinstream.c lib_rawoutstream.c
diff --git a/nuttx/lib/lib_lowinstream.c b/nuttx/lib/lib_lowinstream.c
index f92fdb5ad..c5016bebe 100644
--- a/nuttx/lib/lib_lowinstream.c
+++ b/nuttx/lib/lib_lowinstream.c
@@ -69,6 +69,17 @@ static int lowinstream_getc(FAR struct lib_outstream_s *this)
 
 /****************************************************************************
  * Name: lib_lowinstream
+ *
+ * Description:
+ *   Initializes a stream for use with low-level, architecture-specific I/O.
+ *
+ * Input parameters:
+ *   lowoutstream - User allocated, uninitialized instance of struct
+ *                  lib_lowoutstream_s to be initialized.
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
  ****************************************************************************/
 
 void lib_lowinstream(FAR struct lib_outstream_s *stream)
diff --git a/nuttx/lib/lib_lowoutstream.c b/nuttx/lib/lib_lowoutstream.c
index dad84ce85..0bbf6450f 100644
--- a/nuttx/lib/lib_lowoutstream.c
+++ b/nuttx/lib/lib_lowoutstream.c
@@ -69,6 +69,17 @@ static void lowoutstream_putc(FAR struct lib_outstream_s *this, int ch)
 
 /****************************************************************************
  * Name: lib_lowoutstream
+ *
+ * Description:
+ *   Initializes a stream for use with low-level, architecture-specific I/O.
+ *
+ * Input parameters:
+ *   lowoutstream - User allocated, uninitialized instance of struct
+ *                  lib_lowoutstream_s to be initialized.
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
  ****************************************************************************/
 
 void lib_lowoutstream(FAR struct lib_outstream_s *stream)
diff --git a/nuttx/lib/lib_meminstream.c b/nuttx/lib/lib_meminstream.c
index 5453d2775..62260c639 100644
--- a/nuttx/lib/lib_meminstream.c
+++ b/nuttx/lib/lib_meminstream.c
@@ -70,6 +70,19 @@ static int meminstream_getc(FAR struct lib_instream_s *this)
 
 /****************************************************************************
  * Name: lib_meminstream
+ *
+ * Description:
+ *   Initializes a stream for use with a fixed-size memory buffer.
+ *
+ * Input parameters:
+ *   meminstream - User allocated, uninitialized instance of struct
+ *                 lib_meminstream_s to be initialized.
+ *   bufstart    - Address of the beginning of the fixed-size memory buffer
+ *   buflen      - Size of the fixed-sized memory buffer in bytes
+ *
+ * Returned Value:
+ *   None (meminstream initialized).
+ *
  ****************************************************************************/
 
 void lib_meminstream(FAR struct lib_meminstream_s *meminstream,
diff --git a/nuttx/lib/lib_memoutstream.c b/nuttx/lib/lib_memoutstream.c
index 7e6412304..0395e22a9 100644
--- a/nuttx/lib/lib_memoutstream.c
+++ b/nuttx/lib/lib_memoutstream.c
@@ -64,6 +64,19 @@ static void memoutstream_putc(FAR struct lib_outstream_s *this, int ch)
 
 /****************************************************************************
  * Name: lib_memoutstream
+ *
+ * Description:
+ *   Initializes a stream for use with a fixed-size memory buffer.
+ *
+ * Input parameters:
+ *   memoutstream - User allocated, uninitialized instance of struct
+ *                  lib_memoutstream_s to be initialized.
+ *   bufstart     - Address of the beginning of the fixed-size memory buffer
+ *   buflen       - Size of the fixed-sized memory buffer in bytes
+ *
+ * Returned Value:
+ *   None (memoutstream initialized).
+ *
  ****************************************************************************/
 
 void lib_memoutstream(FAR struct lib_memoutstream_s *memoutstream,
diff --git a/nuttx/lib/lib_nullinstream.c b/nuttx/lib/lib_nullinstream.c
index dec0a191e..cd24bc1f6 100644
--- a/nuttx/lib/lib_nullinstream.c
+++ b/nuttx/lib/lib_nullinstream.c
@@ -47,14 +47,29 @@
 
 static int nullinstream_getc(FAR struct lib_instream_s *this)
 {
-  this->nget++;
-  return 0;
+  return EOF;
 }
 
 /****************************************************************************
  * Public Functions
  ****************************************************************************/
 
+/****************************************************************************
+ * Name: lib_nullinstream
+ *
+ * Description:
+ *   Initializes a NULL stream. The initialized stream will  will return only
+ *   EOF.
+ *
+ * Input parameters:
+ *   nullinstream  - User allocated, uninitialized instance of struct
+ *                   lib_instream_s to be initialized.
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
+ ****************************************************************************/
+
 void lib_nullinstream(FAR struct lib_instream_s *nullinstream)
 {
   nullinstream->get  = nullinstream_getc;
diff --git a/nuttx/lib/lib_nulloutstream.c b/nuttx/lib/lib_nulloutstream.c
index f2638fbcf..c3dcfe0f6 100644
--- a/nuttx/lib/lib_nulloutstream.c
+++ b/nuttx/lib/lib_nulloutstream.c
@@ -54,6 +54,22 @@ static void nulloutstream_putc(FAR struct lib_outstream_s *this, int ch)
  * Public Functions
  ****************************************************************************/
 
+/****************************************************************************
+ * Name: lib_nulloutstream
+ *
+ * Description:
+ *   Initializes a NULL streams. The initialized stream will write all data
+ *   to the bit-bucket.
+ *
+ * Input parameters:
+ *   nulloutstream - User allocated, uninitialized instance of struct
+ *                   lib_outstream_s to be initialized.
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
+ ****************************************************************************/
+
 void lib_nulloutstream(FAR struct lib_outstream_s *nulloutstream)
 {
   nulloutstream->put  = nulloutstream_putc;
diff --git a/nuttx/lib/lib_rawinstream.c b/nuttx/lib/lib_rawinstream.c
index 39cfa0b1e..de7301a58 100644
--- a/nuttx/lib/lib_rawinstream.c
+++ b/nuttx/lib/lib_rawinstream.c
@@ -78,6 +78,19 @@ static int rawinstream_getc(FAR struct lib_instream_s *this)
 
 /****************************************************************************
  * Name: lib_rawinstream
+ *
+ * Description:
+ *   Initializes a stream for use with a file descriptor.
+ *
+ * Input parameters:
+ *   rawinstream - User allocated, uninitialized instance of struct
+ *                 lib_rawinstream_s to be initialized.
+ *   fd          - User provided file/socket descriptor (must have been opened
+ *                 for the correct access).
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
  ****************************************************************************/
 
 void lib_rawinstream(FAR struct lib_rawinstream_s *rawinstream, int fd)
diff --git a/nuttx/lib/lib_rawoutstream.c b/nuttx/lib/lib_rawoutstream.c
index 1772f3927..4d102446b 100644
--- a/nuttx/lib/lib_rawoutstream.c
+++ b/nuttx/lib/lib_rawoutstream.c
@@ -74,6 +74,19 @@ static void rawoutstream_putc(FAR struct lib_outstream_s *this, int ch)
 
 /****************************************************************************
  * Name: lib_rawoutstream
+ *
+ * Description:
+ *   Initializes a stream for use with a file descriptor.
+ *
+ * Input parameters:
+ *   rawoutstream - User allocated, uninitialized instance of struct
+ *                  lib_rawoutstream_s to be initialized.
+ *   fd           - User provided file/socket descriptor (must have been opened
+ *                  for write access).
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
  ****************************************************************************/
 
 void lib_rawoutstream(FAR struct lib_rawoutstream_s *rawoutstream, int fd)
diff --git a/nuttx/lib/lib_stdinstream.c b/nuttx/lib/lib_stdinstream.c
index 1833f3a7a..182696ead 100644
--- a/nuttx/lib/lib_stdinstream.c
+++ b/nuttx/lib/lib_stdinstream.c
@@ -69,6 +69,19 @@ static int stdinstream_getc(FAR struct lib_instream_s *this)
 
 /****************************************************************************
  * Name: lib_stdinstream
+ *
+ * Description:
+ *   Initializes a stream for use with a FILE instance.
+ *
+ * Input parameters:
+ *   stdinstream - User allocated, uninitialized instance of struct
+ *                 lib_stdinstream_s to be initialized.
+ *   stream      - User provided stream instance (must have been opened for
+ *                 read access).
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
  ****************************************************************************/
 
 void lib_stdinstream(FAR struct lib_stdinstream_s *stdinstream,
diff --git a/nuttx/lib/lib_stdoutstream.c b/nuttx/lib/lib_stdoutstream.c
index 66864d07c..d92236edb 100644
--- a/nuttx/lib/lib_stdoutstream.c
+++ b/nuttx/lib/lib_stdoutstream.c
@@ -65,6 +65,19 @@ static void stdoutstream_putc(FAR struct lib_outstream_s *this, int ch)
 
 /****************************************************************************
  * Name: lib_stdoutstream
+ *
+ * Description:
+ *   Initializes a stream for use with a FILE instance.
+ *
+ * Input parameters:
+ *   stdoutstream - User allocated, uninitialized instance of struct
+ *                  lib_stdoutstream_s to be initialized.
+ *   stream       - User provided stream instance (must have been opened for
+ *                  write access).
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
  ****************************************************************************/
 
 void lib_stdoutstream(FAR struct lib_stdoutstream_s *stdoutstream,
diff --git a/nuttx/lib/lib_zeroinstream.c b/nuttx/lib/lib_zeroinstream.c
new file mode 100644
index 000000000..8cf55f51d
--- /dev/null
+++ b/nuttx/lib/lib_zeroinstream.c
@@ -0,0 +1,79 @@
+/****************************************************************************
+ * lib/lib_zeroinstream.c
+ *
+ *   Copyright (C) 2009 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ * 3. Neither the name NuttX nor the names of its contributors may be
+ *    used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <stdio.h>
+#include <errno.h>
+#include "lib_internal.h"
+
+/****************************************************************************
+ * Private Functions
+ ****************************************************************************/
+
+static int zeroinstream_getc(FAR struct lib_instream_s *this)
+{
+  this->nget++;
+  return 0;
+}
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: lib_zeroinstream
+ *
+ * Description:
+ *   Initializes a NULL stream.  The initialized stream will return an
+ *   infinitely long stream of zeroes.
+ *
+ * Input parameters:
+ *   zeroinstream  - User allocated, uninitialized instance of struct
+ *                   lib_instream_s to be initialized.
+ *
+ * Returned Value:
+ *   None (User allocated instance initialized).
+ *
+ ****************************************************************************/
+
+void lib_zeroinstream(FAR struct lib_instream_s *zeroinstream)
+{
+  zeroinstream->get  = zeroinstream_getc;
+  zeroinstream->nget = 0;
+}
+