Hi Aaron,
I think if still possible you should include this in the release.
I made some comments below, but they can be addressed later. They are
just clarifications.
On Fri, 2024-10-18 at 00:02 -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> config/elfutils.spec.in | 1 +
> doc/Makefile.am | 3 +-
> doc/libelf.3 | 363 ++++++++++++++++++++++++++++++++++++++++
> 3 files changed, 366 insertions(+), 1 deletion(-)
> create mode 100644 doc/libelf.3
>
> diff --git a/config/elfutils.spec.in b/config/elfutils.spec.in
> index 0d1ec11b..dcaa85b3 100644
> --- a/config/elfutils.spec.in
> +++ b/config/elfutils.spec.in
> @@ -304,6 +304,7 @@ fi
> %{_mandir}/man3/elf_*.3*
> %{_mandir}/man3/elf32_*.3*
> %{_mandir}/man3/elf64_*.3*
> +%{_mandir}/man3/libelf.3
>
> %files libelf-devel-static
> %{_libdir}/libelf.a
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index ceb6fd2d..c95369e9 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -57,7 +57,8 @@ notrans_dist_man3_MANS= elf_update.3 \
> elf32_fsize.3 \
> elf64_fsize.3 \
> elf32_checksum.3 \
> - elf64_checksum.3
> + elf64_checksum.3 \
> + libelf.3
>
> # libdebuginfod man pages (also notrans)
> # Note we include them even when not building them because we want
> diff --git a/doc/libelf.3 b/doc/libelf.3
> new file mode 100644
> index 00000000..e6fb1a1b
> --- /dev/null
> +++ b/doc/libelf.3
> @@ -0,0 +1,363 @@
> +.TH LIBELF 3 2024-10-18 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +libelf \- a library for accessing and manipulating ELF (Executable and
> Linkable
> +Format) files
> +.SH LIBRARY
> +Elfutils library (\fBlibelf\fP, \fBlibelf.so\fP, \fB-lelf\fP)
> +.SH SYNOPSIS
> +.nf
> +.B #include <libelf.h>
> +
> +.SH DESCRIPTION
> +The \fBlibelf\fP library provides an API for reading, writing, and
> manipulating
> +ELF (Executable and Linkable Format) files. ELF is a standard format for
> object
> +files, shared libraries, core dumps, and executables. See
> +.BR elf (5)
> +for more information regarding ELF.
> +
> +\fBlibelf\fP provides routines for working with ELF object file headers,
> +sections, symbol tables, relocation entries, and other key components.
I would s/key components/ELF data structures/
> +The core of the library is based on
> +.I Elf
> +file descriptors representing ELF files, which can be read from, written to,
> +or updated in-place. The \fBelf_begin\fP function initializes access to an
> +ELF object, while additional functions like \fBelf_getscn\fP,
> \fBelf_getdata\fP,
> +and \fBelf_ndxscn\fP provide access to specific parts of the ELF file.
I would move the general part about there being 32-bit (ELFCLASS32) and
64-bit (ELFCLASS64) objects and that there are specific elf32 and elf64
functions for manipulating each of them from NAMESPACE below here just
before MEMORY REPRESENTATION.
> +.SH FILE VS MEMORY REPRESENTATION
> +
> +The \fBlibelf\fP library distinguishes between the file representation of an
> +ELF file and its memory representation.
> +
> +.PP
> +File Representation refers to the format in which an ELF file is stored on
> disk.
> +The fields in the file may use specific sizes, alignment, and byte ordering
> +(endianness) that could be different from the native format used by the host
> +system.
> +
> +.PP
> +Memory Representation refers to the way the ELF data is organized when loaded
> +into an application's memory. In memory, the data structures are typically
> +converted into the native format of the host system (e.g., the system's
> +endianness, word size, and alignment).
> +
> +.PP
> +\fBlibelf\fP provides the following functions to translate ELF data between
> +file and memory representations:
> +.BR elf32_xlatetom ,
> +.BR elf64_xlatetom ,
> +.BR elf32_xlatetof ,
> +and
> +.BR elf64_xlatetof .
> +
> +See
> +.BR elf32_xlatetom (3)
> +for more information.
> +
> +.SH ELF VERSION
> +
> +To account for the possibility of multiple versions of the ELF specification,
> +the ELF version number must be specified with the \fBelf_version\fP function
> +before any other \fBlibelf\fP functions.
Maybe add:
... are called. Otherwise they might return an error.
> This function sets \fBlibelf\fP's ELF
> +version to the specified value. At this time the only supported ELF version
> is
> +\fBEV_CURRENT\fP.
>
> +.SH DESCRIPTORS
> +.I Elf
> +descriptors the central \fBlibelf\fP object for accessing and manipulating
> +ELF files. They are created with the
> +.BR elf_begin ,
> +.BR elf_clone ,
> +and
> +.B elf_memory
> +functions and closed with the
> +.B elf_end
> +function.
> +
> +\fBlibelf\fP also provides
> +.I Elf_Scn
> +and
> +.I Elf_Data
> +descriptors for ELF sections and section contents, respectively. Members
> +of the
> +.I Elf_Data
> +struct are described below.
> +Members of the
> +.I Elf
> +and
> +.I Elf_Scn
> +structs are hidden from applications.
> +
> +These descriptors can be acquired and modified using various
> +functions provided by \fBlibelf\fP. See
> +.B libelf.h
> +for a complete list.
> +
> +.SH ERROR HANDLING
> +If a \fBlibelf\fP function encounters an error it will set an internal
> +error code that can be retrieved with
> +.BR elf_errno .
> +Each thread maintains its own separate error code. The meaning of
> +each error code can be determined with
> +.BR elf_errmsg,
> +which returns a string describing the error.
> +
> +.SH MEMORY MANAGEMENT
> +\fBlibelf\fP manages all of the memory it allocates and frees it with
> +.BR elf_end .
> +The application must not call
> +.B free
> +on any memory allocated by \fBlibelf\fP.
> +
> +.SH NAMESPACE
> +\fBlibelf\fP uses the following prefix format. See \fBlibelf.h\fP for more
> +information.
> +
> +.RS
> +.TP
> +.PD 0
> +.TP
> +.B elf_
> +Functions usable with both 32-bit and 64-bit ELF files.
> +
> +.TP
> +.B elf32_
> +Functions usable with 32-bit ELF files.
> +
> +.TP
> +.B elf64_
> +Functions usable with 64-bit ELF files.
> +
> +.TP
> +.B Elf_
> +Type that represents data for both 32-bit and 64-bit ELF files.
> +
> +.TP
> +.B Elf32_
> +Type that represents data for 32-bit ELF files.
> +
> +.TP
> +.B Elf64_
> +Type that represents data for 64-bit ELF files.
> +
> +.TP
> +.B ELF_C_
> +.I Elf_Cmd
> +values used in functions such as
> +.B elf_flagset
> +and
> +.BR elf_cntl .
> +
> +.TP
> +.B ELF_F_
> +Flags for ELF structures.
> +
> +.TP
> +.B ELF_K_
> +.I Elf_Kind
> +Identification values for recognized object file types.
> +
> +.TP
> +.B ELF_T_
> +.I Elf_Type
> +values representing the known types of ELF data such as
> +.BR ELF_T_BYTE ,
> +(unsigned char)
> +.BR ELF_T_REL ,
> +(relocation entry)
> +or
> +.B ELF_T_SYM
> +(symbol record).
> +.fi
> +.PD
> +.RE
> +
> +.SH DATA STRUCTURES
> +\fBlibelf\fP implements the following data structures, in addition to
> including
> +the data structures given in the ELF specification (see
> +.BR elf (5)
> +for more information).
> +
> +.SS Section Compression Header
> +.nf
> +.in +4
> +typedef struct {
> + Elf32_Word ch_type;
> + Elf32_Word ch_size;
> + Elf32_Word ch_addralign;
> +} Elf32_Chdr;
> +
> +typedef struct {
> + Elf64_Word ch_type;
> + Elf64_Word ch_reserved;
> + Elf64_Xword ch_size;
> + Elf64_Xword ch_addralign;
> + } Elf64_Chdr;
> +.fi
> +
> +.TP
> +.I ch_type
> +Compression format type. Legal values include
> +.BR ELFCOMPRESS_ZLIB ,
> +.BR ELFCOMPRESS_ZSTD ,
> +the inclusive range between
> +.B ELFCOMPRESS_LOOS
> +to
> +.B ELFCOMPRESS_HIOS
> +as well as the inclusive range between
> +.B ELFCOMPRESS_LOPROC
> +and
> +.B ELFCOMPRESS_HIPROC
> +
> +.RS
> +.TP
> +.PD 0
> +.B ELFCOMPRESS_ZLIB
> +ZLIB/DEFLATE algorithm.
> +.TP
> +.B ELFCOMPRESS_ZSTD
> +Zstandard algorithm.
> +.TP
> +.B ELFCOMPRESS_LOOS
> +Start of OS-specific compression types.
> +.TP
> +.B ELFCOMPRESS_HIOS
> +End of OS-specific compression types.
> +.TP
> +.B ELFCOMPRESS_LOPROC
> +Start of processor-specific compression types.
> +.TP
> +.B ELFCOMPRESS_HIPROC
> +End of processor-specific compression types.
> +.PD
> +.RE
> +
> +.TP
> +.I ch_reserved
> +Space reserved for use by \fBlibelf\fP.
> +
> +.TP
> +.I ch_size
> +Data size of uncompressed section.
> +
> +.TP
> +.I ch_addralign
> +Alignment of uncompressed section.
> +
> +
I think all these really should be defined in elf.h.
And are only defined in libelf.h when not found there.
(Doesn't mean you cannot document them here, but maybe note that.)
> +.SS Section Data
> +.nf
> +.in +4
> +typedef struct {
> + void *d_buf;
> + Elf_Type d_type;
> + unsigned int d_version;
> + size_t d_size;
> + int64_t d_off;
> + size_t d_align;
> +} Elf_Data;
> +.fi
> +
> +.TP
> +.I d_buf
> +Pointer to the actual data.
> +Use
> +.B elf_getdata
> +to retrieve data in memory representation and
> +.B elf_rawdata
> +to retrieve data in file representation.
> +
> +.TP
> +.I d_type
> +The
> +.I Elf_Type
> +of this piece of data. See the
> +.I Elf_Type
> +enum in
> +.B libelf.h
> +for descriptions of each value.
> +
> +.TP
> +.I d_version
> +The ELF version for this data.
> +
> +.TP
> +.I d_size
> +The size in bytes of this data.
> +
> +.TP
> +.I d_off
> +The section offset of this data.
> +
> +.TP
> +.I d_align
> +The section alignment of this data.
> +
> +.SS Archive Member Header
> +.nf
> +.in +4
> +typedef struct {
> + char *ar_name;
> + time_t ar_date;
> + uid_t ar_uid;
> + gid_t ar_gid;
> + mode_t ar_mode;
> + int64_t ar_size;
> + char *ar_rawname;
> +} Elf_Arhdr;
> +.fi
> +
> +.TP
> +.I ar_name
> +Name of archive member.
> +
> +.TP
> +.I ar_data
> +File date.
> +
> +.TP
> +.I ar_uid
> +User ID.
> +
> +.TP
> +.I ar_gid
> +Group ID.
> +
> +.TP
> +.I ar_mode
> +File mode.
> +
> +.TP
> +.I ar_size
> +File size.
> +
> +.TP
> +.I ar_rawname
> +Original name of archive member.
> +
> +.SS Archive Symbol Table Entry
> +.nf
> +.in +4
> +typedef struct {
> + char *as_name;
> + size_t as_off;
> + unsigned long int as_hash;
> +} Elf_Arsym;
> +.fi
> +
> +.TP
> +.I as_name
> +Symbol name.
> +
> +.TP
> +.I as_off
> +Offset for this file in the archive.
> +
> +.TP
> +.I as_hash
> +Hash value of the name.
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
