Hi Aaron,
On Mon, Jun 30, 2025 at 11:12:26PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <[email protected]>
> ---
> 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 <[email protected]> or
> https://sourceware.org/bugzilla/.
OK. Some of the lines are very wide though.
Thanks,
Mark
