Re: [PATCH 3/5] doc: Add elf_getbase.3
Hi Aaron,
On Tue, 2025-04-01 at 00:05 -0400, Aaron Merey wrote:
> diff --git a/doc/elf_getbase.3 b/doc/elf_getbase.3
> new file mode 100644
> index ..1934e1ac
> --- /dev/null
> +++ b/doc/elf_getbase.3
> @@ -0,0 +1,55 @@
> +.TH ELF_GETBASE 3 2025-03-31 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_getbase \- Retrieve the base offset for an ELF object file.
> +
> +.SH SYNOPSIS
> +.B #include
> +
> +.BI "int64_t elf_getbase(Elf *" elf ");"
> +
> +.SH DESCRIPTION
> +.B elf_getbase
> +returns the file offset of the first byte of the ELF descriptor
> +.IR elf .
Interesting, I didn't actually knew what this did. I had to look at the
one single use we have of this in tests/arextract.c. So it can be used
for a naive ar extraction utility. Our eu-ar uses elf_rawfile for that
though.
> +If
> +.I elf
> +is a member of an archive and has ELF kind
> +.BR ELF_K_AR ,
> +the base offset is the offset of the ELF object within the archive.
> +For other ELF object types the base offset is 0.
So this is only really interesting for AR entries? And then it gives
the file offset right after the AR header? Otherwise it returns zero?
> +.SH PARAMETERS
> +.TP
> +.I elf
> +The ELF descriptor.
> +
> +.SH RETURN VALUE
> +Return the base offset of
> +.IR elf .
> +If
> +.I elf
> +is NULL, return -1.
So should this say if the ELF kind is not ELF_K_AR it returns, unless
the elf is NULL, then it returns -1?
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
Maybe reference elf_getaroff? Which seems to do the same, but gives the
offset to the AR header inside the file? And elf_rawelf which gives you
a pointer to the same offset to read from.
> +.SH ATTRIBUTES
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute Value
> +T{
> +.na
> +.nh
> +.BR elf_getbase ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to or
> https://sourceware.org/bugzilla/.
Cheers,
Mark
Re: [PATCH 2/5] doc: Add elf_fill.3
Hi Aaron,
On Tue, 2025-04-01 at 00:05 -0400, Aaron Merey wrote:
> diff --git a/doc/elf_fill.3 b/doc/elf_fill.3
> new file mode 100644
> index ..9448b064
> --- /dev/null
> +++ b/doc/elf_fill.3
> @@ -0,0 +1,53 @@
> +.TH ELF_FILL 3 2025-03-31 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_fill \- Set fill byte used when constructing or editing ELF object files.
> +
> +.SH SYNOPSIS
> +.nf
> +#include
> +
> +.BI "void elf_fill(int " fill ");"
> +
> +.SH DESCRIPTION
> +The
> +.B elf_fill
> +function sets the fill byte used by libelf to pad gaps between ELF sections
> +or data elements when an ELF object file is resized or realigned using
> +.BR elf_update .
Good. Maybe say "new gaps" because if elf_update doesn't realign/move
section data around the exist "fill" just stays in place. But maybe
that is too pedantic.
> +The default fill byte used by libelf is zero.
> +
> +.SH PARAMETERS
> +.TP
> +.I fill
> +The value used to fill gaps in future writes to ELF objects. This value
> +should be between 0 and 255 (inclusive). Only the least significant
> +8 bits are used.
Ah, because it is an int and that is how memset works. OK.
> +.SH RETURN VALUE
> +.B elf_fill
> +returns no value.
> +
> +.SH SEE ALSO
> +.BR elf_update (3),
> +.BR libelf (3),
> +.BR elf (5)
> +
> +.SH ATTRIBUTES
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute Value
> +T{
> +.na
> +.nh
> +.BR elf_fill ()
> +T} Thread safety MT-Safe
> +.TE
Are you sure about it being MT-Safe. It is process wide and not bound
to any particular ELF. So I would say MT-Unsafe race or MT-Unsafe const
maybe?
> +.SH REPORTING BUGS
> +Report bugs to or
> https://sourceware.org/bugzilla/.
> +
Cheers,
Mark
Re: [PATCH 5/5] doc: Add elf_kind.3
Hi Aaron,
On Tue, 2025-04-01 at 00:05 -0400, Aaron Merey wrote:
> diff --git a/doc/elf_kind.3 b/doc/elf_kind.3
> new file mode 100644
> index ..3caa2724
> --- /dev/null
> +++ b/doc/elf_kind.3
> @@ -0,0 +1,71 @@
> +.TH ELF_KIND 3 2025-03-31 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_kind \- Determine the type of file represented by an ELF descriptor.
> +
> +.SH SYNOPSIS
> +.nf
> +#include
> +
> +.BI "Elf_Kind elf_kind(Elf *" elf ");"
> +
> +.SH DESCRIPTION
> +The
> +.B elf_kind
> +function determines the file type of the file represented by
> +.IR elf .
> +This type identifies whether the descriptor represents an
> +ELF object, an archive member, or some other type of file.
> +
> +.SH PARAMETERS
> +.TP
> +.I elf
> +The ELF descriptor.
> +
> +.SH RETURN VALUE
> +The file type of the file represented by
> +.IR elf .
> +The possible return value are
> +
> +.RS
> +.TP
> +.PD 0
> +.TP
> +.TP
> +.B ELF_K_NONE
> +Unknown file type.
> +
> +.TP
> +.B ELF_K_AR
> +Archive member.
> +
> +.TP
> +.B ELF_K_COFF
> +COFF object file.
Maybe mention that elfutils libelf doesn't support COFF object files?
> +
> +.TP
> +.B ELF_K_ELF
> +ELF object file.
> +
> +
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
elf.5 doesn't describe the ar format, should it? Or should we have an
ar.5 man page?
> +
> +.SH ATTRIBUTES
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute Value
> +T{
> +.na
> +.nh
> +.BR elf_kind ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to or
> https://sourceware.org/bugzilla/.
Cheers,
Mark
Re: [PATCH 4/5] doc: Add elf_hash.3
Hi Aaron,
On Tue, 2025-04-01 at 00:05 -0400, Aaron Merey wrote:
> diff --git a/doc/elf_hash.3 b/doc/elf_hash.3
> new file mode 100644
> index ..6082c8c8
> --- /dev/null
> +++ b/doc/elf_hash.3
> @@ -0,0 +1,49 @@
> +.TH ELF_HASH 3 2025-03-31 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_hash \- Compute the standard ELF hash of a string.
> +
> +.SH SYNOPSIS
> +.nf
> +#include
> +
> +.BI "int elf_hash(const char *" string ");"
The actual signature is:
unsigned long int elf_hash (const char *string);
But it looks like the code makes sure only 32bits are relevant.
Which should probably be mentioned below.
> +
> +.SH DESCRIPTION
> +The
> +.B elf_hash
> +function computes the standard ELF hash value for a null-terminated
> +string. The hash values are typically used in ELF object files for
> +symbol table hashing. The hash function avoids generating
> +architecture-dependent values and is suitable for use across architectures.
Maybe mention "as used in SHT_HASH sections"?
> +.SH PARAMETERS
> +.TP
> +.I string
> +NULL-terminated string to be hashed.
> +
> +.SH RETURN VALUE
> +This function returns the standard ELF hash value for
> +.IR string .
Mention that the returned hash is a 32bit value?
> +
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
> +
> +.SH ATTRIBUTES
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute Value
> +T{
> +.na
> +.nh
> +.BR elf_hash ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to or
> https://sourceware.org/bugzilla/.
Cheers,
Mark
