From: Monty <xiphmont@xiph.org>
Date: Sat, 13 Jul 2013 20:57:14 +0000 (+0000)
Subject: Patch for trac #1965; clarify in comments and docs that a failed call
X-Git-Tag: v1.3.4~9
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1b0aa969c7bebfad37c5d2dea4055c50c766aa96;p=platform%2Fupstream%2Flibvorbis.git

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
--- 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
--- 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)