[8/9,v2] doc: Add elf{32, 64}_xlatetof.3 and elf{32, 64}_xlatetom.3

Message ID 20241003022610.129834-8-amerey@redhat.com
State Committed
Headers
Series [1/9,v2] doc: Add elf32_checksum.3 and elf64_checksum.3 |

Commit Message

Aaron Merey Oct. 3, 2024, 2:26 a.m. UTC
  Signed-off-by: Aaron Merey <amerey@redhat.com>
---

v2 changes:
Merge xlatetof and xlatetom man pages.

Added additional details suggested in Mark's review
https://sourceware.org/pipermail/elfutils-devel/2024q3/007377.html

 doc/elf32_xlatetof.3 |   1 +
 doc/elf32_xlatetom.3 | 130 +++++++++++++++++++++++++++++++++++++++++++
 doc/elf64_xlatetof.3 |   1 +
 doc/elf64_xlatetom.3 |   1 +
 4 files changed, 133 insertions(+)
 create mode 100644 doc/elf32_xlatetof.3
 create mode 100644 doc/elf32_xlatetom.3
 create mode 100644 doc/elf64_xlatetof.3
 create mode 100644 doc/elf64_xlatetom.3
  

Comments

Mark Wielaard Oct. 15, 2024, 9:49 p.m. UTC | #1
Hi Aaron,

On Wed, Oct 02, 2024 at 10:26:09PM -0400, Aaron Merey wrote:
> v2 changes:
> Merge xlatetof and xlatetom man pages.
> 
> Added additional details suggested in Mark's review
> https://sourceware.org/pipermail/elfutils-devel/2024q3/007377.html

I like this version. One small wording question below.

