Document some of the interfaces.

lib/_cdio_stdio.c

@@ -1,5 +1,5 @@
 /*
-    $Id: _cdio_stdio.c,v 1.2 2003/03/29 17:32:00 rocky Exp $
+    $Id: _cdio_stdio.c,v 1.3 2003/04/06 23:40:21 rocky Exp $
 
     Copyright (C) 2000 Herbert Valerio Riedel <hvr@gnu.org>
     Copyright (C) 2003 Rocky Bernstein <rocky@panix.com>
@@ -35,7 +35,7 @@
 #include "_cdio_stream.h"
 #include "_cdio_stdio.h"
 
-static const char _rcsid[] = "$Id: _cdio_stdio.c,v 1.2 2003/03/29 17:32:00 rocky Exp $";
+static const char _rcsid[] = "$Id: _cdio_stdio.c,v 1.3 2003/04/06 23:40:21 rocky Exp $";
 
 #define CDIO_STDIO_BUFSIZE (128*1024)
 
@@ -90,18 +90,36 @@ _stdio_free(void *user_data)
   free(ud);
 }
 
+/*! 
+  Like fseek(3) and in fact may be the same.
+  
+  This  function sets the file position indicator for the stream
+  pointed to by stream.  The new position, measured in bytes, is obtained
+  by  adding offset bytes to the position specified by whence.  If whence
+  is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset  is  relative  to
+  the  start of the file, the current position indicator, or end-of-file,
+  respectively.  A successful call to the fseek function clears the end-
+  of-file indicator for the stream and undoes any effects of the
+  ungetc(3) function on the same stream.
+  
+  RETURN VALUE
+  Upon successful completion, return 0,
+  Otherwise, -1 is returned and the global variable errno is set to indi-
+  cate the error.
+*/
 static long
 _stdio_seek(void *user_data, long offset, int whence)
 {
   _UserData *const ud = user_data;
 
-  if (fseek (ud->fd, offset, whence))
+  if ( (offset=fseek (ud->fd, offset, whence)) ) {
     cdio_error ("fseek (): %s", strerror (errno));
+  }
 
   return offset;
 }
 
-static long
+static long int
 _stdio_stat(void *user_data)
 {
   const _UserData *const ud = user_data;
@@ -109,6 +127,23 @@ _stdio_stat(void *user_data)
   return ud->st_size;
 }
 
