Hi Aaron,
On Mon, Aug 04, 2025 at 11:24:39PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> v2: Describe default field values of Elf_Data returned by elf_newdata.
> Minor rewording changes
>
> doc/Makefile.am | 1 +
> doc/elf_newdata.3 | 92 +++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 93 insertions(+)
> create mode 100644 doc/elf_newdata.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 7157fc6d..217c2da1 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -80,6 +80,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_kind.3 \
> elf_memory.3 \
> elf_ndxscn.3 \
> + elf_newdata.3 \
> elf_nextscn.3 \
> elf_rawfile.3 \
> elf_scnshndx.3 \
OK.
> diff --git a/doc/elf_newdata.3 b/doc/elf_newdata.3
> new file mode 100644
> index 00000000..0522bc15
> --- /dev/null
> +++ b/doc/elf_newdata.3
> @@ -0,0 +1,92 @@
> +.TH ELF_NEWDATA 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_newdata \- Add a new Elf_Data descriptor to a section
> +
> +.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 and associates it 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). If the section has
> +no data associated with it yet, or was created using
> +.BR elf_newscn (),
> +this function creates the first
> +.BR Elf_Data
> +descriptor for the section.
> +
> +Subsequent calls to
> +.BR elf_newdata ()
> +will append new data descriptors to the section.
> +
> +The returned descriptor is marked dirty so that it will be included during
> +.BR elf_update () .
> +The returned descriptor is also initialized to represent no data with
> +.I d_buf
> +set to NULL,
> +.I d_type
> +set to
> +.BR ELF_T_BYTE ,
> +.I d_version
> +set to
> +.BR EV_CURRENT ,
> +and
> +.IR d_size ,
> +.IR d_off ,
> +and
> +.IR d_align
> +set to zero.
OK.
> +.SH PARAMETERS
> +.TP
> +.I scn
> +A section descriptor to which the new data descriptor should be attached.
> +Must not be section zero, the null section. If
> +.I scn
> +is NULL this function returns NULL.
OK.
> +.SH RETURN VALUE
> +On success, a pointer to a new, writable
> +.BR Elf_Data
> +descriptor is returned. On failure, NULL is returned an elf_errno is set.
> +If
> +.I scn
> +is NULL, then NULL is returned and elf_errno is not set.
> +
> +The caller is responsible for configuring the return value (see DESCRIPTION
> +for default field values).
OK.
> +.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.
Thanks,
Mark
