diff mbox series

[8/9] doc: Add elf32_xlatetof.3 and elf64_xlatetof.3

Message ID 20240814213321.244089-8-amerey@redhat.com
State Superseded
Delegated to: Mark Wielaard
Headers
Series [1/9] doc: Add elf32_checksum.3 and elf64_checksum.3 |

Commit Message

Aaron Merey Aug. 14, 2024, 9:33 p.m. UTC 
  Signed-off-by: Aaron Merey <amerey@redhat.com>
---
 doc/elf32_xlatetof.3 | 61 ++++++++++++++++++++++++++++++++++++++++++++
 doc/elf64_xlatetof.3 | 61 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 122 insertions(+)
 create mode 100644 doc/elf32_xlatetof.3
 create mode 100644 doc/elf64_xlatetof.3

Comments

Mark Wielaard Aug. 28, 2024, 4:44 p.m. UTC | #1 
Hi Aaron,

I would recommend combining these two with the next two from [PATCH
9/9] doc: Add elf32_xlatetom.3 and elf64_xlatetom.3. They essentially
do the same things.

On Wed, 2024-08-14 at 17:33 -0400, Aaron Merey wrote:
> diff --git a/doc/elf32_xlatetof.3 b/doc/elf32_xlatetof.3
> new file mode 100644
> index 00000000..a33471f4
> --- /dev/null
> +++ b/doc/elf32_xlatetof.3
> @@ -0,0 +1,61 @@
> +.TH ELF32_XLATETOF 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf32_xlatetof \- translate ELF32 data to file representation
> +
> +.SH SYNOPSIS
> +.B #include <libelf.h>
> +
> +.BI "int elf32_xlatetof(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
> +
> +.SH DESCRIPTION
> +Translate ELF32 data from its memory representation to its file representation.

I think you really should expand on this description.

Explain that Elf_Data normally comes from elf_getdata, in which case it
is in memory representation, or from elf_rawdata, in which case it is
in file representation.

For xlatetof functions you provide encoding, as ELFDATA2LSB or
ELFDATA2MSB, for the dst encoding. For xlatetom functions you provide
the encoding of the src data.

To know a specific Elf file encoding you can look at the Ehdr
e_ident[EI_DATA]. To know the memory encoding for your program you
#include <endian.h> and check BYTE_ORDER == LITTLE_ENDIAN (for
ELFDATA2LSB) or BYTE_ORDER == BIG_ENDIAN (for ELFDATA2MSB).

If the file and memory encoding are the same these functions just move
the data between the src and dst buffers. Otherwise they will swap the
endian encoding of the values based on the d_type of the src.

The d_size of the dst should be at least as big as the src d_size.
After success the dst d_type and dst d_size will be equal to the src
d_type and src d_size.

> +.SH PARAMETERS
> +.TP
> +.I dst
> +Destination where the translated data will be stored.
> +
> +.TP
> +.I src
> +Source data in its memory representation.
> +
> +.TP
> +.I encoding
> +The encoding of the destination data.
> +.I encoding
> +can be either
> +.B ELFDATA2LSB
> +(two's complement little-endian) or
> +.B ELFDATA2MSB
> +(two's complement big-endian).
> +
> +.SH RETURN VALUE
> +Return
> +.I dest
> +on success. If an error occurs, return NULL and sets a libelf error code.
> +
> +.SH SEE ALSO
> +.BR elf_errno (3),
> +.BR elf32_xlatetom (3),
> +.BR elf64_xlatetof (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_xlatetof ()
> +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_xlatetof.3 b/doc/elf32_xlatetof.3
new file mode 100644
index 00000000..a33471f4
--- /dev/null
+++ b/doc/elf32_xlatetof.3
@@ -0,0 +1,61 @@ 
+.TH ELF32_XLATETOF 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf32_xlatetof \- translate ELF32 data to file representation
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "int elf32_xlatetof(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
+
+.SH DESCRIPTION
+Translate ELF32 data from its memory representation to its file representation.
+
+.SH PARAMETERS
+.TP
+.I dst
+Destination where the translated data will be stored.
+
+.TP
+.I src
+Source data in its memory representation.
+
+.TP
+.I encoding
+The encoding of the destination data.
+.I encoding
+can be either
+.B ELFDATA2LSB
+(two's complement little-endian) or
+.B ELFDATA2MSB
+(two's complement big-endian).
+
+.SH RETURN VALUE
+Return
+.I dest
+on success. If an error occurs, return NULL and sets a libelf error code.
+
+.SH SEE ALSO
+.BR elf_errno (3),
+.BR elf32_xlatetom (3),
+.BR elf64_xlatetof (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_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..4af26c91
--- /dev/null
+++ b/doc/elf64_xlatetof.3
@@ -0,0 +1,61 @@ 
+.TH ELF64_XLATETOF 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf64_xlatetof \- translate ELF64 data to file representation
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "int elf64_xlatetof(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");"
+
+.SH DESCRIPTION
+Translate ELF64 data from its memory representation to its file representation.
+
+.SH PARAMETERS
+.TP
+.I dst
+Destination where the translated data will be stored.
+
+.TP
+.I src
+Source data in its memory representation.
+
+.TP
+.I encoding
+The encoding of the destination data.
+.I encoding
+can be either
+.B ELFDATA2LSB
+(two's complement little-endian) or
+.B ELFDATA2MSB
+(two's complement big-endian).
+
+.SH RETURN VALUE
+Return
+.I dest
+on success. If an error occurs, return NULL and sets a libelf error code.
+
+.SH SEE ALSO
+.BR elf_errno (3),
+.BR elf32_xlatetof (3),
+.BR elf64_xlatetom (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_xlatetof ()
+T}	Thread safety	MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.