diff mbox series

[02/16] doc: Add elf_flag*.3

Message ID 20250701031248.1106390-2-amerey@redhat.com
State Superseded
Delegated to: Mark Wielaard
Headers
Series [01/16] doc: Add elf_memory.3 |

Commit Message

Aaron Merey July 1, 2025, 3:12 a.m. UTC 
  Signed-off-by: Aaron Merey <amerey@redhat.com>
---
 doc/Makefile.am    |   6 ++
 doc/elf_flagdata.3 |   1 +
 doc/elf_flagehdr.3 |   1 +
 doc/elf_flagelf.3  | 145 +++++++++++++++++++++++++++++++++++++++++++++
 doc/elf_flagphdr.3 |   1 +
 doc/elf_flagscn.3  |   1 +
 doc/elf_flagshdr.3 |   1 +
 7 files changed, 156 insertions(+)
 create mode 100644 doc/elf_flagdata.3
 create mode 100644 doc/elf_flagehdr.3
 create mode 100644 doc/elf_flagelf.3
 create mode 100644 doc/elf_flagphdr.3
 create mode 100644 doc/elf_flagscn.3
 create mode 100644 doc/elf_flagshdr.3

Comments

Mark Wielaard July 5, 2025, 12:52 a.m. UTC | #1 
Hi Aaron,

On Mon, Jun 30, 2025 at 11:12:19PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <amerey@redhat.com>
> ---
>  doc/Makefile.am    |   6 ++
>  doc/elf_flagdata.3 |   1 +
>  doc/elf_flagehdr.3 |   1 +
>  doc/elf_flagelf.3  | 145 +++++++++++++++++++++++++++++++++++++++++++++
>  doc/elf_flagphdr.3 |   1 +
>  doc/elf_flagscn.3  |   1 +
>  doc/elf_flagshdr.3 |   1 +
>  7 files changed, 156 insertions(+)
>  create mode 100644 doc/elf_flagdata.3
>  create mode 100644 doc/elf_flagehdr.3
>  create mode 100644 doc/elf_flagelf.3
>  create mode 100644 doc/elf_flagphdr.3
>  create mode 100644 doc/elf_flagscn.3
>  create mode 100644 doc/elf_flagshdr.3
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index e5b12133..3b63dc38 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -58,6 +58,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_getbase.3 \
>  			elf_getdata.3 \
>  			elf_getscn.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..1118deaa
> --- /dev/null
> +++ b/doc/elf_flagelf.3
> @@ -0,0 +1,145 @@
> +.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
> +#include <libelf.h>
> +
> +.B unsigned int elf_flagelf(Elf *" elf ", Elf_Cmd" cmd ", unsigned int" flags ");
> +.B unsigned int elf_flagehdr(Elf *" elf ", "Elf_Cmd" cmd ", unsigned int" flags ");
> +.B unsigned int elf_flagphdr(Elf *" elf ", Elf_Cmd" cmd ", unsigned int" flags ");
> +.B unsigned int elf_flagscn(Elf_Scn *" scn ", Elf_Cmd" cmd ", unsigned int" flags ");
> +.B unsigned int elf_flagshdr("Elf_Scn *" scn ", "Elf_Cmd" cmd ", unsigned int" flags ");
> +.B 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.
> +
> +.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).

OK.

> +.TP
> +.B ELF_F_LAYOUT
> +Indicates that the layout of the ELF component is managed manually. Offsets and
> +sizes will be preserved as provided.

Only effective with elf_flagelf.  Specifically this requires the user
to set the Ehdr e_phoff and e_shoff, the Elf_Data d_off and the Shdr
sh_offset. When not set elf_update will (re)calculate these offsets.

> +.TP
> +.B ELF_F_PERMISSIVE
> +Enables relaxed validation of object structure. This flag permits nonstandard layouts
> +without strict checks.

Only effective with elf_flagelf.  Note that this is an elfutils libelf
extension.  Specifically this removes the check in elf_update that the
section sh_size is a multiple of the section sh_entsize (if not zero).

> +.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 .

Should probably say that ELF_F_LAYOUT and ELF_F_PERMISSIVE only have
effect if used with elf_flagelf and are ignored for the other
functions.

> +.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).

Maybe add if the first argument is NULL then 0 is returned, but no new
error code is set.

> +.SH SEE ALSO
> +.BR elf_errmsg (3),
> +.BR libelf (3),
> +.BR elf (5)

Maybe add elf_update? Although the elf_update manual is kind of empty
at the moment.

> +.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

Looks correct.

> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
> 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.
diff mbox series

Patch

diff --git a/doc/Makefile.am b/doc/Makefile.am
index e5b12133..3b63dc38 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -58,6 +58,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_getbase.3 \
 			elf_getdata.3 \
 			elf_getscn.3 \
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
diff --git a/doc/elf_flagelf.3 b/doc/elf_flagelf.3
new file mode 100644
index 00000000..1118deaa
--- /dev/null
+++ b/doc/elf_flagelf.3
@@ -0,0 +1,145 @@ 
+.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
+#include <libelf.h>
+
+.B unsigned int elf_flagelf(Elf *" elf ", Elf_Cmd" cmd ", unsigned int" flags ");
+.B unsigned int elf_flagehdr(Elf *" elf ", "Elf_Cmd" cmd ", unsigned int" flags ");
+.B unsigned int elf_flagphdr(Elf *" elf ", Elf_Cmd" cmd ", unsigned int" flags ");
+.B unsigned int elf_flagscn(Elf_Scn *" scn ", Elf_Cmd" cmd ", unsigned int" flags ");
+.B unsigned int elf_flagshdr("Elf_Scn *" scn ", "Elf_Cmd" cmd ", unsigned int" flags ");
+.B unsigned int elf_flagdata(Elf_Data *" data ", Elf_Cmd" cmd ", unsigned int" flags ");
+.fi
+.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.
+
+.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 .
+
+The
+.I cmd
+argument determines whether the given flags should be set (
+.B ELF_C_SET
+) or cleared (
+.B ELF_C_CLR
+).
+
+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.
+
+.TP
+.B ELF_F_PERMISSIVE
+Enables relaxed validation of object structure. This flag permits nonstandard layouts
+without strict checks.
+
+.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.
+
+.TP
+.I cmd
+Must be either:
+.B ELF_C_SET
+to set the given flags, or
+.B ELF_C_CLR
+to clear them.
+
+.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 .
+
+.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).
+
+.SH SEE ALSO
+.BR elf_errmsg (3),
+.BR libelf (3),
+.BR elf (5)
+
+.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 <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
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