Hi Aaron,
On Tue, 2025-04-01 at 00:04 -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> doc/Makefile.am | 3 ++-
> doc/elf_end.3 | 71 +++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 73 insertions(+), 1 deletion(-)
> create mode 100644 doc/elf_end.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index c95369e9..36f1855f 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -58,7 +58,8 @@ notrans_dist_man3_MANS= elf_update.3 \
> elf64_fsize.3 \
> elf32_checksum.3 \
> elf64_checksum.3 \
> - libelf.3
> + libelf.3 \
> + elf_end
Don't do this for this patch, but for a separate patch. Currently this
list seems kind of random. Would be good to have this sorted
alphabetically (or some other way that makes it easier to see which man
pages there are where missing ones could be inserted).
> # libdebuginfod man pages (also notrans)
> # Note we include them even when not building them because we want
> diff --git a/doc/elf_end.3 b/doc/elf_end.3
> new file mode 100644
> index 00000000..9eb3dcb8
> --- /dev/null
> +++ b/doc/elf_end.3
> @@ -0,0 +1,71 @@
> +.TH ELF_END 3 2025-03-31 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_end \- Release resources associated with an ELF descriptor.
> +
> +.SH SYNOPSIS
> +.nf
> +#include <libelf.h>
> +
> +.BI "int elf_end(Elf *" elf ");"
> +
> +.SH DESCRIPTION
> +The
> +.B elf_end
> +function releases resources associated with an ELF descriptor previously
> +returned by
> +.BR elf_begin .
> +It decrements the ELF descriptor’s internal reference count by one. When
> +this count reaches zero, the resources associated with the descriptor are
> +freed and the descriptor is invalidated. If
> +.I elf
> +is not an archive member with ELF kind
> +.BR ELF_K_AR ,
> +the internal reference count is increased by one each time
> +.I elf
> +is passed to
> +.B elf_begin
> +as the
> +.I ref
> +argument.
So we do have a tiny elf_begin.3 man page, but it doesn't really
describe anything. The above seems a technically correct description of
ELF descriptor internal reference counting, but I am not sure it makes
sense without a full description of elf_begin.
> +An ELF descriptor whose reference count reaches zero is invalidated.
> +Further operations on the descriptor will result in undefined behavior.
> +
> +.SH PARAMETERS
> +.TP
> +.I elf
> +The ELF descriptor.
Since you mention it below, maybe add (may be NULL)?
> +.SH RETURN VALUE
> +Return the ELF descriptor's current internal reference count after
> +decrementing. A return value of zero indicates the ELF descriptor is now
> +invalidated. If
> +.I elf
> +is NULL, then
> +.B elf_end
> +also returns 0.
Good.
> +.SH SEE ALSO
> +.BR elf_begin (3),
> +.BR libelf (3),
> +.BR elf (5)
Yes, but elf_begin (3) is currently somewhat useless.
> +.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_end ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
> +
Cheers,
Mark
