diff mbox series

[08/16] doc: Add elf_gnu_hash.3

Message ID 20250701031248.1106390-8-amerey@redhat.com
State Superseded
Delegated to: Mark Wielaard
Headers
Series [01/16] doc: Add elf_memory.3 |

Commit Message

Aaron Merey July 1, 2025, 3:12 a.m. UTC 
  Signed-off-by: Aaron Merey <amerey@redhat.com>
---
 doc/Makefile.am    |  1 +
 doc/elf_gnu_hash.3 |  1 +
 doc/elf_hash.3     | 20 +++++++++++++++++---
 3 files changed, 19 insertions(+), 3 deletions(-)
 create mode 100644 doc/elf_gnu_hash.3

Comments

Mark Wielaard July 8, 2025, 8:10 p.m. UTC | #1 
Hi Aaron,

On Mon, Jun 30, 2025 at 11:12:25PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <amerey@redhat.com>
> ---
>  doc/Makefile.am    |  1 +
>  doc/elf_gnu_hash.3 |  1 +
>  doc/elf_hash.3     | 20 +++++++++++++++++---
>  3 files changed, 19 insertions(+), 3 deletions(-)
>  create mode 100644 doc/elf_gnu_hash.3
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 129c612d..98712576 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -75,6 +75,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
>  			elf_getshnum.3 \
>  			elf_getshstrndx.3 \
>  			elf_hash.3 \
> +			elf_gnu_hash.3 \
>  			elf_kind.3 \
>  			elf_memory.3 \
>  			elf_ndxscn.3 \

OK.

> diff --git a/doc/elf_gnu_hash.3 b/doc/elf_gnu_hash.3
> new file mode 100644
> index 00000000..d87463f1
> --- /dev/null
> +++ b/doc/elf_gnu_hash.3
> @@ -0,0 +1 @@
> +.so man3/elf_hash.3
> diff --git a/doc/elf_hash.3 b/doc/elf_hash.3
> index 1e06d888..2313f3b5 100644
> --- a/doc/elf_hash.3
> +++ b/doc/elf_hash.3
> @@ -1,13 +1,14 @@
>  .TH ELF_HASH 3 2025-03-31 "Libelf" "Libelf Programmer's Manual"
>  
>  .SH NAME
> -elf_hash \- Compute the standard ELF hash of a string.
> +elf_hash, elf_gnu_hash \- Compute the standard ELF hash of a string.

standard or GNU?
  
>  .SH SYNOPSIS
>  .nf
>  #include <libelf.h>
>  
>  .BI "unsigned long int elf_hash(const char *" string ");"
> +.BI "unsigned long int elf_gnu_hash(const char *" string ");"

OK.

>  .SH DESCRIPTION
>  The
> @@ -18,13 +19,21 @@ symbol table hashing.  The hash function is used in SHT_HASH sections as
>  it avoids generating architecture-dependent values and is suitable for use
>  across architectures.
>  
> +The
> +.BR elf_gnu_hash
> +function computes the GNU-style hash value of a null-terminated string,
> +used in
> +.B SHT_GNU_HASH
> +sections. This method is more space- and time-efficient in dynamic symbol lookup
> +compared to the standard ELF hash, particularly for larger symbol tables.

Yes, but that is the table setup. But the funcion just calculates a
hash value. The hash is also 32bits, maybe it is slightly faster?

>  .SH PARAMETERS
>  .TP
>  .I string
>  NULL-terminated string to be hashed.
>  
>  .SH RETURN VALUE
> -This function returns the standard ELF hash value for
> +These functions return a hash value for
>  .IR string .
>  Only the lower 32 bits of the return value are used.

OK.

> @@ -43,9 +52,14 @@ Interface	Attribute	Value
>  T{
>  .na
>  .nh
> -.BR elf_hash ()
> +.BR elf_hash (),\~elf_gnu_hash ()
>  T}	Thread safety	MT-Safe
>  .TE
>  
>  .SH REPORTING BUGS
>  Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
> +
> +.SH HISTORY
> +.B elf_gnu_hash
> +first appeared in elfutils 0.122.  This function is a elfutils libelf extension and
> +may not be available in other libelf implementations.

OK.

Thanks,

Mark
diff mbox series

Patch

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 129c612d..98712576 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -75,6 +75,7 @@  notrans_dist_man3_MANS= elf32_checksum.3 \
 			elf_getshnum.3 \
 			elf_getshstrndx.3 \
 			elf_hash.3 \
+			elf_gnu_hash.3 \
 			elf_kind.3 \
 			elf_memory.3 \
 			elf_ndxscn.3 \
diff --git a/doc/elf_gnu_hash.3 b/doc/elf_gnu_hash.3
new file mode 100644
index 00000000..d87463f1
--- /dev/null
+++ b/doc/elf_gnu_hash.3
@@ -0,0 +1 @@ 
+.so man3/elf_hash.3
diff --git a/doc/elf_hash.3 b/doc/elf_hash.3
index 1e06d888..2313f3b5 100644
--- a/doc/elf_hash.3
+++ b/doc/elf_hash.3
@@ -1,13 +1,14 @@ 
 .TH ELF_HASH 3 2025-03-31 "Libelf" "Libelf Programmer's Manual"
 
 .SH NAME
-elf_hash \- Compute the standard ELF hash of a string.
+elf_hash, elf_gnu_hash \- Compute the standard ELF hash of a string.
 
 .SH SYNOPSIS
 .nf
 #include <libelf.h>
 
 .BI "unsigned long int elf_hash(const char *" string ");"
+.BI "unsigned long int elf_gnu_hash(const char *" string ");"
 
 .SH DESCRIPTION
 The
@@ -18,13 +19,21 @@  symbol table hashing.  The hash function is used in SHT_HASH sections as
 it avoids generating architecture-dependent values and is suitable for use
 across architectures.
 
+The
+.BR elf_gnu_hash
+function computes the GNU-style hash value of a null-terminated string,
+used in
+.B SHT_GNU_HASH
+sections. This method is more space- and time-efficient in dynamic symbol lookup
+compared to the standard ELF hash, particularly for larger symbol tables.
+
 .SH PARAMETERS
 .TP
 .I string
 NULL-terminated string to be hashed.
 
 .SH RETURN VALUE
-This function returns the standard ELF hash value for
+These functions return a hash value for
 .IR string .
 Only the lower 32 bits of the return value are used.
 
@@ -43,9 +52,14 @@  Interface	Attribute	Value
 T{
 .na
 .nh
-.BR elf_hash ()
+.BR elf_hash (),\~elf_gnu_hash ()
 T}	Thread safety	MT-Safe
 .TE
 
 .SH REPORTING BUGS
 Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf_gnu_hash
+first appeared in elfutils 0.122.  This function is a elfutils libelf extension and
+may not be available in other libelf implementations.