Hi Aaron, On Sun, 2025-11-09 at 23:40 -0500, Aaron Merey wrote: > Add sections "GELF INTERFACE", "GELF NAMESPACE" and "GELF DATA > STRUCTURES".
I think I would have added these to their own gelf.3 manpage. But this also works. Maybe have a gelf.3 -> libelf.3? > diff --git a/doc/libelf.3 b/doc/libelf.3 > index e6fb1a1b..eb5d1c18 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 > @@ -112,8 +113,8 @@ The application must not call > on any memory allocated by \fBlibelf\fP. Shouldn't there be a sentence/paragraph about the gelf interface in the description? Same for the 'FILE VS MEMORY REPRESENTATION' section. At least mention gelf_xlatetom and gelf_xlatetof? 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). > .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, but don't you want to actually mention gelf_... functions are ... GElf_... types are ... ? [later...] Aha, you do that in its own separate Section below. Maybe explicitly mention that here then? > @@ -359,5 +360,122 @@ Offset for this file in the archive. > .I as_hash > Hash value of the name. > > +.SH GELF INTERFACE > +.B <gelf.h> > +provides an additional class-independent interface on top of libelf that > supports > +both ELFCLASS32 and ELFCLASS64 binaries without specialization based on byte > size. byte size? > +This interface provides > +.B GElf_* > +types that are sized according to the largest common denominator between the > +corresponding > +.B Elf32_* > +and > +.B Elf64_* > +types. > +.B gelf_* > +functions transparently handle any type conversions necessary to match > +the class of an ELF binary. > + > +Note that if an ELF binary has class > +.BR ELFCLASS32 , > +then any > +.B GElf_* > +values and struct fields should be able to fit into the corresponding > +ELFCLASS32 values and struct fields. For example, a > +.B GElf_Off > +value used with an > +.B ELFCLASS32 > +binary should fit in a > +.B Elf32_Off > +value. OK. > +.SH GELF NAMESPACE > + > +.RS > +.TP > +.PD 0 > +.TP > +.B gelf_ > +Class-independent libelf functions. > + > +.TP > +.B GElf_ > +Types that represent class-independent data for ELF files. > + > +.TP > +.B GELF_ > +Class-independent macros for manipulating particular GElf struct fields. > + > +.fi > +.PD > +.RE OK. > +.SH GELF DATA STRUCTURES > + > +All GElf types are defined as aliases for their 64-bit ELF counterparts. > +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 OK. > +.SH GELF MACROS > +All GElf macros are defined as aliases for their 64-bit ELF counterparts. > +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 Yeah. I don't think the _M_ macros are ever really used because they are for SHT_SUNW_move section content. But we do define them. > .SH REPORTING BUGS > Report bugs to <[email protected]> or > https://sourceware.org/bugzilla/. Thanks, Mark