+/*!
+  Like fread(3) and in fact is about the same.
+  
+  DESCRIPTION:
+  The function fread reads nmemb elements of data, each size bytes long,
+  from the stream pointed to by stream, storing them at the location
+  given by ptr.
+  
+  RETURN VALUE:
+  return the number of items successfully read or written (i.e.,
+  not the number of characters).  If an error occurs, or the
+  end-of-file is reached, the return value is a short item count
+  (or zero).
+  
+  We do not distinguish between end-of-file and error, and callers
+  must use feof(3) and ferror(3) to determine which occurred.
+  */
 static long
 _stdio_read(void *user_data, void *buf, long count)
 {

lib/_cdio_stream.c

@@ -1,5 +1,5 @@
 /*
-    $Id: _cdio_stream.c,v 1.3 2003/04/06 17:57:20 rocky Exp $
+    $Id: _cdio_stream.c,v 1.4 2003/04/06 23:40:21 rocky Exp $
 
     Copyright (C) 2000 Herbert Valerio Riedel <hvr@gnu.org>
 
@@ -34,7 +34,7 @@
 #include "util.h"
 #include "_cdio_stream.h"
 
-static const char _rcsid[] = "$Id: _cdio_stream.c,v 1.3 2003/04/06 17:57:20 rocky Exp $";
+static const char _rcsid[] = "$Id: _cdio_stream.c,v 1.4 2003/04/06 23:40:21 rocky Exp $";
 
 /* 
  * DataSource implementations
@@ -47,6 +47,10 @@ struct _CdioDataSource {
   long position;
 };
 
+/* 
+   Open if not already open. 
+   Return false if we hit an error. Errno should be set for that error.
+*/
 static bool
 _cdio_stream_open_if_necessary(CdioDataSource *obj)
 {
@@ -65,12 +69,31 @@ _cdio_stream_open_if_necessary(CdioDataSource *obj)
   return true;
 }
 
+/*! 
+  Like 3 fseek and in fact may be the same.
+  
+  This  function sets the file position indicator for the stream
+  pointed to by stream.  The new position, measured in bytes, is obtained
+  by  adding offset bytes to the position specified by whence.  If whence
+  is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset  is  relative  to
+  the  start of the file, the current position indicator, or end-of-file,
+  respectively.  A successful call to the fseek function clears the end-
+  of-file indicator for the stream and undoes any effects of the
+  ungetc(3) function on the same stream.
+  
+  RETURN VALUE
+  Upon successful completion, return 0,
+  Otherwise, -1 is returned and the global variable errno is set to indi-
+  cate the error.
+*/
 long
 cdio_stream_seek(CdioDataSource* obj, long offset, int whence)
 {
   cdio_assert (obj != NULL);
 
-  if (!_cdio_stream_open_if_necessary(obj)) return 0;
+  if (!_cdio_stream_open_if_necessary(obj)) 
+    /* errno is set by _cdio_stream_open_if necessary. */
+    return -1;
 
   if (obj->position != offset) {
 #ifdef STREAM_DEBUG
@@ -96,6 +119,23 @@ cdio_stream_new(void *user_data, const cdio_stream_io_functions *funcs)
   return new_obj;
 }
 
+/*!
+  Like fread(3) and in fact may be the same.
+  
+  DESCRIPTION:
+  The function fread reads nmemb elements of data, each size bytes long,
+  from the stream pointed to by stream, storing them at the location
+  given by ptr.
+  
+  RETURN VALUE:
+  return the number of items successfully read or written (i.e.,
+  not the number of characters).  If an error occurs, or the
+  end-of-file is reached, the return value is a short item count
+  (or zero).
+  
+  We do not distinguish between end-of-file and error, and callers
+  must use feof(3) and ferror(3) to determine which occurred.
+*/
 long
 cdio_stream_read(CdioDataSource* obj, void *ptr, long size, long nmemb)
 {
@@ -111,12 +151,16 @@ cdio_stream_read(CdioDataSource* obj, void *ptr, long size, long nmemb)
   return read_bytes;
 }
 
-long
+/*!
+  Return whatever size of stream reports, I guess unit size is bytes. 
+  On error return -1;
+ */
+long int
 cdio_stream_stat(CdioDataSource* obj)
 {
   cdio_assert (obj != NULL);
 
-  if (!_cdio_stream_open_if_necessary(obj)) return 0;
+  if (!_cdio_stream_open_if_necessary(obj)) return -1;
 
   return obj->op.stat(obj->user_data);
 }

lib/_cdio_stream.h

@@ -1,5 +1,5 @@
 /*
-    $Id: _cdio_stream.h,v 1.3 2003/04/03 12:16:27 rocky Exp $
+    $Id: _cdio_stream.h,v 1.4 2003/04/06 23:40:21 rocky Exp $
 
     Copyright (C) 2000 Herbert Valerio Riedel <hvr@gnu.org>
     Copyright (C) 2003 Rocky Bernstein <rocky@panix.com>
@@ -29,51 +29,85 @@
 extern "C" {
 #endif /* __cplusplus */
 
-/* typedef'ed IO functions prototypes */
+  /* typedef'ed IO functions prototypes */
   
-typedef int(*cdio_data_open_t)(void *user_data);
+  typedef int(*cdio_data_open_t)(void *user_data);
   
-typedef long(*cdio_data_read_t)(void *user_data, void *buf, long count);
+  typedef long(*cdio_data_read_t)(void *user_data, void *buf, long count);
   
-typedef long(*cdio_data_seek_t)(void *user_data, long offset, int whence);
+  typedef long(*cdio_data_seek_t)(void *user_data, long offset, int whence);
   
-typedef long(*cdio_data_stat_t)(void *user_data);
+  typedef long(*cdio_data_stat_t)(void *user_data);
   
-typedef int(*cdio_data_close_t)(void *user_data);
+  typedef int(*cdio_data_close_t)(void *user_data);
   
-typedef void(*cdio_data_free_t)(void *user_data);
+  typedef void(*cdio_data_free_t)(void *user_data);
   
   
-/* abstract data source */
+  /* abstract data source */
   
-typedef struct _CdioDataSource CdioDataSource;
+  typedef struct _CdioDataSource CdioDataSource;
   
-typedef struct {
+  typedef struct {
     cdio_data_open_t open;
     cdio_data_seek_t seek; 
     cdio_data_stat_t stat; 
     cdio_data_read_t read;
     cdio_data_close_t close;
     cdio_data_free_t free;
-} cdio_stream_io_functions;
+  } cdio_stream_io_functions;
   
-CdioDataSource*
+  CdioDataSource*
-cdio_stream_new(void *user_data, const cdio_stream_io_functions *funcs);
+  cdio_stream_new(void *user_data, const cdio_stream_io_functions *funcs);
 
-long
+  /*!
-cdio_stream_read(CdioDataSource* obj, void *ptr, long size, long nmemb);
+     Like fread(3) and in fact may be the same.
 
-long
+     DESCRIPTION:
-cdio_stream_seek(CdioDataSource* obj, long offset, int whence);
+     The function fread reads nmemb elements of data, each size bytes long,
+     from the stream pointed to by stream, storing them at the location
+     given by ptr.
 
-long
+     RETURN VALUE:
-cdio_stream_stat(CdioDataSource* obj);
+     return the number of items successfully read or written (i.e.,
+     not the number of characters).  If an error occurs, or the
+     end-of-file is reached, the return value is a short item count
+     (or zero).
 
-void
+     We do not distinguish between end-of-file and error, and callers
-cdio_stream_destroy(CdioDataSource* obj);
+     must use feof(3) and ferror(3) to determine which occurred.
+  */
+  long
+  cdio_stream_read(CdioDataSource* obj, void *ptr, long size, long nmemb);
   
-void
+  /*! 
-cdio_stream_close(CdioDataSource* obj);
+    Like fseek(3) and in fact may be the same.
+
+    This  function sets the file position indicator for the stream
+    pointed to by stream.  The new position, measured in bytes, is obtained
+    by  adding offset bytes to the position specified by whence.  If whence
+    is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset  is  relative  to
+    the  start of the file, the current position indicator, or end-of-file,
+    respectively.  A successful call to the fseek function clears the end-
+    of-file indicator for the stream and undoes any effects of the
+    ungetc(3) function on the same stream.
+    
+    RETURN VALUE
+    Upon successful completion, return 0,
+    Otherwise, -1 is returned and the global variable errno is set to indi-
+    cate the error.
+   */
+  long cdio_stream_seek(CdioDataSource* obj, long offset, int whence);
+  
+  /*!
+    Return whatever size of stream reports, I guess unit size is bytes. 
+    On error return -1;
+  */
+  long cdio_stream_stat(CdioDataSource* obj);
+  
+  void cdio_stream_destroy(CdioDataSource* obj);
+  
+  void cdio_stream_close(CdioDataSource* obj);
   
 #ifdef __cplusplus
 }