From: Aaron Merey Date: Sun, 14 Sep 2025 23:20:59 +0000 (-0400) Subject: doc: Add elf_flag*.3 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=acc5b81defddd461b7851f137c1f262e00fe0b90;p=thirdparty%2Felfutils.git doc: Add elf_flag*.3 Signed-off-by: Aaron Merey --- 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 \ 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..7992f217 --- /dev/null +++ b/doc/elf_flagelf.3 @@ -0,0 +1,187 @@ +.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 + +.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 + +.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. 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. + +.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. + +.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 . + +Note that +.B ELF_F_LAYOUT +and +.B ELF_F_PERMISSIVE +are only used with +.BR elf_flagelf () +and are ignored for 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). +If the first argument is NULL then 0 is return and no error code is set. + +If the last flag is cleared, 0 will be returned as the new flag value. +In this case 0 is not an error indicator and no error code is set. + +.SH SEE ALSO +.BR elf_errmsg (3), +.BR elf_update (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 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