Hi Aaron,
On Sun, 2025-06-22 at 19:02 -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> doc/Makefile.am | 2 +
> doc/elf_compress.3 | 183 +++++++++++++++++++++++++++++++++++++++++
> doc/elf_compress_gnu.3 | 1 +
> 3 files changed, 186 insertions(+)
> create mode 100644 doc/elf_compress.3
> create mode 100644 doc/elf_compress_gnu.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index de0106bb..aaf90606 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -52,6 +52,8 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_begin.3 \
> elf_clone.3 \
> elf_cntl.3 \
> + elf_compress.3 \
> + elf_compress_gnu.3 \
> elf_end.3 \
> elf_errmsg.3 \
> elf_errno.3 \
OK.
> diff --git a/doc/elf_compress.3 b/doc/elf_compress.3
> new file mode 100644
> index 00000000..df48336a
> --- /dev/null
> +++ b/doc/elf_compress.3
> @@ -0,0 +1,183 @@
> +.TH ELF_COMPRESS 3 2025-06-09 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_compress, elf_compress_gnu \- compress or decompress a section in an ELF
> object
> +.SH SYNOPSIS
> +.nf
> +#include <libelf.h>
> +
> +.BI "int elf_compress (Elf_Scn *" scn ", int" type ", unsigned int "flags");
> +.BI "int elf_compress_gnu (Elf_Scn *" scn ", int" compress ", unsigned int"
> flags ");
> +.fi
I find it hard to judge this one. Since I wrote the documentation in
libelf.h for these functions. It looks like your version is basically
based on that, but rearranged and slightly reworded. Do you feel your
rearrangement/rewording is better than what is in libelf.h? Is there a
way we can make sure these descriptions match? IMHO ideally the
documentation text is the same.
> +.SH DESCRIPTION
> +The functions
> +.BR elf_compress ()
> +and
> +.BR elf_compress_gnu ()
> +modify the contents of a section in an ELF descriptor by compressing or
> +decompressing the section data and adjusting the section header. These
> changes
> +take effect when the ELF descriptor is written with
> +.BR elf_update (3).
> +These functions do not mark the section as dirty. To retain the changes in
> +.B elf_update(),
> +call
> +.BR elf_flagscn (scn, ELF_C_SET, ELF_F_DIRTY) .
> +
> +.BR elf_compress ()
> +works by setting or clearing the
> +.B SHF_COMPRESSED
> +flag in the section header and will encode or decode an
> +.B Elf32_Chdr
> +or
> +.B Elf64_Chdr
> +structure at the start of the section data.
> +
> +.BR elf_compress_gnu ()
> +can encode or decode any section, but is traditionally used only for
> sections whose names begin with
> +.B .debug
> +when uncompressed or
> +.B .zdebug
> +when compressed. It stores only the uncompressed size followed by the
> compressed payload. The GNU compression method is deprecated and should be
> used only for legacy support.
> +
> +.BR elf_compress_gnu ()
> +does not check whether the section name begins with
> +.B .debug
> +or
> +.B .zdebug .
> +It is the responsibility of the caller to ensure that the deprecated GNU
> compression method is used only on appropriately named sections, and to
> rename the section if necessary when using
> +.BR elf_compress_gnu () .
> +
> +These functions invalidate all previously returned section headers and
> +.B Elf_Data
> +buffers for the affected section. The caller must not use these stale
> pointers
> +after invoking either function.
> +
> +The section must not be of type
> +.B SHT_NOBITS
> +and must not have the
> +.B SHF_ALLOC
> +flag set. Using these functions on such sections results in an error.
> +
> +Calling
> +.B elf_compress_gnu()
> +on a section with the
> +.B SHF_COMPRESSED
> +flag set is an error. The section must first be decompressed using
> +.B elf_compress (scn, 0, 0)
> +before applying GNU-style compression.
> +
> +.SH PARAMETERS
> +.SS elf_compress
> +.TP
> +.I scn
> +A pointer to an
> +.B Elf_Scn
> +structure representing the section to compress or decompress. Must not be
> NULL. The section must not be of type
> +.B SHT_NOBITS
> +and must not have the
> +.B SHF_ALLOC
> +flag set.
> +
> +.TP
> +.I type
> +Specifies the compression algorithm or decompression mode. Valid values are:
> +.RS
> +.TP
> +.B 0
> +Decompress the section. The section must currently have the
> +.B SHF_COMPRESSED
> +flag set.
> +.TP
> +.B ELFCOMPRESS_ZLIB
> +Compress the section using the ZLIB/DEFLATE algorithm.
> +.TP
> +.B ELFCOMPRESS_ZSTD
> +Compress the section using the Zstandard algorithm.
> +.TP
The above are indeed valid values.
But the following are not really:
> +.B ELFCOMPRESS_LOOS
> +Start of the OS-specific compression algorithm range.
> +.TP
> +.B ELFCOMPRESS_HIOS
> +End of the OS-specific compression algorithm range.
> +.TP
> +.B ELFCOMPRESS_LOPROC
> +Start of the processor-specific compression algorithm range.
> +.TP
> +.B ELFCOMPRESS_HIPROC
> +End of the processor-specific compression algorithm range.
> +.RE
The above are OS or Processor specific compression algorithm ranges,
not really valid values. I wouldn't document them here, except maybe to
say that elfutils doesn't support any arch or os specific values.
> +.TP
> +.I flags
> +May be zero or:
> +.RS
> +.TP
> +.B ELF_CHF_FORCE
> +Force compression even if it does not reduce the total size of the section
> (including any headers).
> +.RE
> +
> +.SS elf_compress_gnu
> +.TP
> +.I scn
> +Same as above. The section must not have the
> +.B SHF_COMPRESSED
> +flag set and must not be of type
> +.B SHT_NOBITS
> +or have the
> +.B SHF_ALLOC
> +flag set.
> +
> +.TP
> +.I compress
> +Set to 1 to compress using the legacy GNU format, or 0 to decompress.
> +
> +.TP
> +.I flags
> +Same as for
> +.BR elf_compress () .
> +
> +.SH RETURN VALUE
> +Both functions return:
> +
> +.TP
> +.B 1
> +The section was successfully compressed or decompressed.
> +
> +.TP
> +.B 0
> +Compression was requested but skipped because the result would not reduce
> size and
> +.B ELF_CHF_FORCE
> +was not set.
> +
> +.TP
> +.B \-1
> +An error occurred. The error code can be retrieved with
> +.BR elf_errno (3).
> +
> +
> +.SH SEE ALSO
> +.BR elf_update (3),
> +.BR elf_flagscn (3),
> +.BR elf_errno (3)
> +.BR libelf (3),
> +.BR elf (5),
> +
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.na
> +.nh
> +.BR elf_compress (),\~elf_compress_gnu ()
> +T} Thread safety MT-Unsafe race
> +.TE
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
> +
> +.SH HISTORY
> +.B elf_compress
> +first appeared in elfutils 0.165. This function is a elfutils libelf
> extension and
> +may not be available in other libelf implementations.
It might not be available in other (older) libelf implementations, but
it was developed together with the Solaris libelf hackers on the
generic_abi mailinglist and so can be considered a standard extension.
https://www.linker-aliens.org/blogs/ali/entry/elf_section_compression/
https://gnu.wildebeest.org/blog/mjw/2016/01/13/elf-libelf-compressed-sections-and-elfutils/
> diff --git a/doc/elf_compress_gnu.3 b/doc/elf_compress_gnu.3
> new file mode 100644
> index 00000000..d0ddf5ba
> --- /dev/null
> +++ b/doc/elf_compress_gnu.3
> @@ -0,0 +1 @@
> +.so man3/elf_compress.3
Cheers,
Mark
