NAME
        elf_zscn_decompress

SYNOPSIS
        cc [ flag ... ] file ... -lelf [ library ... ]
        #include <libelf.h>

        int elf_zscn_decompress(Elf_Scn *scn, const char *scn_name);

DESCRIPTION
        elf_zscn_decompress is used to decompress section data. If the
        section is in a compressed format, it is decompressed. If the
        section is already decompressed, then the section is not modified.

        scn_name is the name of the section, and is required in order
        to identify ELF_ZSCN_T_ZLIB_GNU type compression. If scn_name
        is NULL, elf_zscn_decompress will not recognize or decompress
        ELF_ZSCN_T_ZLIB_GNU sections.

RETURN VALUE
        Upon failure, elf_zscn_decompress returns -1 and sets elf_errno.
        Otherwise, the original compression type is returned, corresponding
        to the value that would have been returned by elf_zscn_identify()
        prior to decompression.

        If elf_zscn_identify returns ELF_ZSCN_T_NONE, then the original
        section was not compressed, and remains unchanged. Any other
        successful call to elf_zscn_decompress updates the section header
        to reflect the fact that the data is no longer compressed, and the
        compressed data is replaced with the uncompressed version. Any
        information previously returned by elf32_getshdr, elf64_shdr, or
        elf_getdata, will be invalidated, and should no longer be referenced.
        The caller should defer calling those functions until after calling
        elf_zscn_compress, or should call them again afterwards in order to
        obtain the new information.

EXAMPLES
        Example 1 Decompress all compressed sections

        The following code fragment iterates over all the sections
        of an ELF object, decompresses all compressed sections,
        and prints the section index, and name for each decompressed
        section. The details of obtaining the section name and error
        handling are omitted in the interest of brevity.

        ndx = 1;
        modified = 0;
        for (scn = NULL; scn = elf_nextscn(elf, scn); ndx++) {
                scn_name = get_scn_name(...);
                ztype = elf_zscn_identify(scn, scn_name);
                if (ztype == -1)
                        error(...);
                if (ztype != ELF_ZSCN_T_NONE) {
                        (void) printf("[%u] %s\n", ndx, scn_name);
                        if (elf_zscn_decompress(scn, scn_name) == -1)
                                ec_fatal_elf(fd, filename, elf,
                                    "elf_zscn_decompress");
                        modified = 1;
                }
        }
        if (modified)
                elf_update(elf, ELF_C_WRITE);

NOTES
        The ELF_ZSCN_T_ZLIB_GNU compression type can only be applied
        to sections with names that start with .debug. When compressed,
        that type requires the name to be altered to start with .zdebug.
        Upon later decompression, the original name must be restored.
        elf_zscn_decompress does not provide the replacement name. The
        caller is responsible for determining when data in the
        ELF_ZSCN_T_ZLIB_GNU compression format is being decompressed,
        and for restoring the original name. The elf_zscn_identify function
        can be used for this purpose.

SEE ALSO
       elf_errno(3ELF), elf_zscn_compress(3ELF), elf_zscn_decompress(3ELF),
       elf_zscn_identify(3ELF), libelf(3LIB), elf32_getshdr(3ELF),
       elf64_getshdr(3ELF), elf_errno(3ELF), elf_getdata(3ELF),
       elf_zscn_compress(3ELF), elf_zscn_compressible(3ELF),
       elf_zscn_identify(3ELF), libelf(3LIB)