From 9e24b5594f6afe741bd692ba7fa945c0362ab420 Mon Sep 17 00:00:00 2001
From: rocky <rocky>
Date: Sun, 25 Feb 2007 15:58:31 +0000
Subject: [PATCH] Update cdio_read documentation.

---
 include/cdio/read.h |  9 +++++----
 lib/driver/read.c   | 17 ++++++++++++-----
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/include/cdio/read.h b/include/cdio/read.h
index 09f00d1b..0fd56d07 100644
--- a/include/cdio/read.h
+++ b/include/cdio/read.h
@@ -1,5 +1,5 @@
 /* -*- c -*-
-    $Id: read.h,v 1.11 2006/01/23 20:47:33 rocky Exp $
+    $Id: read.h,v 1.12 2007/02/25 15:58:31 rocky Exp $
 
     Copyright (C) 2005, 2006 Rocky Bernstein <rocky@panix.com>
 
@@ -59,9 +59,10 @@ extern "C" {
 
   off_t cdio_lseek(const CdIo_t *p_cdio, off_t offset, int whence);
     
-  /*!
-    Reads into buf the next size bytes.
-    Similar to (if not the same as) libc's read()
+  /*!  Reads into buf the next size bytes.  Similar to (if not the
+    same as) libc's read(). This is a "cooked" read, or one handled by
+    the OS. It probably won't work on audio data. For that use
+    cdio_read_audio_sector(s).
 
     @param p_cdio object to read from
     @param p_buf place to read data into. The caller should make sure
diff --git a/lib/driver/read.c b/lib/driver/read.c
index 6c583cee..4aaedbc6 100644
--- a/lib/driver/read.c
+++ b/lib/driver/read.c
@@ -1,5 +1,5 @@
 /*
-    $Id: read.c,v 1.10 2005/11/10 00:44:41 rocky Exp $
+    $Id: read.c,v 1.11 2007/02/25 15:58:31 rocky Exp $
 
     Copyright (C) 2005 Rocky Bernstein <rocky@panix.com>
 
@@ -87,10 +87,17 @@ cdio_lseek (const CdIo_t *p_cdio, off_t offset, int whence)
   return DRIVER_OP_UNSUPPORTED;
 }
 
-/*!
-  Reads into buf the next size bytes.
-  Returns -1 on error. 
-  Similar to (if not the same as) libc's read()
+/*!  Reads into buf the next size bytes.  Similar to (if not the
+  same as) libc's read(). This is a "cooked" read, or one handled by
+  the OS. It probably won't work on audio data. For that use
+  cdio_read_audio_sector(s).
+
+  @param p_cdio object to read from
+  @param p_buf place to read data into. The caller should make sure
+               this location can store at least i_size bytes.
+  @param i_size number of bytes to read
+
+  @return (ssize_t) -1 on error. 
 */
 ssize_t
 cdio_read (const CdIo_t *p_cdio, void *p_buf, size_t i_size)