diff mbox series

[7/9] doc: Add elf32_newphdr.3 and elf64_newphdr.3

Message ID	20240814213321.244089-7-amerey@redhat.com
State	Superseded
Delegated to:	Mark Wielaard
Headers	DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 12E6D3858414 From: Aaron Merey <amerey@redhat.com> To: elfutils-devel@sourceware.org Cc: Aaron Merey <amerey@redhat.com> Subject: [PATCH 7/9] doc: Add elf32_newphdr.3 and elf64_newphdr.3 Date: Wed, 14 Aug 2024 17:33:19 -0400 Message-ID: <20240814213321.244089-7-amerey@redhat.com> In-Reply-To: <20240814213321.244089-1-amerey@redhat.com> References: <20240814213321.244089-1-amerey@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="US-ASCII"; x-default=true Precedence: list Errors-To: elfutils-devel-bounces~patchwork=sourceware.org@sourceware.org
Series	[1/9] doc: Add elf32_checksum.3 and elf64_checksum.3 \| [1/9] doc: Add elf32_checksum.3 and elf64_checksum.3 [2/9] doc: Add elf32_fsize.3 and elf64_fsize.3 [3/9] doc: Add elf32_getchdr.3 and elf64_getchdr.3 [4/9] doc: Add elf32_getphdr.3 and elf64_getphdr.3 [5/9] doc: Add elf32_getshdr.3 and elf64_getshdr.3 [6/9] doc: Add elf32_newehdr.3 and elf64_newehdr.3 [7/9] doc: Add elf32_newphdr.3 and elf64_newphdr.3 [8/9] doc: Add elf32_xlatetof.3 and elf64_xlatetof.3 [9/9] doc: Add elf32_xlatetom.3 and elf64_xlatetom.3

Commit Message

Aaron Merey Aug. 14, 2024, 9:33 p.m. UTC

  Signed-off-by: Aaron Merey <amerey@redhat.com>
---
 doc/elf32_newphdr.3 | 62 +++++++++++++++++++++++++++++++++++++++++++++
 doc/elf64_newphdr.3 | 62 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 124 insertions(+)
 create mode 100644 doc/elf32_newphdr.3
 create mode 100644 doc/elf64_newphdr.3

Comments

Mark Wielaard Aug. 28, 2024, 1:10 p.m. UTC | #1

Hi Aaron,

On Wed, 2024-08-14 at 17:33 -0400, Aaron Merey wrote:
> diff --git a/doc/elf32_newphdr.3 b/doc/elf32_newphdr.3
> new file mode 100644
> index 00000000..8f55566c
> --- /dev/null
> +++ b/doc/elf32_newphdr.3
> @@ -0,0 +1,62 @@
> +.TH ELF32_NEWPHDR 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf32_newphdr \- create a new program header table for an ELF32 object file
> +
> +.SH SYNOPSIS
> +.B #include <libelf.h>
> +
> +.BI "Elf32_Phdr *elf32_newphdr(Elf *" elf ", size_t " count ");"
> +
> +.SH DESCRIPTION
> +Create a new program header table for the ELF32 object file referred to by
> +.I elf.
> +The number of entries in the new program header table is specified by
> +.I count.  A
> +.I count
> +of zero removes the existing program header table.
> +
> +The function allocates a new array of
> +.I Elf32_Phdr
> +and makes it the program header table for
> +.I elf.
> +Any previous program header table is discarded.

This is unfortunate. But indeed what the code does. Maybe explicitly
mention that the new program headers are zeroed out. So the user knows
to make a copy of any old headers they want to preserve (copy back in
after extending or reducing the program header count).

> +.SH PARAMETERS
> +.TP
> +.I elf
> +Pointer to the ELF object for which a new program header table is to be created.
> +
> +.TP
> +.I count
> +The number of entries in the new program header table. A count of zero removes
> +the existing program header table.
> +
> +.SH RETURN VALUE
> +On success, return a pointer to the first
> +.I Elf32_Phdr
> +in the newly created program header table. If an error occurs, return NULL and set a libelf error code.

If count is zero this also returns NULL.
And like other functions, if elf is NULL no (new) error is set, but
NULL is returned.

Maybe add that an ehdr needs to exists before calling newphdr?

> +
> +.SH SEE ALSO
> +.BR elf_errno (3),
> +.BR elf64_newphdr (3),
> +.BR libelf (3),
> +.BR elf (5)
> +
> +.SH ATTRIBUTES
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface	Attribute	Value
> +T{
> +.na
> +.nh
> +.BR elf32_newphdr ()
> +T}	Thread safety	MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

Cheers,

Mark

diff mbox series

Patch

diff --git a/doc/elf32_newphdr.3 b/doc/elf32_newphdr.3
new file mode 100644
index 00000000..8f55566c
--- /dev/null
+++ b/doc/elf32_newphdr.3
@@ -0,0 +1,62 @@ 
+.TH ELF32_NEWPHDR 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf32_newphdr \- create a new program header table for an ELF32 object file
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "Elf32_Phdr *elf32_newphdr(Elf *" elf ", size_t " count ");"
+
+.SH DESCRIPTION
+Create a new program header table for the ELF32 object file referred to by
+.I elf.
+The number of entries in the new program header table is specified by
+.I count.  A
+.I count
+of zero removes the existing program header table.
+
+The function allocates a new array of
+.I Elf32_Phdr
+and makes it the program header table for
+.I elf.
+Any previous program header table is discarded.
+
+.SH PARAMETERS
+.TP
+.I elf
+Pointer to the ELF object for which a new program header table is to be created.
+
+.TP
+.I count
+The number of entries in the new program header table. A count of zero removes
+the existing program header table.
+
+.SH RETURN VALUE
+On success, return a pointer to the first
+.I Elf32_Phdr
+in the newly created program header table. If an error occurs, return NULL and set a libelf error code.
+
+.SH SEE ALSO
+.BR elf_errno (3),
+.BR elf64_newphdr (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR elf32_newphdr ()
+T}	Thread safety	MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
diff --git a/doc/elf64_newphdr.3 b/doc/elf64_newphdr.3
new file mode 100644
index 00000000..1de450a0
--- /dev/null
+++ b/doc/elf64_newphdr.3
@@ -0,0 +1,62 @@ 
+.TH ELF64_NEWPHDR 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf64_newphdr \- create a new program header table for an ELF64 object file
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "Elf64_Phdr *elf64_newphdr(Elf *" elf ", size_t " count ");"
+
+.SH DESCRIPTION
+Create a new program header table for the ELF64 object file referred to by
+.I elf.
+The number of entries in the new program header table is specified by
+.I count.  A
+.I count
+of zero removes the existing program header table.
+
+The function allocates a new array of
+.I Elf64_Phdr
+and makes it the program header table for
+.I elf.
+Any previous program header table is discarded.
+
+.SH PARAMETERS
+.TP
+.I elf
+Pointer to the ELF object for which a new program header table is to be created.
+
+.TP
+.I count
+The number of entries in the new program header table. A count of zero removes
+the existing program header table.
+
+.SH RETURN VALUE
+On success, return a pointer to the first
+.I Elf64_Phdr
+in the newly created program header table. If an error occurs, return NULL and set a libelf error code.
+
+.SH SEE ALSO
+.BR elf_errno (3),
+.BR elf32_newphdr (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR elf64_newphdr ()
+T}	Thread safety	MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.