{
    "content": [
        {
            "type": "text",
            "text": "# IO::Compress::Bzip2 (info)\n\n## NAME\n\nIO::Compress::Bzip2 - Write bzip2 files/buffers\n\n## SYNOPSIS\n\nuse IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\nmy $status = bzip2 $input => $output [,OPTS]\nor die \"bzip2 failed: $Bzip2Error\\n\";\nmy $z = IO::Compress::Bzip2->new( $output [,OPTS] )\nor die \"bzip2 failed: $Bzip2Error\\n\";\n$z->print($string);\n$z->printf($format, $string);\n$z->write($string);\n$z->syswrite($string [, $length, $offset]);\n$z->flush();\n$z->tell();\n$z->eof();\n$z->seek($position, $whence);\n$z->binmode();\n$z->fileno();\n$z->opened();\n$z->autoflush();\n$z->inputlinenumber();\n$z->newStream( [OPTS] );\n$z->close() ;\n$Bzip2Error ;\n# IO::File mode\nprint $z $string;\nprintf $z $format, $string;\ntell $z\neof $z\nseek $z, $position, $whence\nbinmode $z\nfileno $z\nclose $z ;\n\n## DESCRIPTION\n\nThis module provides a Perl interface that allows writing bzip2\ncompressed data to files or buffer.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **Functional Interface**\n- **Methods**\n- **Importing**\n- **EXAMPLES**\n- **SUPPORT**\n- **SEE ALSO**\n- **AUTHOR**\n- **MODIFICATION HISTORY**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "IO::Compress::Bzip2",
        "section": "",
        "mode": "info",
        "summary": "IO::Compress::Bzip2 - Write bzip2 files/buffers",
        "synopsis": "use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\nmy $status = bzip2 $input => $output [,OPTS]\nor die \"bzip2 failed: $Bzip2Error\\n\";\nmy $z = IO::Compress::Bzip2->new( $output [,OPTS] )\nor die \"bzip2 failed: $Bzip2Error\\n\";\n$z->print($string);\n$z->printf($format, $string);\n$z->write($string);\n$z->syswrite($string [, $length, $offset]);\n$z->flush();\n$z->tell();\n$z->eof();\n$z->seek($position, $whence);\n$z->binmode();\n$z->fileno();\n$z->opened();\n$z->autoflush();\n$z->inputlinenumber();\n$z->newStream( [OPTS] );\n$z->close() ;\n$Bzip2Error ;\n# IO::File mode\nprint $z $string;\nprintf $z $format, $string;\ntell $z\neof $z\nseek $z, $position, $whence\nbinmode $z\nfileno $z\nclose $z ;",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [
            "Apache::GZip Revisited",
            "See IO::Compress::FAQ",
            "Working with Net::FTP",
            "See IO::Compress::FAQ"
        ],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 38,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "Functional Interface",
                "lines": 335,
                "subsections": []
            },
            {
                "name": "Methods",
                "lines": 169,
                "subsections": []
            },
            {
                "name": "Importing",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "EXAMPLES",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "SUPPORT",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 19,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "MODIFICATION HISTORY",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENSE",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "IO::Compress::Bzip2 - Write bzip2 files/buffers\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\n\nmy $status = bzip2 $input => $output [,OPTS]\nor die \"bzip2 failed: $Bzip2Error\\n\";\n\nmy $z = IO::Compress::Bzip2->new( $output [,OPTS] )\nor die \"bzip2 failed: $Bzip2Error\\n\";\n\n$z->print($string);\n$z->printf($format, $string);\n$z->write($string);\n$z->syswrite($string [, $length, $offset]);\n$z->flush();\n$z->tell();\n$z->eof();\n$z->seek($position, $whence);\n$z->binmode();\n$z->fileno();\n$z->opened();\n$z->autoflush();\n$z->inputlinenumber();\n$z->newStream( [OPTS] );\n\n$z->close() ;\n\n$Bzip2Error ;\n\n# IO::File mode\n\nprint $z $string;\nprintf $z $format, $string;\ntell $z\neof $z\nseek $z, $position, $whence\nbinmode $z\nfileno $z\nclose $z ;\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module provides a Perl interface that allows writing bzip2\ncompressed data to files or buffer.\n\nFor reading bzip2 files/buffers, see the companion module\nIO::Uncompress::Bunzip2.\n",
                "subsections": []
            },
            "Functional Interface": {
                "content": "A top-level function, \"bzip2\", is provided to carry out \"one-shot\"\ncompression between buffers and/or files. For finer control over the\ncompression process, see the \"OO Interface\" section.\n\nuse IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\n\nbzip2 $inputfilenameorreference => $outputfilenameorreference [,OPTS]\nor die \"bzip2 failed: $Bzip2Error\\n\";\n\nThe functional interface needs Perl5.005 or better.\n\nbzip2 $inputfilenameorreference => $outputfilenameorreference [,\nOPTS]\n\"bzip2\" expects at least two parameters, $inputfilenameorreference\nand $outputfilenameorreference and zero or more optional parameters\n(see \"Optional Parameters\")\n\nThe $inputfilenameorreference parameter\n\nThe parameter, $inputfilenameorreference, is used to define the\nsource of the uncompressed data.\n\nIt can take one of the following forms:\n\nA filename\nIf the $inputfilenameorreference parameter is a simple scalar,\nit is assumed to be a filename. This file will be opened for\nreading and the input data will be read from it.\n\nA filehandle\nIf the $inputfilenameorreference parameter is a filehandle, the\ninput data will be read from it.  The string '-' can be used as an\nalias for standard input.\n\nA scalar reference\nIf $inputfilenameorreference is a scalar reference, the input\ndata will be read from $$inputfilenameorreference.\n\nAn array reference\nIf $inputfilenameorreference is an array reference, each\nelement in the array must be a filename.\n\nThe input data will be read from each file in turn.\n\nThe complete array will be walked to ensure that it only contains\nvalid filenames before any data is compressed.\n\nAn Input FileGlob string\nIf $inputfilenameorreference is a string that is delimited by\nthe characters \"<\" and \">\" \"bzip2\" will assume that it is an input\nfileglob string. The input is the list of files that match the\nfileglob.\n\nSee File::GlobMapper for more details.\n\nIf the $inputfilenameorreference parameter is any other type,\n\"undef\" will be returned.\n\nThe $outputfilenameorreference parameter\n\nThe parameter $outputfilenameorreference is used to control the\ndestination of the compressed data. This parameter can take one of\nthese forms.\n\nA filename\nIf the $outputfilenameorreference parameter is a simple scalar,\nit is assumed to be a filename.  This file will be opened for\nwriting and the compressed data will be written to it.\n\nA filehandle\nIf the $outputfilenameorreference parameter is a filehandle,\nthe compressed data will be written to it.  The string '-' can be\nused as an alias for standard output.\n\nA scalar reference\nIf $outputfilenameorreference is a scalar reference, the\ncompressed data will be stored in $$outputfilenameorreference.\n\nAn Array Reference\nIf $outputfilenameorreference is an array reference, the\ncompressed data will be pushed onto the array.\n\nAn Output FileGlob\nIf $outputfilenameorreference is a string that is delimited by\nthe characters \"<\" and \">\" \"bzip2\" will assume that it is an\noutput fileglob string. The output is the list of files that match\nthe fileglob.\n\nWhen $outputfilenameorreference is an fileglob string,\n$inputfilenameorreference must also be a fileglob string.\nAnything else is an error.\n\nSee File::GlobMapper for more details.\n\nIf the $outputfilenameorreference parameter is any other type,\n\"undef\" will be returned.\n\nNotes\nWhen $inputfilenameorreference maps to multiple files/buffers and\n$outputfilenameorreference is a single file/buffer the input\nfiles/buffers will be stored in $outputfilenameorreference as a\nconcatenated series of compressed data streams.\n\nOptional Parameters\nThe optional parameters for the one-shot function \"bzip2\" are (for the\nmost part) identical to those used with the OO interface defined in the\n\"Constructor Options\" section. The exceptions are listed below\n\n\"AutoClose => 0|1\"\nThis option applies to any input or output data streams to \"bzip2\"\nthat are filehandles.\n\nIf \"AutoClose\" is specified, and the value is true, it will result\nin all input and/or output filehandles being closed once \"bzip2\"\nhas completed.\n\nThis parameter defaults to 0.\n\n\"BinModeIn => 0|1\"\nThis option is now a no-op. All files will be read in binmode.\n\n\"Append => 0|1\"\nThe behaviour of this option is dependent on the type of output\ndata stream.\n\no    A Buffer\n\nIf \"Append\" is enabled, all compressed data will be append to\nthe end of the output buffer. Otherwise the output buffer\nwill be cleared before any compressed data is written to it.\n\no    A Filename\n\nIf \"Append\" is enabled, the file will be opened in append\nmode. Otherwise the contents of the file, if any, will be\ntruncated before any compressed data is written to it.\n\no    A Filehandle\n\nIf \"Append\" is enabled, the filehandle will be positioned to\nthe end of the file via a call to \"seek\" before any\ncompressed data is written to it.  Otherwise the file pointer\nwill not be moved.\n\nWhen \"Append\" is specified, and set to true, it will append all\ncompressed data to the output data stream.\n\nSo when the output is a filehandle it will carry out a seek to the\neof before writing any compressed data. If the output is a\nfilename, it will be opened for appending. If the output is a\nbuffer, all compressed data will be appended to the existing\nbuffer.\n\nConversely when \"Append\" is not specified, or it is present and is\nset to false, it will operate as follows.\n\nWhen the output is a filename, it will truncate the contents of\nthe file before writing any compressed data. If the output is a\nfilehandle its position will not be changed. If the output is a\nbuffer, it will be wiped before any compressed data is output.\n\nDefaults to 0.\n\nExamples\nHere are a few example that show the capabilities of the module.\n\nStreaming\n\nThis very simple command line example demonstrates the streaming\ncapabilities of the module.  The code reads data from STDIN, compresses\nit, and writes the compressed data to STDOUT.\n\n$ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 \\*STDIN => \\*STDOUT' >output.bz2\n\nThe special filename \"-\" can be used as a standin for both \"\\*STDIN\"\nand \"\\*STDOUT\", so the above can be rewritten as\n\n$ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 \"-\" => \"-\"' >output.bz2\n\nCompressing a file from the filesystem\n\nTo read the contents of the file \"file1.txt\" and write the compressed\ndata to the file \"file1.txt.bz2\".\n\nuse strict ;\nuse warnings ;\nuse IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\n\nmy $input = \"file1.txt\";\nbzip2 $input => \"$input.bz2\"\nor die \"bzip2 failed: $Bzip2Error\\n\";\n\nReading from a Filehandle and writing to an in-memory buffer\n\nTo read from an existing Perl filehandle, $input, and write the\ncompressed data to a buffer, $buffer.\n\nuse strict ;\nuse warnings ;\nuse IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\nuse IO::File ;\n\nmy $input = IO::File->new( \"<file1.txt\" )\nor die \"Cannot open 'file1.txt': $!\\n\" ;\nmy $buffer ;\nbzip2 $input => \\$buffer\nor die \"bzip2 failed: $Bzip2Error\\n\";\n\nCompressing multiple files\n\nTo compress all files in the directory \"/my/home\" that match \"*.txt\"\nand store the compressed data in the same directory\n\nuse strict ;\nuse warnings ;\nuse IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\n\nbzip2 '</my/home/*.txt>' => '<*.bz2>'\nor die \"bzip2 failed: $Bzip2Error\\n\";\n\nand if you want to compress each file one at a time, this will do the\ntrick\n\nuse strict ;\nuse warnings ;\nuse IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\n\nfor my $input ( glob \"/my/home/*.txt\" )\n{\nmy $output = \"$input.bz2\" ;\nbzip2 $input => $output\nor die \"Error compressing '$input': $Bzip2Error\\n\";\n}\n\nOO Interface\nConstructor\nThe format of the constructor for \"IO::Compress::Bzip2\" is shown below\n\nmy $z = IO::Compress::Bzip2->new( $output [,OPTS] )\nor die \"IO::Compress::Bzip2 failed: $Bzip2Error\\n\";\n\nIt returns an \"IO::Compress::Bzip2\" object on success and undef on\nfailure.  The variable $Bzip2Error will contain an error message on\nfailure.\n\nIf you are running Perl 5.005 or better the object, $z, returned from\nIO::Compress::Bzip2 can be used exactly like an IO::File filehandle.\nThis means that all normal output file operations can be carried out\nwith $z.  For example, to write to a compressed file/buffer you can use\neither of these forms\n\n$z->print(\"hello world\\n\");\nprint $z \"hello world\\n\";\n\nThe mandatory parameter $output is used to control the destination of\nthe compressed data. This parameter can take one of these forms.\n\nA filename\nIf the $output parameter is a simple scalar, it is assumed to be a\nfilename. This file will be opened for writing and the compressed\ndata will be written to it.\n\nA filehandle\nIf the $output parameter is a filehandle, the compressed data will\nbe written to it.  The string '-' can be used as an alias for\nstandard output.\n\nA scalar reference\nIf $output is a scalar reference, the compressed data will be\nstored in $$output.\n\nIf the $output parameter is any other type, \"IO::Compress::Bzip2\"::new\nwill return undef.\n\nConstructor Options\n\"OPTS\" is any combination of zero or more the following options:\n\n\"AutoClose => 0|1\"\nThis option is only valid when the $output parameter is a\nfilehandle. If specified, and the value is true, it will result in\nthe $output being closed once either the \"close\" method is called\nor the \"IO::Compress::Bzip2\" object is destroyed.\n\nThis parameter defaults to 0.\n\n\"Append => 0|1\"\nOpens $output in append mode.\n\nThe behaviour of this option is dependent on the type of $output.\n\no    A Buffer\n\nIf $output is a buffer and \"Append\" is enabled, all\ncompressed data will be append to the end of $output.\nOtherwise $output will be cleared before any data is written\nto it.\n\no    A Filename\n\nIf $output is a filename and \"Append\" is enabled, the file\nwill be opened in append mode. Otherwise the contents of the\nfile, if any, will be truncated before any compressed data is\nwritten to it.\n\no    A Filehandle\n\nIf $output is a filehandle, the file pointer will be\npositioned to the end of the file via a call to \"seek\" before\nany compressed data is written to it.  Otherwise the file\npointer will not be moved.\n\nThis parameter defaults to 0.\n\n\"BlockSize100K => number\"\nSpecify the number of 100K blocks bzip2 uses during compression.\n\nValid values are from 1 to 9, where 9 is best compression.\n\nThe default is 1.\n\n\"WorkFactor => number\"\nSpecifies how much effort bzip2 should take before resorting to a\nslower fallback compression algorithm.\n\nValid values range from 0 to 250, where 0 means use the default\nvalue 30.\n\nThe default is 0.\n\n\"Strict => 0|1\"\nThis is a placeholder option.\n\nExamples\nTODO\n",
                "subsections": []
            },
            "Methods": {
                "content": "print\nUsage is\n\n$z->print($data)\nprint $z $data\n\nCompresses and outputs the contents of the $data parameter. This has\nthe same behaviour as the \"print\" built-in.\n\nReturns true if successful.\n\nprintf\nUsage is\n\n$z->printf($format, $data)\nprintf $z $format, $data\n\nCompresses and outputs the contents of the $data parameter.\n\nReturns true if successful.\n\nsyswrite\nUsage is\n\n$z->syswrite $data\n$z->syswrite $data, $length\n$z->syswrite $data, $length, $offset\n\nCompresses and outputs the contents of the $data parameter.\n\nReturns the number of uncompressed bytes written, or \"undef\" if\nunsuccessful.\n\nwrite\nUsage is\n\n$z->write $data\n$z->write $data, $length\n$z->write $data, $length, $offset\n\nCompresses and outputs the contents of the $data parameter.\n\nReturns the number of uncompressed bytes written, or \"undef\" if\nunsuccessful.\n\nflush\nUsage is\n\n$z->flush;\n\nFlushes any pending compressed data to the output file/buffer.\n\nTODO\n\nReturns true on success.\n\ntell\nUsage is\n\n$z->tell()\ntell $z\n\nReturns the uncompressed file offset.\n\neof\nUsage is\n\n$z->eof();\neof($z);\n\nReturns true if the \"close\" method has been called.\n\nseek\n$z->seek($position, $whence);\nseek($z, $position, $whence);\n\nProvides a sub-set of the \"seek\" functionality, with the restriction\nthat it is only legal to seek forward in the output file/buffer.  It is\na fatal error to attempt to seek backward.\n\nEmpty parts of the file/buffer will have NULL (0x00) bytes written to\nthem.\n\nThe $whence parameter takes one the usual values, namely SEEKSET,\nSEEKCUR or SEEKEND.\n\nReturns 1 on success, 0 on failure.\n\nbinmode\nUsage is\n\n$z->binmode\nbinmode $z ;\n\nThis is a noop provided for completeness.\n\nopened\n$z->opened()\n\nReturns true if the object currently refers to a opened file/buffer.\n\nautoflush\nmy $prev = $z->autoflush()\nmy $prev = $z->autoflush(EXPR)\n\nIf the $z object is associated with a file or a filehandle, this method\nreturns the current autoflush setting for the underlying filehandle. If\n\"EXPR\" is present, and is non-zero, it will enable flushing after every\nwrite/print operation.\n\nIf $z is associated with a buffer, this method has no effect and always\nreturns \"undef\".\n\nNote that the special variable $| cannot be used to set or retrieve the\nautoflush setting.\n\ninputlinenumber\n$z->inputlinenumber()\n$z->inputlinenumber(EXPR)\n\nThis method always returns \"undef\" when compressing.\n\nfileno\n$z->fileno()\nfileno($z)\n\nIf the $z object is associated with a file or a filehandle, \"fileno\"\nwill return the underlying file descriptor. Once the \"close\" method is\ncalled \"fileno\" will return \"undef\".\n\nIf the $z object is associated with a buffer, this method will return\n\"undef\".\n\nclose\n$z->close() ;\nclose $z ;\n\nFlushes any pending compressed data and then closes the output\nfile/buffer.\n\nFor most versions of Perl this method will be automatically invoked if\nthe IO::Compress::Bzip2 object is destroyed (either explicitly or by\nthe variable with the reference to the object going out of scope). The\nexceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these\ncases, the \"close\" method will be called automatically, but not until\nglobal destruction of all live objects when the program is terminating.\n\nTherefore, if you want your scripts to be able to run on all versions\nof Perl, you should call \"close\" explicitly and not rely on automatic\nclosing.\n\nReturns true on success, otherwise 0.\n\nIf the \"AutoClose\" option has been enabled when the IO::Compress::Bzip2\nobject was created, and the object is associated with a file, the\nunderlying file will also be closed.\n\nnewStream([OPTS])\nUsage is\n\n$z->newStream( [OPTS] )\n\nCloses the current compressed data stream and starts a new one.\n\nOPTS consists of any of the options that are available when creating\nthe $z object.\n\nSee the \"Constructor Options\" section for more details.\n",
                "subsections": []
            },
            "Importing": {
                "content": "No symbolic constants are required by IO::Compress::Bzip2 at present.\n\n:all Imports \"bzip2\" and $Bzip2Error.  Same as doing this\n\nuse IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;\n",
                "subsections": []
            },
            "EXAMPLES": {
                "content": "Apache::GZip Revisited\nSee IO::Compress::FAQ\n\nWorking with Net::FTP\nSee IO::Compress::FAQ\n",
                "subsections": []
            },
            "SUPPORT": {
                "content": "General feedback/questions/bug reports should be sent to\n<https://github.com/pmqs/IO-Compress/issues> (preferred) or\n<https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,\nIO::Compress::Deflate, IO::Uncompress::Inflate,\nIO::Compress::RawDeflate, IO::Uncompress::RawInflate,\nIO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma,\nIO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip,\nIO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop,\nIO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd,\nIO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,\nIO::Uncompress::AnyUncompress\n\nIO::Compress::FAQ\n\nFile::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib\n\nThe primary site for the bzip2 program is\n<https://sourceware.org/bzip2/>.\n\nSee the module Compress::Bzip2\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "This module was written by Paul Marquess, \"pmqs@cpan.org\".\n",
                "subsections": []
            },
            "MODIFICATION HISTORY": {
                "content": "See the Changes file.\n",
                "subsections": []
            },
            "COPYRIGHT AND LICENSE": {
                "content": "Copyright (c) 2005-2021 Paul Marquess. All rights reserved.\n\nThis program is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n\nperl v5.34.0                      2026-06-23        IO::Compress::Bzip2(3perl)",
                "subsections": []
            }
        }
    }
}