From 689abfbb937a9946661c8fd1806c70eba4799e18 Mon Sep 17 00:00:00 2001 From: rocky Date: Sun, 6 Apr 2003 23:40:21 +0000 Subject: [PATCH] Document some of the interfaces. --- lib/_cdio_stdio.c | 43 +++++++++++++++-- lib/_cdio_stream.c | 54 +++++++++++++++++++-- lib/_cdio_stream.h | 118 +++++++++++++++++++++++++++++---------------- 3 files changed, 164 insertions(+), 51 deletions(-) diff --git a/lib/_cdio_stdio.c b/lib/_cdio_stdio.c index 18704de5..94acb49c 100644 --- a/lib/_cdio_stdio.c +++ b/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 Copyright (C) 2003 Rocky Bernstein @@ -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) { diff --git a/lib/_cdio_stream.c b/lib/_cdio_stream.c index 7d62ab92..776ef58f 100644 --- a/lib/_cdio_stream.c +++ b/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 @@ -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); } diff --git a/lib/_cdio_stream.h b/lib/_cdio_stream.h index 8ac7917d..1b33e503 100644 --- a/lib/_cdio_stream.h +++ b/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 Copyright (C) 2003 Rocky Bernstein @@ -29,52 +29,86 @@ extern "C" { #endif /* __cplusplus */ -/* typedef'ed IO functions prototypes */ + /* typedef'ed IO functions prototypes */ + + 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_seek_t)(void *user_data, long offset, int whence); + + typedef long(*cdio_data_stat_t)(void *user_data); + + typedef int(*cdio_data_close_t)(void *user_data); + + typedef void(*cdio_data_free_t)(void *user_data); + + + /* abstract data source */ + + typedef struct _CdioDataSource CdioDataSource; + + 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; + + CdioDataSource* + cdio_stream_new(void *user_data, const cdio_stream_io_functions *funcs); -typedef int(*cdio_data_open_t)(void *user_data); + /*! + Like fread(3) and in fact may be the same. -typedef long(*cdio_data_read_t)(void *user_data, void *buf, long count); + 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. -typedef long(*cdio_data_seek_t)(void *user_data, long offset, int whence); + 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). -typedef long(*cdio_data_stat_t)(void *user_data); - -typedef int(*cdio_data_close_t)(void *user_data); - -typedef void(*cdio_data_free_t)(void *user_data); - - -/* abstract data source */ - -typedef struct _CdioDataSource CdioDataSource; - -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; - -CdioDataSource* -cdio_stream_new(void *user_data, const cdio_stream_io_functions *funcs); - -long -cdio_stream_read(CdioDataSource* obj, void *ptr, long size, long nmemb); - -long -cdio_stream_seek(CdioDataSource* obj, long offset, int whence); - -long -cdio_stream_stat(CdioDataSource* obj); - -void -cdio_stream_destroy(CdioDataSource* obj); - -void -cdio_stream_close(CdioDataSource* obj); + 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); + + /*! + 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 } #endif /* __cplusplus */