php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #70819 bzflush() is a null function
Submitted: 2015-10-30 06:20 UTC Modified: 2020-12-10 12:31 UTC
From: mail at jerrygrey dot me Assigned: cmb (profile)
Status: Closed Package: Streams related
PHP Version: Irrelevant OS: Irrelevant
Private report: No CVE-ID: None
 [2015-10-30 06:20 UTC] mail at jerrygrey dot me
Description:
------------
This looks like an old bug (from 12 years ago) first appearing here: http://php.net/manual/en/function.fflush.php#28887 It has reappeared via https://github.com/php/php-src/pull/1553

The function bzopen should automatically rewind the file pointer as per fopen() documentation for "r" mode: "...place the file pointer at the beginning of the file", but it doesn't. If this is by design, it should be included in the documentation. Since fopen is the base for bzopen, it might have the same issue too.

Test script:
---------------
<?php
$file = __DIR__ . DIRECTORY_SEPARATOR . 'bzflush_test.txt.bz2';
$text = "This is a test string.";

$bz1 = bzopen($file, 'w');
bzwrite($bz1, $text);
var_dump(bzflush($bz1));

$bz2 = bzopen($file, 'r');
var_dump(bzread($bz2));
bzclose($bz2);

bzclose($bz1);
?>

Expected result:
----------------
bool(true)
string(22) "This is a test string."

Actual result:
--------------
bool(true)
string(0) ""

Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2015-11-01 15:20 UTC] reeze@php.net
-Type: Bug +Type: Documentation Problem
 [2015-11-01 15:20 UTC] reeze@php.net
This might be a document problem.  
`bzflush()` is a no-op function,  https://github.com/enthought/bzip2/blob/master/bzlib.c#L1505

You could close it before next reading.


<?php
$file = __DIR__ . DIRECTORY_SEPARATOR . 'bzflush_test.txt.bz2';
$text = "This is a test string.";

$bz1 = bzopen($file, 'w');
bzwrite($bz1, $text);
var_dump(bzflush($bz1));

var_dump(file_get_contents($file));

bzclose($bz1);
var_dump(file_get_contents($file));
 [2015-11-01 15:28 UTC] mail at jerrygrey dot me
In that case, should this function exist at all? It is just causing confusion.
 [2015-11-01 16:01 UTC] reeze@php.net
@jerry  PHP just passthrough to zip library. maybe someday it will be implemented. We could fix the document to reflect that this function actually doing nothing. (we can't remove it for BC)
 [2016-01-01 22:04 UTC] salsi at icosaedro dot it
My thoughs:

- Looking at source code, bzflush() simply calls fflush(). But this does not means all the data sent to the file with bzwrite() have been really written to disk: some are still in memory, where BZIP2 is building the current block of compressed data; some others are in internal buffer of the kernel, waiting to either complete a whole disk block or a file close.

- The original poster encountered a problem because he missed to close the stream with bzclose() and it made instead a fflush(). Then, writing only few bytes of data, this means nothing had really written to disk, and the following read failed returning an empty string.

- If the original poster had checked with bzerrno() or bzstrerr() the actual success of the bzread() operation, the result would be an "UNEXPECTED_EOF", indicating that something went wrong. This to stress how important (an difficult) may be to check errors properly, and how important and urgent may be to switch to exceptions everywhere as soon as possible :-)

- Finally, there is no bug here, and in my opinion this report should be closed as "not a bug".
 [2020-12-09 18:07 UTC] cmb@php.net
-Summary: bzopen/fopen is not rewinded when accessing a file for the second time +Summary: bzflush(), bzwrite() and bzclose() are aliases -Status: Open +Status: Verified -Assigned To: +Assigned To: cmb
 [2020-12-09 18:07 UTC] cmb@php.net
Well, I think we should clearly document that bzflush() is an
alias of fflush(), and that bzwrite() and bzclose() are aliases of
fwrite() and fclose(), respectively.  Otherwise, this is
apparently misleading.
 [2020-12-10 04:26 UTC] mail at jerrygrey dot me
Salsi, as I said above, if this isn't a bug, it should be documented. The PHP documentation for bzflush to this day says nothing more than "Forces a write of all buffered bzip2 data for the file pointer bz."

Speaking for myself, at the time, I was mislead by the documentation. A short sentence or two on the documentation to note this behaviour would have saved me a ton of time and frustration.
 [2020-12-10 12:31 UTC] cmb@php.net
-Summary: bzflush(), bzwrite() and bzclose() are aliases +Summary: bzflush() is a null function
 [2020-12-10 12:31 UTC] cmb@php.net
After having a closer look at this, forget about the alias thing;
while technically correct, that info is not useful for users.
Actually, reeze is right, we're calling BZ2_bzflush() which is
supposed to give better zlib compatibility[1], but completely
fails to do so (if it does nothing, it should not claim success).

[1] <https://www.sourceware.org/bzip2/manual/manual.html#zlib-compat>
 [2020-12-10 12:32 UTC] cmb@php.net
Automatic comment from SVN on behalf of cmb
Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=351993
Log: Fix #70819: bzflush() is a null function
 [2020-12-10 12:34 UTC] phpdocbot@php.net
Automatic comment on behalf of cmb
Revision: http://git.php.net/?p=doc/en.git;a=commit;h=d5fafb8e37413e5d0bd74dec1797de591cb9bad1
Log: Fix #70819: bzflush() is a null function
 [2020-12-10 12:34 UTC] phpdocbot@php.net
-Status: Verified +Status: Closed
 [2020-12-10 22:30 UTC] mumumu@php.net
Automatic comment from SVN on behalf of mumumu
Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=352003
Log: Fix #70819: bzflush() is a null function
 [2020-12-10 22:35 UTC] phpdocbot@php.net
Automatic comment on behalf of mumumu
Revision: http://git.php.net/?p=doc/ja.git;a=commit;h=e3044f0af0a4533749323b450d540b4fd5adbb86
Log: Fix #70819: bzflush() is a null function
 [2020-12-30 11:58 UTC] nikic@php.net
Automatic comment on behalf of mumumu
Revision: http://git.php.net/?p=doc/ja.git;a=commit;h=ee10f458854410b099577c0e3a824b19e0f62f74
Log: Fix #70819: bzflush() is a null function
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Tue Mar 19 03:01:29 2024 UTC