Re: [PATCH 0/9 v2] Fix thread-safety for elfutils
On Donnerstag, 18. Juli 2024 00:33:59 MESZ Aaron Merey wrote:
> v1 can be found at
> https://sourceware.org/pipermail/elfutils-devel/2023q3/006329.html
>
> Heather McIntyre is the original author of v1 of these patches.
> Heather and myself co-wrote v2.
Hey you all,
this sounds very promising! I have some high level questions:
Could you please add some documentation on the thread safety guarantees when
elfutils was compiled with `--enable-thread-safety`? For my purposes in
maintaining profilers (heaptrack, hotspot), it would be extremely cool if we
could eventually use multiple threads to analyze separate samples. In theory,
I would hope that "write" operations (such as `dwfl_report_{begin,end,elf}`
will require synchronization, but subsequent "read" operations (such as those
needed for symbolication
(`dwfl_{addrmodule,module_getsymtab,module_getsym_info,module_nextcu,module_info,module_address_section,
get_debuginfod_client,...`,
`dwarf_{tag,getscopes_die,formstring,fromudata,diename,getsrc_die,dieoffset,linesrc,lineno,getsrcfiles,attr_integrate,...`)
or unwinding (`dwfl_{thread_state_registers,frame_pc,getthread_frames}) could
happen in parallel. Is that the case already after this patch set?
Generally it seems like the documentation could see some love in better
explaining this feature.
How can I query at runtime whether elfutils was compiled with thread safety
guarantees or not, such that I can adapt my consumer side accordingly (i.e.
enable multi-threading or not)?
Cheers
--
Milian Wolff
m...@milianw.de
http://milianw.de
signature.asc
Description: This is a digitally signed message part.
Re: [PATCH 0/9 v2] Fix thread-safety for elfutils
Hi Milian,
On Thu, Jul 18, 2024 at 6:14 AM Milian Wolff wrote:
>
> On Donnerstag, 18. Juli 2024 00:33:59 MESZ Aaron Merey wrote:
> > v1 can be found at
> > https://sourceware.org/pipermail/elfutils-devel/2023q3/006329.html
> >
> > Heather McIntyre is the original author of v1 of these patches.
> > Heather and myself co-wrote v2.
>
> Hey you all,
>
> this sounds very promising! I have some high level questions:
>
> Could you please add some documentation on the thread safety guarantees when
> elfutils was compiled with `--enable-thread-safety`?
This is definitely needed. I've been working on adding man pages for
elfutils public library functions. We should indicate whether each
function is MT-Safe. We should also have man pages for libelf, libdw,
etc, themselves and these should include thread safety information and
constraints. I will prioritize this.
> For my purposes in
> maintaining profilers (heaptrack, hotspot), it would be extremely cool if we
> could eventually use multiple threads to analyze separate samples. In theory,
> I would hope that "write" operations (such as `dwfl_report_{begin,end,elf}`
> will require synchronization, but subsequent "read" operations (such as those
> needed for symbolication
> (`dwfl_{addrmodule,module_getsymtab,module_getsym_info,module_nextcu,module_info,module_address_section,
> get_debuginfod_client,...`,
> `dwarf_{tag,getscopes_die,formstring,fromudata,diename,getsrc_die,dieoffset,linesrc,lineno,getsrcfiles,attr_integrate,...`)
> or unwinding (`dwfl_{thread_state_registers,frame_pc,getthread_frames}) could
> happen in parallel. Is that the case already after this patch set?
This patch set is not entirely comprehensive. It focuses on thread safety
in libelf and libdw (not libdwfl) and there is still at least one data race
in libelf (see https://sourceware.org/bugzilla/show_bug.cgi?id=31967).
However what you describe should be possible when this feature is more
fully implemented.
In the v1 of this patch set there is a patch which removed the
"experimental" notice from the --enable-thread-safety configure option.
I left this patch in v2 but I think that we should defer that patch and
instead keep thread safety "experimental" until it is more fully tested
and production ready.
> Generally it seems like the documentation could see some love in better
> explaining this feature.
>
> How can I query at runtime whether elfutils was compiled with thread safety
> guarantees or not, such that I can adapt my consumer side accordingly (i.e.
> enable multi-threading or not)?
libelf is compiled with pthread only when elfutils is built with
the --enable-thread-safety configure option. So ATM I believe that
checking the libelf binary for pthread_rwlock_* symbols with
{eu-}readelf or another tool is your best option.
I should also mention that libdw is built with pthread unconditionally,
whether or not --enable-thread-safety is given. However libelf and
libdw should always be installed and upgraded in lockstep, so if
libelf contains pthread_rwlock_* symbols then it's reasonable to
assume that libdw was also built with --enable-thread-safety.
However this is not ideal. Maybe we should add some way to verify
thread safety to the public library API.
Aaron
Re: [PATCH v2] backends: allocate enough stace for null terminator
Hi Sergei, On Wed, 2024-07-17 at 23:03 +0100, Sergei Trofimovich wrote: > `gcc-15` added a new warning in https://gcc.gnu.org/PR115185: > > i386_regs.c:88:11: error: initializer-string for array of 'char' is too > long [-Werror=unterminated-string-initialization] >88 | "ax", "cx", "dx", "bx", "sp", "bp", "si", "di", "ip" > | ^~~~ > > `elfutils` does not need to store '\0'. We could either initialize the > arrays with individual bytes or allocate extra byte for null. > > This change initializes the array bytewise. > > * backends/i386_regs.c (i386_register_info): Initialize the > array bytewise to fix gcc-15 warning. > * backends/x86_64_regs.c (x86_64_register_info): Ditto. This looks good. I have pushed it to main. Will this warning be enabled by -Wall or -Wextra (both of which are enabled by default for elfutils builds)? Or would be need to enable it explicitly? Thanks, Mark
Re: [PATCH 1/9 v2] libelf: Fix deadlock in __libelf_readall
On Wed, 2024-07-17 at 18:34 -0400, Aaron Merey wrote:
> From: Heather McIntyre
>
> Apply locking during __libelf_readall.
>
> Signed-off-by: Heather S. McIntyre
> Signed-off-by: Aaron Merey
> Signed-off-by: Mark Wielaard
>
> ---
> v2 changes:
>
> Add locking for all early returns in __libelf_readall.
>
> libelf_{acquire,release}_all have been renamed to
> libelf_{acquire,release}_all_children. These functions also no longer
> acquire/release the parent's lock. This is done in order to simplify
> lock management in __libelf_readall.
OK, so now we have __libelf_readall take the lock on the Elf handle at
the start. If there is a bad fildes we immediately unlock and return.
If we don't have read everything yet (checking map_address) we call
libelf_acquire_all_children. Every (error) path ends up at the end of
the lexical block where we call libelf_release_all_children. Then we
call rwlock_unlock and return.
So assuming libelf_acquire_all_children/libelf_release_all_children do
as promised, this looks fine.
A comment (about a comment) below. And a nitpick about the locking
order of the (recursive) children.
> libelf/common.h | 16
> libelf/elf_readall.c | 4 ++--
> 2 files changed, 10 insertions(+), 10 deletions(-)
>
> diff --git a/libelf/common.h b/libelf/common.h
> index 9b2a856d..b7226ee8 100644
> --- a/libelf/common.h
> +++ b/libelf/common.h
> @@ -92,10 +92,8 @@ allocate_elf (int fildes, void *map_address, int64_t
> offset, size_t maxsize,
> /* Acquire lock for the descriptor and all children. */
This ^ comment is outdated now. It should say something like:
/* Caller must hold a lock for the descriptor. If there are
children a lock will be acquired for each of them
(recursively). */
> static void
> __attribute__ ((unused))
> -libelf_acquire_all (Elf *elf)
> +libelf_acquire_all_children (Elf *elf)
> {
> - rwlock_wrlock (elf->lock);
> -
>if (elf->kind == ELF_K_AR)
> {
>Elf *child = elf->state.ar.children;
> @@ -103,7 +101,9 @@ libelf_acquire_all (Elf *elf)
>while (child != NULL)
> {
> if (child->ref_count != 0)
> - libelf_acquire_all (child);
> + libelf_acquire_all_children (child);
> +
> + rwlock_wrlock(child->lock);
So, if my suggestion for the function comment is correct, this should
first call rwlock_wrlock (child->lock) and then
libelf_acquire_all_children (child).
> child = child->next;
> }
> }
> @@ -112,7 +112,7 @@ libelf_acquire_all (Elf *elf)
> /* Release own lock and those of the children. */
^ likewise.
> static void
> __attribute__ ((unused))
> -libelf_release_all (Elf *elf)
> +libelf_release_all_children (Elf *elf)
> {
>if (elf->kind == ELF_K_AR)
> {
> @@ -121,12 +121,12 @@ libelf_release_all (Elf *elf)
>while (child != NULL)
> {
> if (child->ref_count != 0)
> - libelf_release_all (child);
> + libelf_release_all_children (child);
> +
> + rwlock_unlock (child->lock);
> child = child->next;
Here the sequence seems correct, first release the locks on all
children, then release the lock on the child descriptor itself.
I don't think this can actually lead to deadlock because the top-level
Elf descriptor lock is held and I don't think children can be held by
two different top-level Elf handles. But it feels better to acquire the
locks in the prescribed order (and unlock in the reverse).
> }
> }
> -
> - rwlock_unlock (elf->lock);
> }
>
>
> diff --git a/libelf/elf_readall.c b/libelf/elf_readall.c
> index d0f9a28c..4ef8fe97 100644
> --- a/libelf/elf_readall.c
> +++ b/libelf/elf_readall.c
> @@ -84,7 +84,7 @@ __libelf_readall (Elf *elf)
>
>/* If this is an archive and we have derived descriptors get the
>locks for all of them. */
> - libelf_acquire_all (elf);
> + libelf_acquire_all_children (elf);
>
>if (elf->maximum_size == ~((size_t) 0))
> {
> @@ -141,7 +141,7 @@ __libelf_readall (Elf *elf)
> __libelf_seterrno (ELF_E_NOMEM);
>
>/* Free the locks on the children. */
> - libelf_release_all (elf);
> + libelf_release_all_children (elf);
> }
>
>rwlock_unlock (elf->lock);
Re: [PATCH 2/9 v2] libelf: Fix deadlock in elf_cntl
Hi,
On Wed, 2024-07-17 at 18:34 -0400, Aaron Merey wrote:
> From: Heather McIntyre
>
> * libelf/elf_cntl.c (elf_cntl): Move rwlock_wrlock, rwlock_unlock,
> inside case switch statements.
>
> Signed-off-by: Heather S. McIntyre
> Signed-off-by: Aaron Merey
> Signed-off-by: Mark Wielaard
>
> ---
> v2 changes:
> Remove unnecessary locking and checking of elf->map_address
>
> libelf/elf_cntl.c | 7 +++
> 1 file changed, 3 insertions(+), 4 deletions(-)
>
> diff --git a/libelf/elf_cntl.c b/libelf/elf_cntl.c
> index 04aa9132..3fbc7d97 100644
> --- a/libelf/elf_cntl.c
> +++ b/libelf/elf_cntl.c
> @@ -48,13 +48,12 @@ elf_cntl (Elf *elf, Elf_Cmd cmd)
>return -1;
> }
>
Out of view of this patch, but in the line before this code does:
if (elf->fildes == -1)
{
__libelf_seterrno (ELF_E_INVALID_HANDLE);
return -1;
}
Below we are careful to take a lock (in __libelf_readall or explicitly
in the case of ELF_C_FDDONE, before reading or writing fildes.
So we either have to add a lock around this check too. Or maybe better
just remove this check. In the case of ELF_C_FDREAD __libelf_readall
will return NULL and so already produce an error. In the case of
ELF_C_FDDONE I would make the point that it doesn't matter, if the
fildes was already -1, then it still is. No need for error in that
case?
>
> - rwlock_wrlock (elf->lock);
>
>switch (cmd)
> {
> case ELF_C_FDREAD:
>/* If not all of the file is in the memory read it now. */
> - if (elf->map_address == NULL && __libelf_readall (elf) == NULL)
> + if (__libelf_readall (elf) == NULL)
This looks good, __libelf_readall (elf) already does that check (after
locking).
> {
> /* We were not able to read everything. */
> result = -1;
> @@ -64,7 +63,9 @@ elf_cntl (Elf *elf, Elf_Cmd cmd)
>
> case ELF_C_FDDONE:
>/* Mark the file descriptor as not usable. */
> + rwlock_wrlock (elf->lock);
>elf->fildes = -1;
> + rwlock_unlock (elf->lock);
>break;
>
> default:
This also looks correct.
Cheers,
Mark
Re: [PATCH 0/9 v2] Fix thread-safety for elfutils
On Donnerstag, 18. Juli 2024 17:56:39 MESZ Aaron Merey wrote:
> Hi Milian,
>
> On Thu, Jul 18, 2024 at 6:14 AM Milian Wolff wrote:
> > On Donnerstag, 18. Juli 2024 00:33:59 MESZ Aaron Merey wrote:
> > > v1 can be found at
> > > https://sourceware.org/pipermail/elfutils-devel/2023q3/006329.html
> > >
> > > Heather McIntyre is the original author of v1 of these patches.
> > > Heather and myself co-wrote v2.
> >
> > Hey you all,
> >
> > this sounds very promising! I have some high level questions:
> >
> > Could you please add some documentation on the thread safety guarantees
> > when elfutils was compiled with `--enable-thread-safety`?
>
> This is definitely needed. I've been working on adding man pages for
> elfutils public library functions. We should indicate whether each
> function is MT-Safe. We should also have man pages for libelf, libdw,
> etc, themselves and these should include thread safety information and
> constraints. I will prioritize this.
>
> > For my purposes in
> > maintaining profilers (heaptrack, hotspot), it would be extremely cool if
> > we could eventually use multiple threads to analyze separate samples. In
> > theory, I would hope that "write" operations (such as
> > `dwfl_report_{begin,end,elf}` will require synchronization, but
> > subsequent "read" operations (such as those needed for symbolication
> > (`dwfl_{addrmodule,module_getsymtab,module_getsym_info,module_nextcu,modul
> > e_info,module_address_section, get_debuginfod_client,...`,
> > `dwarf_{tag,getscopes_die,formstring,fromudata,diename,getsrc_die,dieoffse
> > t,linesrc,lineno,getsrcfiles,attr_integrate,...`) or unwinding
> > (`dwfl_{thread_state_registers,frame_pc,getthread_frames}) could happen
> > in parallel. Is that the case already after this patch set?
>
> This patch set is not entirely comprehensive. It focuses on thread safety
> in libelf and libdw (not libdwfl) and there is still at least one data race
> in libelf (see https://sourceware.org/bugzilla/show_bug.cgi?id=31967).
> However what you describe should be possible when this feature is more
> fully implemented.
>
> In the v1 of this patch set there is a patch which removed the
> "experimental" notice from the --enable-thread-safety configure option.
> I left this patch in v2 but I think that we should defer that patch and
> instead keep thread safety "experimental" until it is more fully tested
> and production ready.
OK, good to know. If you are looking for feedback once this is further along
and includes libdwfl, then I'm more than happy to play around with it. But I
guess I'll have to wait until libdwfl is thread safe to some degree.
> > Generally it seems like the documentation could see some love in better
> > explaining this feature.
> >
> > How can I query at runtime whether elfutils was compiled with thread
> > safety
> > guarantees or not, such that I can adapt my consumer side accordingly
> > (i.e.
> > enable multi-threading or not)?
>
> libelf is compiled with pthread only when elfutils is built with
> the --enable-thread-safety configure option. So ATM I believe that
> checking the libelf binary for pthread_rwlock_* symbols with
> {eu-}readelf or another tool is your best option.
>
> I should also mention that libdw is built with pthread unconditionally,
> whether or not --enable-thread-safety is given. However libelf and
> libdw should always be installed and upgraded in lockstep, so if
> libelf contains pthread_rwlock_* symbols then it's reasonable to
> assume that libdw was also built with --enable-thread-safety.
>
> However this is not ideal. Maybe we should add some way to verify
> thread safety to the public library API.
Yes please. Looking up `pthread_rwlock_*` symbols in a lib linking against
libdw just to figure out if things are threadsafe or not is super brittle.
Please add an explicit API that forwards the `--enable-thread-safety` compile
time flag such that we can query it at runtime.
thanks
--
Milian Wolff
m...@milianw.de
http://milianw.de
signature.asc
Description: This is a digitally signed message part.
Re: [PATCH 4/9 v2] libdw: make dwarf_getalt thread-safe
Hi,
On Wed, Jul 17, 2024 at 06:34:03PM -0400, Aaron Merey wrote:
> From: Heather McIntyre
>
> * libdw/dwarf_getalt.c (dwarf_getalt): Add locking.
>
> Signed-off-by: Heather S. McIntyre
> Signed-off-by: Aaron Merey
> Signed-off-by: Mark Wielaard
>
> v2 changes:
>
> Write lock now applies to all of dwarf_getalt.
This looks good, but two nitpicks.
> ---
> libdw/dwarf_getalt.c | 18 --
> 1 file changed, 16 insertions(+), 2 deletions(-)
>
> diff --git a/libdw/dwarf_getalt.c b/libdw/dwarf_getalt.c
> index 0a12dfae..3b827d0b 100644
> --- a/libdw/dwarf_getalt.c
> +++ b/libdw/dwarf_getalt.c
> @@ -160,15 +160,27 @@ find_debug_altlink (Dwarf *dbg)
> }
> }
>
> +/* find_debug_altlink() modifies "dbg->alt_dwarf".
> + dwarf_getalt() reads "main->alt_dwarf".
> + Mutual exclusion is enforced to prevent a race. */
> +
> Dwarf *
> dwarf_getalt (Dwarf *main)
> {
> + rwlock_wrlock(main->dwarf_lock);
> +
>/* Only try once. */
>if (main == NULL || main->alt_dwarf == (void *) -1)
> -return NULL;
> +{
> + rwlock_unlock (main->dwarf_lock);
> + return NULL;
> +}
The main == NULL check has to be done before taking the lock since
that would cause an SEGV otherwise.
The return on NULL input (without setting error) is a common pattern
in libdw, it allows to "chain" calls where some might fail (set error)
and return NULL. The chained call then also returns NULL (and you get
the original error).
>if (main->alt_dwarf != NULL)
> -return main->alt_dwarf;
> +{
> + rwlock_unlock (main->dwarf_lock);
> + return main->alt_dwarf;
> +}
>
>find_debug_altlink (main);
>
> @@ -176,9 +188,11 @@ dwarf_getalt (Dwarf *main)
>if (main->alt_dwarf == NULL)
> {
>main->alt_dwarf = (void *) -1;
> + rwlock_unlock (main->dwarf_lock);
>return NULL;
> }
>
> + rwlock_unlock (main->dwarf_lock);
>return main->alt_dwarf;
> }
In both these unlock and return main->alt_dwarf I think this is fine
in practice, since they are done after the final write to
alt_dwarf. But to make absolutely sure we don't read/write to variable
we should only access under a lock I like the pattern of defining a
Dwarf *result; assign result = main->alt_dwarf before dropping the
lock, then return result. Call me paranoid :)
Cheers,
Mark
Re: [PATCH 5/9 v2] libdwP.h: Add locking to __libdw_dieabbrev,
Hi,
On Wed, Jul 17, 2024 at 06:34:04PM -0400, Aaron Merey wrote:
> From: Heather McIntyre
>
> Signed-off-by: Heather S. McIntyre
> Signed-off-by: Aaron Merey
> Signed-off-by: Mark Wielaard
>
> ---
>
> v2 changes:
> This replaces patch "libdw: Add locking around __libdw_dieabbrev for
> dwarf_hasattr". Mark suggested that we remove lazy abbrev reading
> in order to simplify the locking of __libdw_dieabbrev. This is
> a fair bit of work so for now lets just put a write lock around all
> of __libdw_dieabbrev. The removal of lazy reading of abbrev will be
> done in a future patch.
I have to think a bit about this. It sounds expensive to have to wrap
each abbrev read in a lock.
> diff --git a/libdw/dwarf_setalt.c b/libdw/dwarf_setalt.c
> index dc9b61cb..f7d70d9d 100644
> --- a/libdw/dwarf_setalt.c
> +++ b/libdw/dwarf_setalt.c
> @@ -35,6 +35,8 @@
> void
> dwarf_setalt (Dwarf *main, Dwarf *alt)
> {
> + rwlock_wrlock(main->dwarf_lock);
> +
>if (main->alt_fd != -1)
> {
>INTUSE(dwarf_end) (main->alt_dwarf);
> @@ -43,5 +45,7 @@ dwarf_setalt (Dwarf *main, Dwarf *alt)
> }
>
>main->alt_dwarf = alt;
> +
> + rwlock_unlock(main->dwarf_lock);
> }
> INTDEF (dwarf_setalt)
This part should go with the previous patch "libdw: make dwarf_getalt
thread-safe".
Cheers,
Mark
Re: [PATCH 6/9 v2] libdw: Make libdw_find_split_unit thread-safe
Hi,
On Wed, Jul 17, 2024 at 06:34:05PM -0400, Aaron Merey wrote:
> From: Heather McIntyre
>
> * (__libdw_find_split_unit): Add lock for cu->split.
>
> Signed-off-by: Heather S. McIntyre
> Signed-off-by: Aaron Merey
> Signed-off-by: Mark Wielaard
>
> ---
>
> v2 changes:
> Locking applied to __libdw_find_split_unit instead of try_split_file.
>
> libdw/libdw_find_split_unit.c | 8 +++-
> 1 file changed, 7 insertions(+), 1 deletion(-)
Would be nice to have the split_lock definition from patch "lib: Add
eu_tsearch, eu_tfind, eu_tdelete and eu_tdestroy " here to make this
patch self-contained.
> diff --git a/libdw/libdw_find_split_unit.c b/libdw/libdw_find_split_unit.c
> index 67d31a9c..eb3d88d7 100644
> --- a/libdw/libdw_find_split_unit.c
> +++ b/libdw/libdw_find_split_unit.c
> @@ -150,9 +150,14 @@ Dwarf_CU *
> internal_function
> __libdw_find_split_unit (Dwarf_CU *cu)
> {
> + rwlock_wrlock(cu->split_lock);
> +
>/* Only try once. */
>if (cu->split != (Dwarf_CU *) -1)
> -return cu->split;
> +{
> + rwlock_unlock(cu->split_lock);
> + return cu->split;
> +}
>
>/* We need a skeleton unit with a comp_dir and [GNU_]dwo_name attributes.
> The split unit will be the first in the dwo file and should have the
> @@ -207,5 +212,6 @@ __libdw_find_split_unit (Dwarf_CU *cu)
>if (cu->split == (Dwarf_CU *) -1)
> cu->split = NULL;
>
> + rwlock_unlock(cu->split_lock);
>return cu->split;
> }
Again, just as a style issue, because it looks like the unlocked read
is fine in this case, but I really like the Dwarf_CU *result; result =
cu->split; unlock; return result; idiom here.
Cheers,
Mark
Re: [PATCH v2] backends: allocate enough stace for null terminator
On Thu, 18 Jul 2024 18:49:54 +0200 Mark Wielaard wrote: > Hi Sergei, > > On Wed, 2024-07-17 at 23:03 +0100, Sergei Trofimovich wrote: > > `gcc-15` added a new warning in https://gcc.gnu.org/PR115185: > > > > i386_regs.c:88:11: error: initializer-string for array of 'char' is too > > long [-Werror=unterminated-string-initialization] > >88 | "ax", "cx", "dx", "bx", "sp", "bp", "si", "di", "ip" > > | ^~~~ > > > > `elfutils` does not need to store '\0'. We could either initialize the > > arrays with individual bytes or allocate extra byte for null. > > > > This change initializes the array bytewise. > > > > * backends/i386_regs.c (i386_register_info): Initialize the > > array bytewise to fix gcc-15 warning. > > * backends/x86_64_regs.c (x86_64_register_info): Ditto. > > This looks good. I have pushed it to main. > > Will this warning be enabled by -Wall or -Wextra (both of which are > enabled by default for elfutils builds)? Or would be need to enable it > explicitly? Thank you! It's enabled only with `-Wextra` (and that's how I encountered on build failure in `elfutils`). -- Sergei
[PATCH] Add man pages for some libelf functions
Add man pages for elf32_offscn.3, elf64_offscn.3, elf_getscn.3 and
elf_ndxscn.3.
Signed-off-by: Aaron Merey
---
doc/elf32_offscn.3 | 61 +
doc/elf64_offscn.3 | 62 ++
doc/elf_getscn.3 | 55
doc/elf_ndxscn.3 | 52 ++
4 files changed, 230 insertions(+)
create mode 100644 doc/elf32_offscn.3
create mode 100644 doc/elf64_offscn.3
create mode 100644 doc/elf_getscn.3
create mode 100644 doc/elf_ndxscn.3
diff --git a/doc/elf32_offscn.3 b/doc/elf32_offscn.3
new file mode 100644
index ..5d4a657f
--- /dev/null
+++ b/doc/elf32_offscn.3
@@ -0,0 +1,61 @@
+.TH ELF32_OFFSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf32_offscn \- retrieve a section descriptor by file offset for a 32-bit ELF
file
+
+.SH SYNOPSIS
+.B #include
+
+.BI "Elf_Scn *elf32_offscn(Elf *" elf ", off_t " offset ");"
+
+.SH DESCRIPTION
+The
+.B elf32_offscn
+function retrieves the section descriptor for the section at the specified
file offset in the ELF32 object referred to by
+.I elf.
+
+.SH PARAMETERS
+.TP
+.I elf
+An
+.I Elf pointer to the ELF object from which the section descriptor is to be
retrieved.
+
+.TP
+.I offset
+An
+.I off_t
+value representing the file offset of the section whose descriptor is to be
retrieved.
+
+.SH RETURN VALUE
+The
+.B elf32_offscn
+function returns a pointer to the
+.I Elf_Scn
+for the section at the specified offset. If an error occurs, it returns NULL
and sets an appropriate libelf error code.
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf32_offscn ()
+T} Thread safety MT-Safe
+.TE
+
+.SH SEE ALSO
+.BR elf64_offscn (3),
+.BR libelf (3),
+.BR elf (5),
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf32_offscn
+first appeared in elfutils 0.112.
diff --git a/doc/elf64_offscn.3 b/doc/elf64_offscn.3
new file mode 100644
index ..4ab29b30
--- /dev/null
+++ b/doc/elf64_offscn.3
@@ -0,0 +1,62 @@
+.TH ELF64_OFFSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf64_offscn \- retrieve a section descriptor by file offset for a 64-bit ELF
file
+
+.SH SYNOPSIS
+.B #include
+
+.BI "Elf_Scn *elf64_offscn(Elf *" elf ", off_t " offset ");"
+
+.SH DESCRIPTION
+The
+.B elf64_offscn
+function retrieves the section descriptor for the section at the specified
file offset in the ELF64 object referred to by
+.I elf.
+
+.SH PARAMETERS
+.TP
+.I elf
+An
+.I Elf
+pointer to the ELF object from which the section descriptor is to be retrieved.
+
+.TP
+.I offset
+An
+.I off_t
+value representing the file offset of the section whose descriptor is to be
retrieved.
+
+.SH RETURN VALUE
+The
+.B elf64_offscn
+function returns a pointer to the
+.I Elf_Scn
+for the section at the specified offset. If an error occurs, it returns NULL
and sets an appropriate libelf error code.
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf64_offscn ()
+T} Thread safety MT-Safe
+.TE
+
+.SH SEE ALSO
+.BR elf32_offscn (3),
+.BR libelf (3),
+.BR elf (5),
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf64_offscn
+first appeared in elfutils 0.112.
diff --git a/doc/elf_getscn.3 b/doc/elf_getscn.3
new file mode 100644
index ..1be13369
--- /dev/null
+++ b/doc/elf_getscn.3
@@ -0,0 +1,55 @@
+.TH ELF_GETSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_getscn \- retrieve a descriptor for an ELF section at a specified index.
+
+.SH SYNOPSIS
+.B #include
+
+.BI "Elf_Scn *elf_getscn(Elf *" elf ", size_t " index ");"
+
+.SH DESCRIPTION
+The .B elf_getscn function retrieves a section descriptor for the section at
the specified index in the ELF object referred to by .I elf.
+
+.SH PARAMETERS
+.TP
+.I elf
+An
+.I Elf
+pointer to the ELF object from which the section descriptor is to be retrieved.
+
+.TP
+.I index
+A
+.I size_t
+value representing the index of the section whose descriptor is to be
retrieved. Section indices start at 0.
+
+.SH RETURN VALUE
+The
+.B elf_getscn
+function returns a pointer to the
+.I Elf_Scn
+for the section at the specified index. If an error occurs, it returns NULL
and sets an appropriate libelf error code.
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_getscn ()
+T} Thread safety MT-Safe
+.TE
+
+.SH SEE ALSO
+.BR elf_errno (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
diff --git
[PATCH] Add man pages for some libelf functions
Add man pages for elf32_offscn.3, elf64_offscn.3, elf_getscn.3 and
elf_ndxscn.3.
Signed-off-by: Aaron Merey
---
Reposting this patch with the new man pages added to doc/Makefile.am.
doc/Makefile.am| 6 -
doc/elf32_offscn.3 | 61 +
doc/elf64_offscn.3 | 62 ++
doc/elf_getscn.3 | 55
doc/elf_ndxscn.3 | 52 ++
5 files changed, 235 insertions(+), 1 deletion(-)
create mode 100644 doc/elf32_offscn.3
create mode 100644 doc/elf64_offscn.3
create mode 100644 doc/elf_getscn.3
create mode 100644 doc/elf_ndxscn.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index db8526fc..86c1d82d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -35,7 +35,11 @@ notrans_dist_man3_MANS= elf_update.3 \
elf64_getehdr.3 \
elf_errmsg.3 \
elf_errno.3 \
- elf_version.3
+ elf_version.3 \
+ elf32_offscn.3 \
+ elf64_offscn.3 \
+ elf_getscn.3 \
+ elf_ndxscn.3
# libdebuginfod man pages (also notrans)
# Note we include them even when not building them because we want
diff --git a/doc/elf32_offscn.3 b/doc/elf32_offscn.3
new file mode 100644
index ..5d4a657f
--- /dev/null
+++ b/doc/elf32_offscn.3
@@ -0,0 +1,61 @@
+.TH ELF32_OFFSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf32_offscn \- retrieve a section descriptor by file offset for a 32-bit ELF
file
+
+.SH SYNOPSIS
+.B #include
+
+.BI "Elf_Scn *elf32_offscn(Elf *" elf ", off_t " offset ");"
+
+.SH DESCRIPTION
+The
+.B elf32_offscn
+function retrieves the section descriptor for the section at the specified
file offset in the ELF32 object referred to by
+.I elf.
+
+.SH PARAMETERS
+.TP
+.I elf
+An
+.I Elf pointer to the ELF object from which the section descriptor is to be
retrieved.
+
+.TP
+.I offset
+An
+.I off_t
+value representing the file offset of the section whose descriptor is to be
retrieved.
+
+.SH RETURN VALUE
+The
+.B elf32_offscn
+function returns a pointer to the
+.I Elf_Scn
+for the section at the specified offset. If an error occurs, it returns NULL
and sets an appropriate libelf error code.
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf32_offscn ()
+T} Thread safety MT-Safe
+.TE
+
+.SH SEE ALSO
+.BR elf64_offscn (3),
+.BR libelf (3),
+.BR elf (5),
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf32_offscn
+first appeared in elfutils 0.112.
diff --git a/doc/elf64_offscn.3 b/doc/elf64_offscn.3
new file mode 100644
index ..4ab29b30
--- /dev/null
+++ b/doc/elf64_offscn.3
@@ -0,0 +1,62 @@
+.TH ELF64_OFFSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf64_offscn \- retrieve a section descriptor by file offset for a 64-bit ELF
file
+
+.SH SYNOPSIS
+.B #include
+
+.BI "Elf_Scn *elf64_offscn(Elf *" elf ", off_t " offset ");"
+
+.SH DESCRIPTION
+The
+.B elf64_offscn
+function retrieves the section descriptor for the section at the specified
file offset in the ELF64 object referred to by
+.I elf.
+
+.SH PARAMETERS
+.TP
+.I elf
+An
+.I Elf
+pointer to the ELF object from which the section descriptor is to be retrieved.
+
+.TP
+.I offset
+An
+.I off_t
+value representing the file offset of the section whose descriptor is to be
retrieved.
+
+.SH RETURN VALUE
+The
+.B elf64_offscn
+function returns a pointer to the
+.I Elf_Scn
+for the section at the specified offset. If an error occurs, it returns NULL
and sets an appropriate libelf error code.
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf64_offscn ()
+T} Thread safety MT-Safe
+.TE
+
+.SH SEE ALSO
+.BR elf32_offscn (3),
+.BR libelf (3),
+.BR elf (5),
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf64_offscn
+first appeared in elfutils 0.112.
diff --git a/doc/elf_getscn.3 b/doc/elf_getscn.3
new file mode 100644
index ..1be13369
--- /dev/null
+++ b/doc/elf_getscn.3
@@ -0,0 +1,55 @@
+.TH ELF_GETSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_getscn \- retrieve a descriptor for an ELF section at a specified index.
+
+.SH SYNOPSIS
+.B #include
+
+.BI "Elf_Scn *elf_getscn(Elf *" elf ", size_t " index ");"
+
+.SH DESCRIPTION
+The .B elf_getscn function retrieves a section descriptor for the section at
the specified index in the ELF object referred to by .I elf.
+
+.SH PARAMETERS
+.TP
+.I elf
+An
+.I Elf
+pointer to the ELF object from which the section descrip
