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 \
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
+.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
+.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
+
+.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.
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
--
2.49.0
