Signed-off-by: Aaron Merey <ame...@redhat.com>
---
v3: Use the libelf.h comment for elf_compress/elf_compress_gnu as
the DESCRIPTION.
Do not include ELFCOMPRESS_LOOS, ELFCOMPRESS_LOPROC, etc. as valid
compression algorithm types. Mention that OS and arch-specific
algorithm types aren't supported.
doc/Makefile.am | 2 +
doc/elf_compress.3 | 226 +++++++++++++++++++++++++++++++++++++++++
doc/elf_compress_gnu.3 | 1 +
3 files changed, 229 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 486d9f22..9047a3ae 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..e1d584ad
--- /dev/null
+++ b/doc/elf_compress.3
@@ -0,0 +1,226 @@
+.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
+.PP
+.B elf_compress
+works by setting or clearing the
+.B SHF_COMPRESS
+flag from the section
+.I Shdr
+and will encode or decode a
+.I Elf32_Chdr
+or
+.I Elf64_Chdr
+at the start of the section data.
+.B elf_compress_gnu
+will encode or decode any section, but is traditionally only used for
+sections that have a name starting with
+.B ".debug"
+when uncompressed or
+.B ".zdebug"
+when compressed and stores just the uncompressed size.
+The GNU compression method is deprecated and should only be used for
+legacy support.
+
+.B elf_compress
+takes a compression type that should be either zero to decompress or an
+.B ELFCOMPRESS
+algorithm to use for compression.
+Currently
+.B ELFCOMPRESS_ZLIB
+and
+.B ELFCOMPRESS_ZSTD
+are supported.
+.B elf_compress_gnu
+will compress in the traditional GNU compression format when
+.I compress
+is one and decompress the section data when
+.I compress
+is zero.
+
+The
+.I FLAGS
+argument can be zero or
+.B ELF_CHF_FORCE.
+If
+.I FLAGS
+contains
+.B ELF_CHF_FORCE
+then it will always compress the section, even if that would not reduce
+the size of the data section (including the header). Otherwise
+.B elf_compress
+and
+.B elf_compress_gnu
+will compress the section only if the total data size is reduced.
+.PP
+On successful compression or decompression the function returns one.
+If (not forced) compression is requested and the data section would not
+actually reduce in size, the section is not actually compressed and zero
+is returned. Otherwise
+.B \-1
+is returned and
+.B elf_errno
+is set.
+.PP
+It is an error to request compression for a section that already has
+.B SHF_COMPRESSED
+set, or (for
+.BR elf_compress )
+to request decompression for an section that doesn't have
+.B SHF_COMPRESSED
+set.
+If a section has
+.B SHF_COMPRESSED
+set then calling
+.B elf_compress_gnu
+will result in an error.
+The section has to be decompressed first using
+.B elf_compress.
+Calling
+.B elf_compress
+on a section compressed with
+.B elf_compress_gnu
+is fine, but probably useless.
+.PP
+It is always an error to call these functions on
+.B SHT_NOBITS
+sections or if the section has the
+.B SHF_ALLOC
+flag set.
+.B elf_compress_gnu
+will not check whether the section name starts with
+.B ".debug"
+or
+.B ".zdebug".
+It is the responsibility of the caller to make sure the deprecated GNU
+compression method is only called on correctly named sections (and to
+change the name of the section when using
+.BR elf_compress_gnu ).
+.PP
+All previous returned
+.I Shdr
+and
+.I Elf_Data
+buffers are invalidated by this call and should no longer be accessed.
+.PP
+Note that although this changes the header and data returned it doesn't
+mark the section as dirty. To keep the changes when calling
+.B elf_update
+the section has to be flagged
+.B ELF_F_DIRTY.
+
+.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. Elfutils
+libelf does not support OS and processor specific compression algorithms.
+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.
+.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.
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.50.0
