Patch for trac #1965; clarify in comments and docs that a failed call

to ov_test does not take ownership of the passed-in file.

svn path=/trunk/vorbis/; revision=18964

diff --git a/doc/vorbisfile/ov_test.html b/doc/vorbisfile/ov_test.html
index 766dadd..cb11d01 100644 (file)
--- a/doc/vorbisfile/ov_test.html
+++ b/doc/vorbisfile/ov_test.html
@@ -19,9 +19,12 @@
 
 <p>
 This partially opens a vorbis file to test for Vorbis-ness.  It loads
-the headers for the first chain and tests for seekability (but does not seek).
-Use <a href="ov_test_open.html">ov_test_open()</a> to finish opening the file
-or <a href="ov_clear.html">ov_clear</a> to close/free it.
+the headers for the first chain and tests for seekability (but does
+not seek).  Use <a href="ov_test_open.html">ov_test_open()</a> to
+finish opening the file or <a href="ov_clear.html">ov_clear</a> to
+close/free it.  Note that vorbisfile does <b>not</b> take ownership of
+the file if the call fails; the calling applicaiton is responsible for
+closing the file if this call returns an error.
 <p>
 
 <p><em><b> WARNING for Windows developers: </b> Do not use ov_test()

diff --git a/lib/vorbisfile.c b/lib/vorbisfile.c
index 071bbcb..efe5cec 100644 (file)
--- a/lib/vorbisfile.c
+++ b/lib/vorbisfile.c
@@ -1055,7 +1055,11 @@ int ov_halfrate_p(OggVorbis_File *vf){
 /* Only partially open the vorbis file; test for Vorbisness, and load
    the headers for the first chain.  Do not seek (although test for
    seekability).  Use ov_test_open to finish opening the file, else
-   ov_clear to close/free it. Same return codes as open. */
+   ov_clear to close/free it. Same return codes as open.
+
+   Note that vorbisfile does _not_ take ownership of the file if the
+   call fails; the calling applicaiton is responsible for closing the file
+   if this call returns an error. */
 
 int ov_test_callbacks(void *f,OggVorbis_File *vf,
     const char *initial,long ibytes,ov_callbacks callbacks)