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