doc/gelf.3 has been added which redirects to libelf.3. Signed-off-by: Aaron Merey <[email protected]> ---
v3 changes: Rewritten to avoid inclusion of LLM output. v2 was prepared before elfutils had an LLM policy. Added gelf.3 redirecting to libelf.3. Included gelf.h info in DESCRIPTION, FILE VS MEMORY REPRESENTATION and ERROR HANDLING. Moved GELF NAMESPACE into NAMESPACE. On Tue, Nov 18, 2025 at 9:59 AM Mark Wielaard <[email protected]> wrote: > And in 'ERROR HANDLING' maybe mention that gelf_ functions return zero > on failure (where elf[32|64] functions that return an int return non- > zero on failure, but mostly just a datastructure/descriptor where NULL > is failure). I looked into this but I couldn't find many consistent rules that didn't have at least one exception. Not all elf[32|64] functions returning an integer type return non-zero on error (elf_ndxscn will return SHN_UNDEF which is zero). Not all gelf_ functions return zero on error (gelf_checksum returns -1). The only consistent return value rule I could find was that libelf functions returning a pointer will return NULL on error. I added this to ERROR HANDLING. doc/Makefile.am | 1 + doc/gelf.3 | 1 + doc/libelf.3 | 104 ++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 103 insertions(+), 3 deletions(-) create mode 100644 doc/gelf.3 diff --git a/doc/Makefile.am b/doc/Makefile.am index 35e158b4..c1ac66dc 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -91,6 +91,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \ elf_strptr.3 \ elf_update.3 \ elf_version.3 \ + gelf.3 \ gelf_checksum.3 \ gelf_fsize.3 \ gelf_getauxv.3 \ diff --git a/doc/gelf.3 b/doc/gelf.3 new file mode 100644 index 00000000..e7ffe66a --- /dev/null +++ b/doc/gelf.3 @@ -0,0 +1 @@ +.so man3/libelf.3 diff --git a/doc/libelf.3 b/doc/libelf.3 index e6fb1a1b..af2f55a2 100644 --- a/doc/libelf.3 +++ b/doc/libelf.3 @@ -8,6 +8,7 @@ Elfutils library (\fBlibelf\fP, \fBlibelf.so\fP, \fB-lelf\fP) .SH SYNOPSIS .nf .B #include <libelf.h> +.B #include <gelf.h> .SH DESCRIPTION The \fBlibelf\fP library provides an API for reading, writing, and manipulating @@ -26,6 +27,19 @@ 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 GELF INTERFACE +\fB<gelf.h>\fP provides a class-independent interface to \fBlibelf\fP that +transparently handles both \fBELFCLASS32\fP and \fBELFCLASS64\fP binaries. +This allows callers to avoid selecting \fBlibelf\fP functions that are +specialized for working with a particular class of ELF binary. + +\fIGElf_\fP types defined in \fB<gelf.h>\fP are aliases for their \fIElf64_\fP +equivalents. Any conversions to \fIElf32_\fP types are handled internally by +\fBgelf_\fP functions. See \fBGELF DATA STRUCTURES\fP and \fBGELF MACROS\fP +for more information. When using \fBgelf_\fP functions that modify data +structure values for \fBELFCLASS32\fP binaries, the size of the value should +not exceed the maximum size of the \fBELFCLASS32\fP equivalent. + .SH FILE VS MEMORY REPRESENTATION The \fBlibelf\fP library distinguishes between the file representation of an @@ -51,6 +65,11 @@ file and memory representations: .BR elf32_xlatetof , and .BR elf64_xlatetof . +\fB<gelf.h>\fP provides +.B gelf_xlatetom +and +.B gelf_xlatetof +for class-independent translation between file and memory representations. See .BR elf32_xlatetom (3) @@ -102,7 +121,8 @@ error code that can be retrieved with 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. +which returns a string describing the error. \fBlibelf\fP functions +returning a pointer return NULL on failure. .SH MEMORY MANAGEMENT \fBlibelf\fP manages all of the memory it allocates and frees it with @@ -112,8 +132,8 @@ The application must not call on any memory allocated by \fBlibelf\fP. .SH NAMESPACE -\fBlibelf\fP uses the following prefix format. See \fBlibelf.h\fP for more -information. +\fBlibelf\fP uses the following prefix format. See \fBlibelf.h\fP and +\fBgelf.h\fP for more information. .RS .TP @@ -170,6 +190,18 @@ values representing the known types of ELF data such as or .B ELF_T_SYM (symbol record). + +.TP +.B gelf_ +Class-independent functions. + +.TP +.B GElf_ +Class-independent types. + +.TP +.B GELF_ +Class-independent macros. .fi .PD .RE @@ -359,5 +391,71 @@ Offset for this file in the archive. .I as_hash Hash value of the name. +.SH GELF DATA STRUCTURES + +\fIGElf_\fP types are aliases for their \fIElf64_\fP equivalents. +See +.B elf(5) +for more information regarding the underlying types. + +.TS +tab(:); +lB lB +l l. +GElf type:Underlying 64-bit type +_ +GElf_Half:Elf64_Half +GElf_Word:Elf64_Word +GElf_Sword:Elf64_Sword +GElf_Xword:Elf64_Xword +GElf_Sxword:Elf64_Sxword +GElf_Addr:Elf64_Addr +GElf_Off:Elf64_Off +GElf_Ehdr:Elf64_Ehdr +GElf_Shdr:Elf64_Shdr +GElf_Section:Elf64_Section +GElf_Sym:Elf64_Sym +GElf_Syminfo:Elf64_Syminfo +GElf_Rel:Elf64_Rel +GElf_Rela:Elf64_Rela +GElf_Relr:Elf64_Relr +GElf_Phdr:Elf64_Phdr +GElf_Chdr:Elf64_Chdr +GElf_Dyn:Elf64_Dyn +GElf_Verdef:Elf64_Verdef +GElf_Verdaux:Elf64_Verdaux +GElf_Verneed:Elf64_Verneed +GElf_Vernaux:Elf64_Vernaux +GElf_Versym:Elf64_Versym +GElf_auxv_t:Elf64_auxv_t +GElf_Nhdr:Elf64_Nhdr +GElf_Move:Elf64_Move +GElf_Lib:Elf64_Lib +.TE + +.SH GELF MACROS +All \fBGELF_\fP macros are aliases for their \fBELF64_\fP equivalents. +See +.B elf(5) +for more information regarding the underlying macros. + +.TS +tab(:); +lB lB +l l. +GElf macro:Underlying 64-bit macro +_ +GELF_ST_BIND:ELF64_ST_BIND +GELF_ST_TYPE:ELF64_ST_TYPE +GELF_ST_INFO:ELF64_ST_INFO +GELF_ST_VISIBILITY:ELF64_ST_VISIBILITY +GELF_M_INFO:ELF64_M_INFO +GELF_M_SIZE:ELF64_M_SIZE +GELF_M_SYM:ELF64_M_SYM +GELF_R_INFO:ELF64_R_INFO +GELF_R_TYPE:ELF64_R_TYPE +GELF_R_SYM:ELF64_R_SYM +.TE + .SH REPORTING BUGS Report bugs to <[email protected]> or https://sourceware.org/bugzilla/. -- 2.53.0
