Hi Aaron,
One small comment below, but this looks good with or without that.
On Sun, Sep 14, 2025 at 07:20:59PM -0400, Aaron Merey wrote:
> v3 changes:
> Fix unbalanced " in SYNOPSIS.
> Reword ELF_F_LAYOUT description and mention that phdr offset changes will
> prevent automatic changes to shdr offset changes during elf_update.
> Mention that ELF_F_PERMISSIVE is an elfutils extention.
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 8d799643..81566664 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -56,6 +56,12 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_errmsg.3 \
> elf_errno.3 \
> elf_fill.3 \
> + elf_flagelf.3 \
> + elf_flagehdr.3 \
> + elf_flagphdr.3 \
> + elf_flagscn.3 \
> + elf_flagdata.3 \
> + elf_flagshdr.3 \
> elf_getarhdr.3 \
> elf_getaroff.3 \
> elf_getarsym.3 \
OK
> diff --git a/doc/elf_flagdata.3 b/doc/elf_flagdata.3
> new file mode 100644
> index 00000000..ee84d431
> --- /dev/null
> +++ b/doc/elf_flagdata.3
> @@ -0,0 +1 @@
> +.so man3/elf_flagelf.3
> diff --git a/doc/elf_flagehdr.3 b/doc/elf_flagehdr.3
> new file mode 100644
> index 00000000..ee84d431
> --- /dev/null
> +++ b/doc/elf_flagehdr.3
> @@ -0,0 +1 @@
> +.so man3/elf_flagelf.3
OK.
> diff --git a/doc/elf_flagelf.3 b/doc/elf_flagelf.3
> new file mode 100644
> index 00000000..0a8482f2
> --- /dev/null
> +++ b/doc/elf_flagelf.3
> @@ -0,0 +1,184 @@
> +.TH ELF_FLAGELF 3 2025-06-23 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_flagelf, elf_flagdata, elf_flagehdr, elf_flagphdr, elf_flagscn,
> elf_flagshdr \- set or clear flags on ELF descriptors and components
> +.SH SYNOPSIS
> +.nf
> +.B #include <libelf.h>
> +
> +.BI "unsigned int elf_flagelf(Elf * " elf ", Elf_Cmd " cmd ", unsigned int "
> flags ");"
> +.BI "unsigned int elf_flagehdr(Elf * " elf ", Elf_Cmd " cmd ", unsigned int
> " flags ");"
> +.BI "unsigned int elf_flagphdr(Elf * " elf ", Elf_Cmd " cmd ", unsigned int
> " flags ");"
> +.BI "unsigned int elf_flagscn(Elf_Scn * " scn ", Elf_Cmd " cmd ", unsigned
> int " flags ");"
> +.BI "unsigned int elf_flagshdr(Elf_Scn * " scn ", Elf_Cmd " cmd ", unsigned
> int " flags ");"
> +.BI "unsigned int elf_flagdata(Elf_Data * " data ", Elf_Cmd " cmd ",
> unsigned int " flags ");"
> +.fi
OK.
> +
> +.SH DESCRIPTION
> +These functions allow the caller to set or clear flags on various ELF
> +components managed by
> +.B libelf .
> +They are typically used to indicate that a component has been modified
> +(dirty), or to control layout behavior during output.
OK.
> +.BR elf_flagelf ()
> +modifies flags on the top-level
> +.B Elf
> +descriptor.
> +
> +.BR elf_flagdata ()
> +modifies flags on an
> +.B Elf_Data
> +descriptor, typically retrieved using
> +.BR elf_getdata (3)
> +or created with
> +.BR elf_newdata (3).
> +
> +.BR elf_flagehdr ()
> +modifies flags on the ELF header for a ELF descriptor (e.g., the result of
> +.BR gelf_getehdr (3)).
> +
> +.BR elf_flagphdr ()
> +modifies flags on the program header table of an ELF descriptor.
> +
> +.BR elf_flagscn ()
> +modifies flags on an
> +.B Elf_Scn
> +(section) descriptor.
> +
> +.BR elf_flagshdr ()
> +modifies flags on the section header of a given
> +.B Elf_Scn .
> +
OK.
> +The
> +.I cmd
> +argument determines whether the given flags should be set (
> +.B ELF_C_SET
> +) or cleared (
> +.B ELF_C_CLR
> +).
OK.
> +The following flag values may be passed via the
> +.I flags
> +parameter:
> +
> +.TP
> +.B ELF_F_DIRTY
> +Marks the object as modified. This ensures changes to the component is
> written
> +out during
> +.BR elf_update (3).
> +
> +.TP
> +.B ELF_F_LAYOUT
> +Indicates that the layout of the ELF component is managed manually. Offsets
> and
> +sizes will be preserved as provided. This flag is only used with
> +.BR elf_flagelf ()
> +and is ignored when used with other functions.
> +If this flag is set the user must set Ehdr
> +.IR e_phoff ,
> +.IR e_shoff ,
> +as well as
> +.B Elf_Data
> +.I d_off
> +and Shdr
> +.IR sh_offset .
> +If not set, then these offsets will be recalculated when
> +.B elf_update
> +is called.
> +If
> +.B ELF_F_LAYOUT
> +is set then changes to phdr offsets will prevent elf_update from
> automatically
> +adjusting shdr offsets.
OK.
> +.TP
> +.B ELF_F_PERMISSIVE
> +Enables relaxed validation of object structure. This flag permits nonstandard
> +layouts without strict checks. Specifically this removes a check in
> +.BR elf_update ()
> +that the section
> +.I sh_size
> +is a multiple of the section
> +.I sh_entsize
> +(if not zero). This flag is only used with
> +.BR elf_flagelf ()
> +and is ignored when used with other functions.
> +.B ELF_F_PERMISSIVE
> +is an elfutils libelf extention and may not be available in other libelf
> +implementations.
OK.
> +.SH PARAMETERS
> +.TP
> +.I obj
> +The object to be modified:
> +For
> +.BR elf_flagelf ,
> +.BR elf_flagehdr ,
> +.BR elf_flagphdr ,
> +this is an
> +.B Elf *
> +descriptor.
> +For
> +.B elf_flagscn
> +and
> +.B elf_flagshdr ,
> +this is an
> +.B Elf_Scn *
> +descriptor.
> +For
> +.B elf_flagdata ,
> +an
> +.B Elf_Data *
> +buffer.
OK.
> +.TP
> +.I cmd
> +Must be either:
> +.B ELF_C_SET
> +to set the given flags, or
> +.B ELF_C_CLR
> +to clear them.
OK.
> +.TP
> +.I flags
> +Bitmask of flags to modify. May include any combination of
> +.B ELF_F_DIRTY ,
> +.B ELF_F_LAYOUT ,
> +and
> +.B ELF_F_PERMISSIVE .
> +
> +Note that
> +.B ELF_F_LAYOUT
> +and
> +.B ELF_F_PERMISSIVE
> +are only used with
> +.BR elf_flagelf ()
> +and are ignored for other functions.
OK.
> +.SH RETURN VALUE
> +Returns the new value of the flags after the set/clear operation.
> +
> +Returns 0 on error, and sets an error code retrievable via
> +.BR elf_errmsg (3).
> +If the first argument is NULL then 0 is return and no error code is set.
I would add that zero is also a valid return valid when clearing the
last flag set. (Which is annoying since it means you cannot really
know if a clear operation resulted in an error...)
> +.SH SEE ALSO
> +.BR elf_errmsg (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_flagelf
> (),\~elf_flagehdr(),\~elf_flagphdr(),\~elf_flagscn(),\~elf_flagshdr(),\~elf_flagdata()
> +T} Thread safety MT-Unsafe race
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <[email protected]> or
> https://sourceware.org/bugzilla/.
OK.
> diff --git a/doc/elf_flagphdr.3 b/doc/elf_flagphdr.3
> new file mode 100644
> index 00000000..ee84d431
> --- /dev/null
> +++ b/doc/elf_flagphdr.3
> @@ -0,0 +1 @@
> +.so man3/elf_flagelf.3
> diff --git a/doc/elf_flagscn.3 b/doc/elf_flagscn.3
> new file mode 100644
> index 00000000..ee84d431
> --- /dev/null
> +++ b/doc/elf_flagscn.3
> @@ -0,0 +1 @@
> +.so man3/elf_flagelf.3
> diff --git a/doc/elf_flagshdr.3 b/doc/elf_flagshdr.3
> new file mode 100644
> index 00000000..ee84d431
> --- /dev/null
> +++ b/doc/elf_flagshdr.3
> @@ -0,0 +1 @@
> +.so man3/elf_flagelf.3
OK.
Thanks,
Mark
