Doc #70819 [Com]: bzflush(), bzwrite() and bzclose() are aliases

Edit report at https://bugs.php.net/bug.php?id=70819&edit=1 ID: 70819 Comment by: mail at jerrygrey dot me Reported by: mail at jerrygrey dot me Summary: bzflush(), bzwrite() and bzclose() are aliases Status: Verified Type: Documentation Problem Package: Streams related Operating System: Irrelevant PHP Version: Irrelevant Assigned To: cmb Block user comment: N Private report: N New Comment: 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. Previous Comments: ------------------------------------------------------------------------ [2020-12-09 18:07:18] 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. ------------------------------------------------------------------------ [2016-01-01 22:04:56] 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". ------------------------------------------------------------------------ [2015-11-01 16:01:06] 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) ------------------------------------------------------------------------ [2015-11-01 15:28:37] mail at jerrygrey dot me In that case, should this function exist at all? It is just causing confusion. ------------------------------------------------------------------------ [2015-11-01 15:20:20] 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)); ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at https://bugs.php.net/bug.php?id=70819 -- Edit this bug report at https://bugs.php.net/bug.php?id=70819&edit=1