[8/9,v2] doc: Add elf{32, 64}_xlatetof.3 and elf{32, 64}_xlatetom.3
Commit Message
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
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
>
new file mode 100644
@@ -0,0 +1 @@
+.so man3/elf32_xlatetom.3
new file mode 100644
@@ -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/.
new file mode 100644
@@ -0,0 +1 @@
+.so man3/elf32_xlatetom.3
new file mode 100644
@@ -0,0 +1 @@
+.so man3/elf32_xlatetom.3