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
