Hi Aaron, On Tue, Apr 14, 2026 at 11:05:28PM -0400, Aaron Merey wrote: > doc/gelf.3 has been added which redirects to libelf.3.
> Included gelf.h info in DESCRIPTION, FILE VS MEMORY REPRESENTATION > and ERROR HANDLING. Moved GELF NAMESPACE into NAMESPACE. Nice. > 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. Too bad there are all these exceptions. But yeah. > 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 Ack. > 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 OK. > 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. OK. For those "overflow" values an error is returned. > .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. OK. > 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. OK. > .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 OK. > @@ -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 Nice. > @@ -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 Looks complete. > +.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 OK, also complete. Thanks, Mark
