Commit Message
Signed-off-by: Aaron Merey <amerey@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
Comments
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 <amerey@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/.
On Fri, Oct 18, 2024 at 11:59 AM Mark Wielaard <mark@klomp.org> wrote:
>
> 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.
Thanks Mark, pushed. Will update after the release. (Discussed on IRC
but repeating here).
Aaron
@@ -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
@@ -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
new file mode 100644
@@ -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.
+
+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.
+
+.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. 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.
+
+
+.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/.