> diff --git a/doc/elf32_xlatetof.3 b/doc/elf32_xlatetof.3
> new file mode 100644
> index 00000000..47ecda27
> --- /dev/null
> +++ b/doc/elf32_xlatetof.3
> @@ -0,0 +1 @@
> +.so man3/elf32_xlatetom.3
> diff --git a/doc/elf32_xlatetom.3 b/doc/elf32_xlatetom.3
> new file mode 100644
> index 00000000..ec2024fd
> --- /dev/null
> +++ b/doc/elf32_xlatetom.3
> @@ -0,0 +1,130 @@
> +.TH ELF32_XLATETOM 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +.nf
> +elf32_xlatetom, elf64_xlatetom \- translate 32-bit or 64-bit ELF data from file
> +representation to memory representation
> +
> +elf32_xlatetof, elf64_xlatetof \- translate 32-bit or 64-bit ELF data from memory
> +representation to file representation
> +
> +.SH SYNOPSIS
> +.nf
> +.B #include <libelf.h>
> +
> +.BI "int elf32_xlatetom(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
> +.BI "int elf64_xlatetom(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
> +
> +.BI "int elf32_xlatetof(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
> +.BI "int elf64_xlatetof(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
> +
> +.SH DESCRIPTION
> +Translate ELF data from file representation to memory representation or
> +vice versa.  File and memory representations of ELF data can differ in
> +terms of endianness.  Data in file representation normally comes from
> +.B elf_rawdata
> +while data in memory representation normally comes from
> +.BR elf_getdata .
> +When there is no difference between file and memory representations,
> +these functions simply copy the ELF data from
> +.I src
> +to
> +.IR dst .
> +Otherwise the encoding with swap between
> +.B ELFDATA2LSB
> +(two's complement little-endian) and
> +.B ELFDATA2MSB
> +(two's complement big-endian).

Should that be "will swap" ?

> The encoding of an ELF file is specified
> +in the
> +.B Elf32_Ehdr
> +or
> +.B Elf64_Ehdr e_ident[EI_DATA]
> +member.  To know the memory encoding for a program you can
> +.B #include <endian.h>
> +and check BYTE_ORDER == LITTLE_ENDIAN (corresponding to
> +.BR ELFDATA2LSB )
> +or BYTE_ORDER == BIG_ENDIAN (corresponding to
> +.BR ELFDATA2MSB ).
> +
> +.SH PARAMETERS
> +.TP
> +.I dst
> +Destination where the translated data will be stored.
> +The
> +.B d_size
> +of
> +.I dst
> +should be at least as big as the
> +.B d_size
> +of
> +.IR src .
> +
> +.TP
> +.I src
> +Source data. For the
> +.B xlatetom
> +functions, the source data should be in file representation.
> +For the
> +.B xlatetof
> +functions, the source data should be in memory representation.
> +
> +.TP
> +.I encoding
> +Specifies an encoding.  Can be either
> +.B ELFDATA2LSB
> +(two's complement little-endian) or
> +.B ELFDATA2MSB
> +(two's complement big-endian).  For the
> +.B xlatetom
> +functions, this specifies the encoding of
> +.IR src .
> +For the
> +.B xlatetof
> +functions, this specifies the encoding of
> +.IR dst .
> +
> +.SH RETURN VALUE
> +On success, return
> +.IR dst ,
> +which will contain the translated data.  If there is no difference
> +between the file and memory representations,
> +.I dst
> +will contain a copy of the source data.  The
> +.B d_type
> +and
> +.B d_size
> +of
> +.I dst
> +will be set to those of
> +.IR src .
> +
> + If an error occurs, return
> +NULL and set a libelf error code.
> +
> +.SH SEE ALSO
> +.BR elf_errno (3),
> +.BR elf_getdata (3),
> +.BR elf_rawdata (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_xlatetom (),
> +.BR elf64_xlatetom (),
> +.BR elf32_xlatetof (),
> +.BR elf64_xlatetof ()
> +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_xlatetof.3 b/doc/elf64_xlatetof.3
> new file mode 100644
> index 00000000..47ecda27
> --- /dev/null
> +++ b/doc/elf64_xlatetof.3
> @@ -0,0 +1 @@
> +.so man3/elf32_xlatetom.3
> diff --git a/doc/elf64_xlatetom.3 b/doc/elf64_xlatetom.3
> new file mode 100644
> index 00000000..47ecda27
> --- /dev/null
> +++ b/doc/elf64_xlatetom.3
> @@ -0,0 +1 @@
> +.so man3/elf32_xlatetom.3
> -- 
> 2.46.2
>
  

Patch

diff --git a/doc/elf32_xlatetof.3 b/doc/elf32_xlatetof.3
new file mode 100644
index 00000000..47ecda27
--- /dev/null
+++ b/doc/elf32_xlatetof.3
@@ -0,0 +1 @@ 
+.so man3/elf32_xlatetom.3
diff --git a/doc/elf32_xlatetom.3 b/doc/elf32_xlatetom.3
new file mode 100644
index 00000000..ec2024fd
--- /dev/null
+++ b/doc/elf32_xlatetom.3
@@ -0,0 +1,130 @@ 
+.TH ELF32_XLATETOM 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+.nf
+elf32_xlatetom, elf64_xlatetom \- translate 32-bit or 64-bit ELF data from file
+representation to memory representation
+
+elf32_xlatetof, elf64_xlatetof \- translate 32-bit or 64-bit ELF data from memory
+representation to file representation
+
+.SH SYNOPSIS
+.nf
+.B #include <libelf.h>
+
+.BI "int elf32_xlatetom(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
+.BI "int elf64_xlatetom(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
+
+.BI "int elf32_xlatetof(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
+.BI "int elf64_xlatetof(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
+
+.SH DESCRIPTION
+Translate ELF data from file representation to memory representation or
+vice versa.  File and memory representations of ELF data can differ in
+terms of endianness.  Data in file representation normally comes from
+.B elf_rawdata
+while data in memory representation normally comes from
+.BR elf_getdata .
+When there is no difference between file and memory representations,
+these functions simply copy the ELF data from
+.I src
+to
+.IR dst .
+Otherwise the encoding with swap between
+.B ELFDATA2LSB
+(two's complement little-endian) and
+.B ELFDATA2MSB
+(two's complement big-endian). The encoding of an ELF file is specified
+in the
+.B Elf32_Ehdr
+or
+.B Elf64_Ehdr e_ident[EI_DATA]
+member.  To know the memory encoding for a program you can
+.B #include <endian.h>
+and check BYTE_ORDER == LITTLE_ENDIAN (corresponding to
+.BR ELFDATA2LSB )
+or BYTE_ORDER == BIG_ENDIAN (corresponding to
+.BR ELFDATA2MSB ).
+
+.SH PARAMETERS
+.TP
+.I dst
+Destination where the translated data will be stored.
+The
+.B d_size
+of
+.I dst
+should be at least as big as the
+.B d_size
+of
+.IR src .
+
+.TP
+.I src
+Source data. For the
+.B xlatetom
+functions, the source data should be in file representation.
+For the
+.B xlatetof
+functions, the source data should be in memory representation.
+
+.TP
+.I encoding
+Specifies an encoding.  Can be either
+.B ELFDATA2LSB
+(two's complement little-endian) or
+.B ELFDATA2MSB
+(two's complement big-endian).  For the
+.B xlatetom
+functions, this specifies the encoding of
+.IR src .
+For the
+.B xlatetof
+functions, this specifies the encoding of
+.IR dst .
+
+.SH RETURN VALUE
+On success, return
+.IR dst ,
+which will contain the translated data.  If there is no difference
+between the file and memory representations,
+.I dst
+will contain a copy of the source data.  The
+.B d_type
+and
+.B d_size
+of
+.I dst
+will be set to those of
+.IR src .
+
+ If an error occurs, return
+NULL and set a libelf error code.
+
+.SH SEE ALSO
+.BR elf_errno (3),
+.BR elf_getdata (3),
+.BR elf_rawdata (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_xlatetom (),
+.BR elf64_xlatetom (),
+.BR elf32_xlatetof (),
+.BR elf64_xlatetof ()
+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_xlatetof.3 b/doc/elf64_xlatetof.3
new file mode 100644
index 00000000..47ecda27
--- /dev/null
+++ b/doc/elf64_xlatetof.3
@@ -0,0 +1 @@ 
+.so man3/elf32_xlatetom.3
diff --git a/doc/elf64_xlatetom.3 b/doc/elf64_xlatetom.3
new file mode 100644
index 00000000..47ecda27
--- /dev/null
+++ b/doc/elf64_xlatetom.3
@@ -0,0 +1 @@ 
+.so man3/elf32_xlatetom.3