doc: Add libelf man page

Message ID 20241018040233.1436333-1-amerey@redhat.com
State Committed
Headers
Series doc: Add libelf man page |

Commit Message

Aaron Merey Oct. 18, 2024, 4:02 a.m. UTC
  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

Mark Wielaard Oct. 18, 2024, 3:58 p.m. UTC | #1
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/.
  
Aaron Merey Oct. 18, 2024, 5:58 p.m. UTC | #2
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
  

Patch

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.
+
+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/.