Hi Aaron,

On Mon, Jun 30, 2025 at 11:12:26PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
>  doc/Makefile.am   |  1 +
>  doc/elf_newdata.3 | 75 +++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 76 insertions(+)
>  create mode 100644 doc/elf_newdata.3
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 98712576..97aac570 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -79,6 +79,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
>                       elf_kind.3 \
>                       elf_memory.3 \
>                       elf_ndxscn.3 \
> +                     elf_newdata.3 \
>                       elf_update.3 \
>                       elf_version.3 \
>                       libelf.3

OK.

> diff --git a/doc/elf_newdata.3 b/doc/elf_newdata.3
> new file mode 100644
> index 00000000..4a8a77ad
> --- /dev/null
> +++ b/doc/elf_newdata.3
> @@ -0,0 +1,75 @@
> +.TH ELF_NEWDATA 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_newdata \- create a new Elf_Data descriptor for a section

Maybe adds a new...?

> +
> +.SH SYNOPSIS
> +.nf
> +#include <libelf.h>
> +
> +.BI "Elf_Data * elf_newdata(Elf_Scn *" scn ");"
> +.fi

OK.

> +.SH DESCRIPTION
> +The
> +.BR elf_newdata ()
> +function creates a new
> +.BR Elf_Data
> +descriptor associated with the section referred to by
> +.I scn .
> +This descriptor can be used to describe new section contents for an ELF 
> object
> +being constructed or modified.
> +
> +The section must not be the null section (index 0), and the section header 
> must
> +already be initialized (for example, by calling
> +.BR elf_getshdr ()
> +after creating the section via
> +.BR elf_newscn ()).

That last requirement surprises me. I don't see it back in the code.

> +If the section has not yet been assigned data, or was created using
> +.BR elf_newscn (),
> +this function creates the first
> +.BR Elf_Data
> +descriptor for the section.

Maybe s/has not yet been assigned data/has no data associated with it yet/ ?

> +Subsequent calls to
> +.BR elf_newdata ()
> +will append new data descriptors to the section.

OK.

> +The returned descriptor is marked dirty so that it will be included during
> +.BR elf_update () .

Maybe add the Elf_Data is initialized to represent no data with d_buf
set to NULL, d_type set to ELF_T_BYTE, d_version set to EV_CURRENT and
d_size, d_off and d_align set to zero.

> +.SH PARAMETERS
> +.TP
> +.I scn
> +A section descriptor to which the new data descriptor should be attached.
> +Must not be the null section.

Must not be section zero. When NULL the function returns NULL.

> +.SH RETURN VALUE
> +On success, a pointer to a new, writable
> +.BR Elf_Data
> +descriptor is returned. On failure, NULL is returned.

and elf_errno will be set. When scn is NULL failure is returned, but
elf_errno isn't (re)set.

> +The caller is responsible for configuring the return value.

Maybe see above for which fields?

> +
> +.SH SEE ALSO
> +.BR elf_getdata (3),
> +.BR elf_newscn (3),
> +.BR elf_update (3),
> +.BR libelf (3),
> +.BR elf (5)

OK.

> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface    Attribute       Value
> +T{
> +.na
> +.nh
> +.BR elf_newdata ()
> +T}   Thread safety   MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or 
> https://sourceware.org/bugzilla/.

OK. Some of the lines are very wide though.

Thanks,

Mark

Reply via email to