diff options
author | Aaron Merey <[email protected]> | 2024-06-19 13:16:58 -0400 |
---|---|---|
committer | Aaron Merey <[email protected]> | 2024-06-19 13:16:58 -0400 |
commit | 545515c536df5739314317e0b28472fb54461860 (patch) | |
tree | 315ded20c80d8921776bd2f256e9cefb1492da43 | |
parent | fe5990c7a87ee0ac5b405e721f0f904a798d5feb (diff) |
Add remaining libelf manpagesupstream/users/amerey/manpages
Chatgpt-generated. Human editing still required.
55 files changed, 3800 insertions, 0 deletions
diff --git a/doc/elf32_checksum.3 b/doc/elf32_checksum.3 new file mode 100644 index 00000000..62cfac68 --- /dev/null +++ b/doc/elf32_checksum.3 @@ -0,0 +1,62 @@ +.TH ELF32_CHECKSUM 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf32_checksum \- compute the checksum for an ELF32 object + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "uint32_t elf32_checksum(Elf *" elf ");" + +.SH DESCRIPTION +The .B elf32_checksum function computes a checksum for the ELF32 object referred to by .I elf. This checksum can be used to verify the integrity of the ELF32 object. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF32 object for which the checksum is to be computed. The ELF object must be valid and of type ELFCLASS32. + +.SH RETURN VALUE +The .B elf32_checksum function returns a .I uint32_t value representing the computed checksum. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf32_checksum fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Compute the checksum for an ELF32 object" +.nf +.in +4 +#include <libelf.h> +#include <stdio.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer for an ELF32 object + +uint32_t checksum = elf32_checksum(elf); +if (checksum == 0) { + // Handle error +} else { + printf("Checksum for the ELF32 object: %u\n", checksum); +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf64_checksum (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf32_fsize.3 b/doc/elf32_fsize.3 new file mode 100644 index 00000000..e74103c7 --- /dev/null +++ b/doc/elf32_fsize.3 @@ -0,0 +1,68 @@ +.TH ELF32_FSIZE 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf32_fsize \- calculate the file size of various ELF32 data structures + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "size_t elf32_fsize(Elf_Type " type ", size_t " count ", unsigned int " version ");" + +.SH DESCRIPTION +The .B elf32_fsize function calculates the file size in bytes of various ELF32 data structures, given their type and count. This function is useful for determining the amount of space needed to store ELF32 data structures in a file. + +.SH PARAMETERS +.TP +.I type +An .I Elf_Type value specifying the type of ELF32 data structure for which the file size is to be calculated. Valid types include .B ELF_T_EHDR, .B ELF_T_PHDR, .B ELF_T_SHDR, .B ELF_T_WORD, and others. + +.TP +.I count +A .I size_t value specifying the number of elements of the specified type. + +.TP +.I version +An .I unsigned int value specifying the ELF version. This should be set to .B EV_CURRENT. + +.SH RETURN VALUE +The .B elf32_fsize function returns the size in bytes of the specified ELF32 data structures. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf32_fsize fails, it sets the following error codes: + +.TP +.B ELFARG +One or more of the parameters are invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Calculate the file size of 10 ELF32 section headers" +.nf +.in +4 +#include <libelf.h> + +size_t count = 10; +size_t size = elf32_fsize(ELF_T_SHDR, count, EV_CURRENT); +if (size == 0) { + // Handle error +} else { + printf("Size of 10 ELF32 section headers: %zu bytes\n", size); +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf64_fsize (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf32_getchdr.3 b/doc/elf32_getchdr.3 new file mode 100644 index 00000000..4a94ddeb --- /dev/null +++ b/doc/elf32_getchdr.3 @@ -0,0 +1,64 @@ +.TH ELF32_GETCHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf32_getchdr \- retrieve the command header for a command descriptor in an ELF32 file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf32_Chdr *elf32_getchdr(Elf_Cmd *" cmd ");" + +.SH DESCRIPTION +The .B elf32_getchdr function retrieves the command header for the command descriptor referred to by .I cmd in an ELF32 object. The command header contains metadata about the command, such as its type, size, and memory offset. + +.SH PARAMETERS +.TP +.I cmd +An .I Elf_Cmd pointer to the command descriptor whose command header is to be retrieved. The command descriptor must be valid. + +.SH RETURN VALUE +The .B elf32_getchdr function returns a pointer to the .I Elf32_Chdr structure representing the command header. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf32_getchdr fails, it sets the following error codes: + +.TP +.B ELFARG +The .I cmd parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the command header for a command descriptor" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Cmd *cmd = ...; // Assume cmd is a valid command descriptor + +Elf32_Chdr *chdr = elf32_getchdr(cmd); +if (chdr == NULL) { + // Handle error +} else { + // Use chdr +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getcmd (3), +.BR elf_nextcmd (3), +.BR elf_ndxcmd (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf32_getphdr.3 b/doc/elf32_getphdr.3 new file mode 100644 index 00000000..4b267b12 --- /dev/null +++ b/doc/elf32_getphdr.3 @@ -0,0 +1,69 @@ +.TH ELF32_GETPHDR 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf32_getphdr \- retrieve the program header for a 32-bit ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +Elf32_Phdr *elf32_getphdr(Elf *elf); +.fi + +.SH DESCRIPTION +.B elf32_getphdr +retrieves the program header table for the given 32-bit ELF descriptor +.I elf. +The program header table contains information about the segments of the ELF file, which are used during the execution of the program. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor from which to retrieve the program header table. + +.SH RETURN VALUE +On success, +.B elf32_getphdr +returns a pointer to the +.B Elf32_Phdr +structure. If the ELF descriptor is invalid or not a 32-bit ELF, it returns NULL and sets an error code retrievable by +.BR elf_errno (3). + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_READ, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + Elf32_Phdr *phdr = elf32_getphdr(elf); + if (phdr == NULL) { + printf("Error retrieving program header: %s\n", elf_errmsg(-1)); + } else { + // Process the program header + for (int i = 0; i < ehdr->e_phnum; i++) { + printf("Program Header %d: Type: %d\n", i, phdr[i].p_type); + } + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf_errmsg (3), +.BR elf_getphdrnum (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf32_getphdr +first appeared in elfutils 0.186. + diff --git a/doc/elf32_getshdr.3 b/doc/elf32_getshdr.3 new file mode 100644 index 00000000..144463ca --- /dev/null +++ b/doc/elf32_getshdr.3 @@ -0,0 +1,64 @@ +.TH ELF32_GETSHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf32_getshdr \- retrieve the section header for a section descriptor in an ELF32 file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf32_Shdr *elf32_getshdr(Elf_Scn *" scn ");" + +.SH DESCRIPTION +The .B elf32_getshdr function retrieves the section header for the section descriptor referred to by .I scn in an ELF32 object. The section header contains metadata about the section, such as its type, size, and memory offset. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor whose section header is to be retrieved. The section descriptor must be valid. + +.SH RETURN VALUE +The .B elf32_getshdr function returns a pointer to the .I Elf32_Shdr structure representing the section header. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf32_getshdr fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the section header for a section descriptor" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +Elf32_Shdr *shdr = elf32_getshdr(scn); +if (shdr == NULL) { + // Handle error +} else { + // Use shdr +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf_nextscn (3), +.BR elf_ndxscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf32_newehdr.3 b/doc/elf32_newehdr.3 new file mode 100644 index 00000000..18c10dcd --- /dev/null +++ b/doc/elf32_newehdr.3 @@ -0,0 +1,74 @@ +.TH ELF32_NEWEHDR 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf32_newehdr \- create a new 32-bit ELF header + +.SH SYNOPSIS +.nf +#include <libelf.h> + +Elf32_Ehdr *elf32_newehdr(Elf *elf); +.fi + +.SH DESCRIPTION +.B elf32_newehdr +creates a new 32-bit ELF header for the given ELF descriptor +.I elf. +This function initializes a new +.B Elf32_Ehdr +structure and associates it with the ELF descriptor. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor for which a new ELF header is to be created. + +.SH RETURN VALUE +On success, +.B elf32_newehdr +returns a pointer to the newly created +.B Elf32_Ehdr +structure. If the ELF descriptor is invalid, it returns NULL and sets an error code retrievable by +.BR elf_errno (3). + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_WRITE, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + Elf32_Ehdr *ehdr = elf32_newehdr(elf); + if (ehdr == NULL) { + printf("Error creating new ELF header: %s\n", elf_errmsg(-1)); + } else { + // Initialize ELF header fields + ehdr->e_ident[EI_MAG0] = ELFMAG0; + ehdr->e_ident[EI_MAG1] = ELFMAG1; + ehdr->e_ident[EI_MAG2] = ELFMAG2; + ehdr->e_ident[EI_MAG3] = ELFMAG3; + ehdr->e_type = ET_EXEC; + // Additional header field initialization + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf_errmsg (3), +.BR elf32_getehdr (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf32_newehdr +first appeared in elfutils 0.186. + diff --git a/doc/elf32_newphdr.3 b/doc/elf32_newphdr.3 new file mode 100644 index 00000000..45af7513 --- /dev/null +++ b/doc/elf32_newphdr.3 @@ -0,0 +1,73 @@ +.TH ELF32_NEWPHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf32_newphdr \- create a new program header table for an ELF32 file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf32_Phdr *elf32_newphdr(Elf *" elf ", size_t " count ");" + +.SH DESCRIPTION +The .B elf32_newphdr function creates a new program header table for the ELF object referred to by .I elf. The number of entries in the new program header table is specified by .I count. + +The function allocates a new array of .I Elf32_Phdr structures and makes it the program header table for the ELF object. Any previously existing program header table is discarded. + +The program header table describes the segments of the ELF file. Each segment specifies information necessary for the system to prepare the program for execution. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object for which a new program header table is to be created. + +.TP +.I count +A .I size_t value representing the number of entries in the new program header table. + +.SH RETURN VALUE +The .B elf32_newphdr function returns a pointer to the first .I Elf32_Phdr structure in the newly created program header table. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf32_newphdr fails, it sets the following error codes: + +.TP +.B ELFMEM +Memory allocation failed. + +.TP +.B ELFARG +The .I elf parameter is NULL, or .I count is zero. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Create a new program header table with 5 entries" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +size_t count = 5; + +Elf32_Phdr *phdr = elf32_newphdr(elf, count); +if (phdr == NULL) { + // Handle error +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf32_getphdr (3), +.BR elf64_newphdr (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf32_offscn.3 b/doc/elf32_offscn.3 new file mode 100644 index 00000000..e6b6cfa1 --- /dev/null +++ b/doc/elf32_offscn.3 @@ -0,0 +1,72 @@ +.TH ELF32_OFFSCN 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf32_offscn \- retrieve a section descriptor by file offset for an ELF32 file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Scn *elf32_offscn(Elf *" elf ", off_t " offset ");" + +.SH DESCRIPTION +The .B elf32_offscn function retrieves the section descriptor for the section at the specified file offset in the ELF32 object referred to by .I elf. + +Sections in an ELF file are located at specific offsets within the file. This function allows access to a section based on its file offset, which is particularly useful when parsing or manipulating ELF files at a low level. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object from which the section descriptor is to be retrieved. + +.TP +.I offset +An .I off_t value representing the file offset of the section whose descriptor is to be retrieved. The offset is typically obtained from other ELF structures, such as program headers or section headers. + +.SH RETURN VALUE +The .B elf32_offscn function returns a pointer to the .I Elf_Scn structure for the section at the specified offset. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf32_offscn fails, it sets the following error codes: + +.TP +.B ELFMEM +Memory allocation failed. + +.TP +.B ELFARG +The .I elf parameter is NULL, or .I offset is invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the section descriptor for a section at a specific offset" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +off_t offset = ...; // Specify a valid file offset + +Elf_Scn *scn = elf32_offscn(elf, offset); +if (scn == NULL) { + // Handle error +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf32_getshdr (3), +.BR elf32_getphdr (3), +.BR elf_getscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf32_xlatetof.3 b/doc/elf32_xlatetof.3 new file mode 100644 index 00000000..a621a788 --- /dev/null +++ b/doc/elf32_xlatetof.3 @@ -0,0 +1,70 @@ +.TH ELF32_XLATETOF 3 "June 2024" "Elfutils" "Library Functions 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 +The .B elf32_xlatetof function translates ELF32 data from its memory representation to its file representation. This function is typically used to convert data from memory into a format suitable for writing to an ELF file. + +.SH PARAMETERS +.TP +.I dst +An .I Elf_Data pointer to a structure where the translated data will be stored. The destination structure must be properly initialized. + +.TP +.I src +A constant .I Elf_Data pointer to a structure containing the source data in its memory representation. + +.TP +.I encoding +An .I unsigned int value specifying the encoding of the destination data. This parameter can be either .B ELFDATA2LSB (little-endian) or .B ELFDATA2MSB (big-endian). + +.SH RETURN VALUE +The .B elf32_xlatetof function returns 0 on success. If an error occurs, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf32_xlatetof fails, it sets the following error codes: + +.TP +.B ELFARG +One or more of the parameters are NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Translate ELF32 data from memory to file representation" +.nf +.in +4 +#include <libelf.h> + +Elf_Data src; // Assume src is properly initialized and contains memory representation data +Elf_Data dst; + +if (elf32_xlatetof(&dst, &src, ELFDATA2LSB) != 0) { + // Handle error +} else { + // Process the translated data in dst +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf32_xlatetom (3), +.BR elf64_xlatetof (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf32_xlatetom.3 b/doc/elf32_xlatetom.3 new file mode 100644 index 00000000..1996cf8e --- /dev/null +++ b/doc/elf32_xlatetom.3 @@ -0,0 +1,70 @@ +.TH ELF32_XLATETOM 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf32_xlatetom \- translate ELF32 data to memory representation + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf32_xlatetom(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");" + +.SH DESCRIPTION +The .B elf32_xlatetom function translates ELF32 data from its file representation to its memory representation. This function is typically used to convert data read from an ELF file into a format suitable for processing in memory. + +.SH PARAMETERS +.TP +.I dst +An .I Elf_Data pointer to a structure where the translated data will be stored. The destination structure must be properly initialized. + +.TP +.I src +A constant .I Elf_Data pointer to a structure containing the source data in its file representation. + +.TP +.I encoding +An .I unsigned int value specifying the encoding of the source data. This parameter can be either .B ELFDATA2LSB (little-endian) or .B ELFDATA2MSB (big-endian). + +.SH RETURN VALUE +The .B elf32_xlatetom function returns 0 on success. If an error occurs, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf32_xlatetom fails, it sets the following error codes: + +.TP +.B ELFARG +One or more of the parameters are NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Translate ELF32 data from file to memory representation" +.nf +.in +4 +#include <libelf.h> + +Elf_Data src; // Assume src is properly initialized and contains file representation data +Elf_Data dst; + +if (elf32_xlatetom(&dst, &src, ELFDATA2LSB) != 0) { + // Handle error +} else { + // Process the translated data in dst +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf32_xlatetof (3), +.BR elf64_xlatetom (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf64_checksum.3 b/doc/elf64_checksum.3 new file mode 100644 index 00000000..f1aeefd9 --- /dev/null +++ b/doc/elf64_checksum.3 @@ -0,0 +1,62 @@ +.TH ELF64_CHECKSUM 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf64_checksum \- compute the checksum for an ELF64 object + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "uint32_t elf64_checksum(Elf *" elf ");" + +.SH DESCRIPTION +The .B elf64_checksum function computes a checksum for the ELF64 object referred to by .I elf. This checksum can be used to verify the integrity of the ELF64 object. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF64 object for which the checksum is to be computed. The ELF object must be valid and of type ELFCLASS64. + +.SH RETURN VALUE +The .B elf64_checksum function returns a .I uint32_t value representing the computed checksum. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf64_checksum fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Compute the checksum for an ELF64 object" +.nf +.in +4 +#include <libelf.h> +#include <stdio.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer for an ELF64 object + +uint32_t checksum = elf64_checksum(elf); +if (checksum == 0) { + // Handle error +} else { + printf("Checksum for the ELF64 object: %u\n", checksum); +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf32_checksum (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf64_fsize.3 b/doc/elf64_fsize.3 new file mode 100644 index 00000000..25e71698 --- /dev/null +++ b/doc/elf64_fsize.3 @@ -0,0 +1,68 @@ +.TH ELF64_FSIZE 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf64_fsize \- calculate the file size of various ELF64 data structures + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "size_t elf64_fsize(Elf_Type " type ", size_t " count ", unsigned int " version ");" + +.SH DESCRIPTION +The .B elf64_fsize function calculates the file size in bytes of various ELF64 data structures, given their type and count. This function is useful for determining the amount of space needed to store ELF64 data structures in a file. + +.SH PARAMETERS +.TP +.I type +An .I Elf_Type value specifying the type of ELF64 data structure for which the file size is to be calculated. Valid types include .B ELF_T_EHDR, .B ELF_T_PHDR, .B ELF_T_SHDR, .B ELF_T_WORD, and others. + +.TP +.I count +A .I size_t value specifying the number of elements of the specified type. + +.TP +.I version +An .I unsigned int value specifying the ELF version. This should be set to .B EV_CURRENT. + +.SH RETURN VALUE +The .B elf64_fsize function returns the size in bytes of the specified ELF64 data structures. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf64_fsize fails, it sets the following error codes: + +.TP +.B ELFARG +One or more of the parameters are invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Calculate the file size of 10 ELF64 section headers" +.nf +.in +4 +#include <libelf.h> + +size_t count = 10; +size_t size = elf64_fsize(ELF_T_SHDR, count, EV_CURRENT); +if (size == 0) { + // Handle error +} else { + printf("Size of 10 ELF64 section headers: %zu bytes\n", size); +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf32_fsize (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf64_getchdr.3 b/doc/elf64_getchdr.3 new file mode 100644 index 00000000..037426d2 --- /dev/null +++ b/doc/elf64_getchdr.3 @@ -0,0 +1,65 @@ +.TH ELF64_GETCHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf64_getchdr \- retrieve the chunk header for a chunk descriptor in an ELF64 file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf64_Chdr *elf64_getchdr(Elf_Scn *" scn ");" + +.SH DESCRIPTION +The .B elf64_getchdr function retrieves the chunk header for the chunk descriptor referred to by .I scn in an ELF64 object. The chunk header contains metadata about the chunk, such as its type, size, and memory offset. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the chunk descriptor whose chunk header is to be retrieved. The chunk descriptor must be valid. + +.SH RETURN VALUE +The .B elf64_getchdr function returns a pointer to the .I Elf64_Chdr structure representing the chunk header. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf64_getchdr fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the chunk header for a chunk descriptor" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid chunk descriptor + +Elf64_Chdr *chdr = elf64_getchdr(scn); +if (chdr == NULL) { + // Handle error +} else { + // Use chdr +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf_nextscn (3), +.BR elf_ndxscn (3), +.BR elf64_getshdr (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf64_getphdr.3 b/doc/elf64_getphdr.3 new file mode 100644 index 00000000..b115d37e --- /dev/null +++ b/doc/elf64_getphdr.3 @@ -0,0 +1,74 @@ +.TH ELF64_GETPHDR 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf64_getphdr \- retrieve the program header for a 64-bit ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +Elf64_Phdr *elf64_getphdr(Elf *elf); +.fi + +.SH DESCRIPTION +.B elf64_getphdr +retrieves the program header table for the given 64-bit ELF descriptor +.I elf. +The program header table contains information about the segments of the ELF file, which are used during the execution of the program. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor from which to retrieve the program header table. + +.SH RETURN VALUE +On success, +.B elf64_getphdr +returns a pointer to the +.B Elf64_Phdr +structure. If the ELF descriptor is invalid or not a 64-bit ELF, it returns NULL and sets an error code retrievable by +.BR elf_errno (3). + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_READ, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + Elf64_Ehdr *ehdr = elf64_getehdr(elf); + if (ehdr == NULL) { + printf("Error retrieving ELF header: %s\n", elf_errmsg(-1)); + } else { + Elf64_Phdr *phdr = elf64_getphdr(elf); + if (phdr == NULL) { + printf("Error retrieving program header: %s\n", elf_errmsg(-1)); + } else { + // Process the program header + for (int i = 0; i < ehdr->e_phnum; i++) { + printf("Program Header %d: Type: %d\n", i, phdr[i].p_type); + } + } + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf_errmsg (3), +.BR elf64_getehdr (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf64_getphdr +first appeared in elfutils 0.186. + diff --git a/doc/elf64_getshdr.3 b/doc/elf64_getshdr.3 new file mode 100644 index 00000000..f6e42a1d --- /dev/null +++ b/doc/elf64_getshdr.3 @@ -0,0 +1,64 @@ +.TH ELF64_GETSHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf64_getshdr \- retrieve the section header for a section descriptor in an ELF64 file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf64_Shdr *elf64_getshdr(Elf_Scn *" scn ");" + +.SH DESCRIPTION +The .B elf64_getshdr function retrieves the section header for the section descriptor referred to by .I scn in an ELF64 object. The section header contains metadata about the section, such as its type, size, and memory offset. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor whose section header is to be retrieved. The section descriptor must be valid. + +.SH RETURN VALUE +The .B elf64_getshdr function returns a pointer to the .I Elf64_Shdr structure representing the section header. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf64_getshdr fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the section header for a section descriptor" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +Elf64_Shdr *shdr = elf64_getshdr(scn); +if (shdr == NULL) { + // Handle error +} else { + // Use shdr +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf_nextscn (3), +.BR elf_ndxscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf64_newehdr.3 b/doc/elf64_newehdr.3 new file mode 100644 index 00000000..91cebedf --- /dev/null +++ b/doc/elf64_newehdr.3 @@ -0,0 +1,74 @@ +.TH ELF64_NEWEHDR 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf64_newehdr \- create a new 64-bit ELF header + +.SH SYNOPSIS +.nf +#include <libelf.h> + +Elf64_Ehdr *elf64_newehdr(Elf *elf); +.fi + +.SH DESCRIPTION +.B elf64_newehdr +creates a new 64-bit ELF header for the given ELF descriptor +.I elf. +This function initializes a new +.B Elf64_Ehdr +structure and associates it with the ELF descriptor. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor for which a new ELF header is to be created. + +.SH RETURN VALUE +On success, +.B elf64_newehdr +returns a pointer to the newly created +.B Elf64_Ehdr +structure. If the ELF descriptor is invalid, it returns NULL and sets an error code retrievable by +.BR elf_errno (3). + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_WRITE, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + Elf64_Ehdr *ehdr = elf64_newehdr(elf); + if (ehdr == NULL) { + printf("Error creating new ELF header: %s\n", elf_errmsg(-1)); + } else { + // Initialize ELF header fields + ehdr->e_ident[EI_MAG0] = ELFMAG0; + ehdr->e_ident[EI_MAG1] = ELFMAG1; + ehdr->e_ident[EI_MAG2] = ELFMAG2; + ehdr->e_ident[EI_MAG3] = ELFMAG3; + ehdr->e_type = ET_EXEC; + // Additional header field initialization + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf_errmsg (3), +.BR elf64_getehdr (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf64_newehdr +first appeared in elfutils 0.186. + diff --git a/doc/elf64_newphdr.3 b/doc/elf64_newphdr.3 new file mode 100644 index 00000000..5ee6915d --- /dev/null +++ b/doc/elf64_newphdr.3 @@ -0,0 +1,78 @@ +.TH ELF64_NEWPHDR 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf64_newphdr \- create a new program header for a 64-bit ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +Elf64_Phdr *elf64_newphdr(Elf *elf, size_t phnum); +.fi + +.SH DESCRIPTION +.B elf64_newphdr +creates a new program header table for the given 64-bit ELF descriptor +.I elf. +This function allocates a new +.B Elf64_Phdr +structure with +.I phnum +entries and associates it with the ELF descriptor. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor for which a new program header table is to be created. +.TP +.I phnum +The number of entries in the new program header table. + +.SH RETURN VALUE +On success, +.B elf64_newphdr +returns a pointer to the newly created +.B Elf64_Phdr +structure. If the ELF descriptor is invalid or the program header table cannot be created, it returns NULL and sets an error code retrievable by +.BR elf_errno (3). + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_WRITE, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + size_t phnum = 5; // Number of program headers + Elf64_Phdr *phdr = elf64_newphdr(elf, phnum); + if (phdr == NULL) { + printf("Error creating new program header: %s\n", elf_errmsg(-1)); + } else { + // Initialize program header fields + for (size_t i = 0; i < phnum; i++) { + phdr[i].p_type = PT_LOAD; + // Additional initialization + } + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf_errno (3), +.BR elf64_getphdr (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf64_newphdr +first appeared in elfutils 0.186. + diff --git a/doc/elf64_offscn.3 b/doc/elf64_offscn.3 new file mode 100644 index 00000000..4321944d --- /dev/null +++ b/doc/elf64_offscn.3 @@ -0,0 +1,72 @@ +.TH ELF64_OFFSCN 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf64_offscn \- retrieve a section descriptor by file offset for an ELF64 file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Scn *elf64_offscn(Elf *" elf ", off_t " offset ");" + +.SH DESCRIPTION +The .B elf64_offscn function retrieves the section descriptor for the section at the specified file offset in the ELF64 object referred to by .I elf. + +Sections in an ELF file are located at specific offsets within the file. This function allows access to a section based on its file offset, which is particularly useful when parsing or manipulating ELF files at a low level. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object from which the section descriptor is to be retrieved. + +.TP +.I offset +An .I off_t value representing the file offset of the section whose descriptor is to be retrieved. The offset is typically obtained from other ELF structures, such as program headers or section headers. + +.SH RETURN VALUE +The .B elf64_offscn function returns a pointer to the .I Elf_Scn structure for the section at the specified offset. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf64_offscn fails, it sets the following error codes: + +.TP +.B ELFMEM +Memory allocation failed. + +.TP +.B ELFARG +The .I elf parameter is NULL, or .I offset is invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the section descriptor for a section at a specific offset" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +off_t offset = ...; // Specify a valid file offset + +Elf_Scn *scn = elf64_offscn(elf, offset); +if (scn == NULL) { + // Handle error +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf64_getshdr (3), +.BR elf64_getphdr (3), +.BR elf_getscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf64_xlatetof.3 b/doc/elf64_xlatetof.3 new file mode 100644 index 00000000..a30fe154 --- /dev/null +++ b/doc/elf64_xlatetof.3 @@ -0,0 +1,70 @@ +.TH ELF64_XLATETOF 3 "June 2024" "Elfutils" "Library Functions 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 +The .B elf64_xlatetof function translates ELF64 data from its memory representation to its file representation. This function is typically used to convert data from memory into a format suitable for writing to an ELF file. + +.SH PARAMETERS +.TP +.I dst +An .I Elf_Data pointer to a structure where the translated data will be stored. The destination structure must be properly initialized. + +.TP +.I src +A constant .I Elf_Data pointer to a structure containing the source data in its memory representation. + +.TP +.I encoding +An .I unsigned int value specifying the encoding of the destination data. This parameter can be either .B ELFDATA2LSB (little-endian) or .B ELFDATA2MSB (big-endian). + +.SH RETURN VALUE +The .B elf64_xlatetof function returns 0 on success. If an error occurs, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf64_xlatetof fails, it sets the following error codes: + +.TP +.B ELFARG +One or more of the parameters are NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Translate ELF64 data from memory to file representation" +.nf +.in +4 +#include <libelf.h> + +Elf_Data src; // Assume src is properly initialized and contains memory representation data +Elf_Data dst; + +if (elf64_xlatetof(&dst, &src, ELFDATA2LSB) != 0) { + // Handle error +} else { + // Process the translated data in dst +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf64_xlatetom (3), +.BR elf32_xlatetof (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf64_xlatetom.3 b/doc/elf64_xlatetom.3 new file mode 100644 index 00000000..573e6472 --- /dev/null +++ b/doc/elf64_xlatetom.3 @@ -0,0 +1,70 @@ +.TH ELF64_XLATETOM 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf64_xlatetom \- translate ELF64 data to memory representation + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf64_xlatetom(Elf_Data *" dst ", const Elf_Data *" src ", unsigned int " encoding ");" + +.SH DESCRIPTION +The .B elf64_xlatetom function translates ELF64 data from its file representation to its memory representation. This function is typically used to convert data read from an ELF file into a format suitable for processing in memory. + +.SH PARAMETERS +.TP +.I dst +An .I Elf_Data pointer to a structure where the translated data will be stored. The destination structure must be properly initialized. + +.TP +.I src +A constant .I Elf_Data pointer to a structure containing the source data in its file representation. + +.TP +.I encoding +An .I unsigned int value specifying the encoding of the source data. This parameter can be either .B ELFDATA2LSB (little-endian) or .B ELFDATA2MSB (big-endian). + +.SH RETURN VALUE +The .B elf64_xlatetom function returns 0 on success. If an error occurs, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf64_xlatetom fails, it sets the following error codes: + +.TP +.B ELFARG +One or more of the parameters are NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Translate ELF64 data from file to memory representation" +.nf +.in +4 +#include <libelf.h> + +Elf_Data src; // Assume src is properly initialized and contains file representation data +Elf_Data dst; + +if (elf64_xlatetom(&dst, &src, ELFDATA2LSB) != 0) { + // Handle error +} else { + // Process the translated data in dst +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf64_xlatetof (3), +.BR elf32_xlatetom (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_cntl.3 b/doc/elf_cntl.3 new file mode 100644 index 00000000..804abd22 --- /dev/null +++ b/doc/elf_cntl.3 @@ -0,0 +1,69 @@ +.TH ELF_CNTL 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_cntl \- control ELF descriptor state + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf_cntl(Elf *" elf ", Elf_Cmd " cmd ");" + +.SH DESCRIPTION +The .B elf_cntl function is used to control the state of an ELF descriptor referred to by .I elf. This function can be used to perform operations such as flushing internal buffers to the underlying file. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF descriptor for which the control operation is to be performed. The ELF descriptor must be valid. + +.TP +.I cmd +An .I Elf_Cmd value specifying the control operation to be performed. The supported command is: +.RS +.IP \- ELF_C_FDREAD +Flushes internal buffers to the underlying file, ensuring that any modifications made to the ELF object are written out. +.RE + +.SH RETURN VALUE +The .B elf_cntl function returns 0 on success. If an error occurs, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf_cntl fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid, or the .I cmd parameter is not supported. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Flush internal buffers to the underlying file for an ELF descriptor" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer + +if (elf_cntl(elf, ELF_C_FDREAD) != 0) { + // Handle error +} else { + // Buffers successfully flushed +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_begin (3), +.BR elf_end (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_compress.3 b/doc/elf_compress.3 new file mode 100644 index 00000000..02fedd6c --- /dev/null +++ b/doc/elf_compress.3 @@ -0,0 +1,75 @@ +.TH ELF_COMPRESS 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_compress \- compress sections in an ELF file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf_compress(Elf_Scn *" scn ", unsigned int " compression_type ", int " flags ");" + +.SH DESCRIPTION +The .B elf_compress function compresses the section referred to by .I scn in an ELF object. The type of compression and additional flags can be specified. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor to be compressed. The section descriptor must be valid. + +.TP +.I compression_type +An .I unsigned int value specifying the type of compression to use. Typically, this corresponds to one of the ELF compression types defined in the ELF standard (e.g., .B ELFCOMPRESS_ZLIB). + +.TP +.I flags +An .I int value specifying additional options for compression. Possible values include .B ELF_F_COMPR_ZLIB, which indicates that the section should be compressed using the ZLIB algorithm. + +.SH RETURN VALUE +The .B elf_compress function returns 0 on success. On error, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf_compress fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.TP +.B ELFCOMPR +Compression failed due to an issue with the compression algorithm or the data being compressed. + +.SH EXAMPLES +.B "Example 1: Compress a section in an ELF file using ZLIB" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +if (elf_compress(scn, ELFCOMPRESS_ZLIB, 0) != 0) { + // Handle error +} else { + // Section is now compressed +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf32_getshdr (3), +.BR elf64_getshdr (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_compress_gnu.3 b/doc/elf_compress_gnu.3 new file mode 100644 index 00000000..f17a85c0 --- /dev/null +++ b/doc/elf_compress_gnu.3 @@ -0,0 +1,75 @@ +.TH ELF_COMPRESS_GNU 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_compress_gnu \- compress sections in an ELF file using GNU compression + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf_compress_gnu(Elf_Scn *" scn ", unsigned int " compression_type ", int " flags ");" + +.SH DESCRIPTION +The .B elf_compress_gnu function compresses the section referred to by .I scn in an ELF object using GNU compression. The type of compression and additional flags can be specified. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor to be compressed. The section descriptor must be valid. + +.TP +.I compression_type +An .I unsigned int value specifying the type of compression to use. Typically, this corresponds to one of the ELF compression types defined in the ELF standard (e.g., .B ELFCOMPRESS_ZLIB). + +.TP +.I flags +An .I int value specifying additional options for compression. For example, .B 0 for default behavior. + +.SH RETURN VALUE +The .B elf_compress_gnu function returns 0 on success. On error, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf_compress_gnu fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.TP +.B ELFCOMPR +Compression failed due to an issue with the compression algorithm or the data being compressed. + +.SH EXAMPLES +.B "Example 1: Compress a section in an ELF file using GNU ZLIB" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +if (elf_compress_gnu(scn, ELFCOMPRESS_ZLIB, 0) != 0) { + // Handle error +} else { + // Section is now compressed +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf32_getshdr (3), +.BR elf64_getshdr (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_end.3 b/doc/elf_end.3 new file mode 100644 index 00000000..80ec79c2 --- /dev/null +++ b/doc/elf_end.3 @@ -0,0 +1,60 @@ +.TH ELF_END 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf_end \- terminate ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +int elf_end(Elf *elf); +.fi + +.SH DESCRIPTION +.B elf_end +releases all resources associated with the ELF descriptor +.I elf. +This function should be called when the application is done using the ELF descriptor to ensure that all associated resources are properly freed. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor to be terminated. + +.SH RETURN VALUE +.B elf_end +returns the number of active ELF descriptors. If +.I elf +is NULL, it returns 0. + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_READ, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + // Use the ELF descriptor + ... + // Terminate the ELF descriptor + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_memory (3), +.BR elf_errmsg (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf_end +first appeared in elfutils 0.186. + diff --git a/doc/elf_fill.3 b/doc/elf_fill.3 new file mode 100644 index 00000000..ac18fb8d --- /dev/null +++ b/doc/elf_fill.3 @@ -0,0 +1,47 @@ +.TH ELF_FILL 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_fill \- set the fill byte for padding in ELF data structures + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "void elf_fill(char " fill );" + +.SH DESCRIPTION +The .B elf_fill function sets the fill byte to be used for padding in ELF data structures. This function can be used to specify the byte value that should be used to fill unused space in sections or other data structures within an ELF file. + +.SH PARAMETERS +.TP +.I fill +A .I char value specifying the byte to be used for padding. + +.SH RETURN VALUE +The .B elf_fill function does not return a value. + +.SH ERRORS +The function does not set any errors. + +.SH EXAMPLES +.B "Example 1: Set the fill byte to 0xFF for padding in ELF data structures" +.nf +.in +4 +#include <libelf.h> + +elf_fill(0xFF); + +// Continue with ELF library operations where padding will use 0xFF +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_flagdata.3 b/doc/elf_flagdata.3 new file mode 100644 index 00000000..eaa79b2c --- /dev/null +++ b/doc/elf_flagdata.3 @@ -0,0 +1,84 @@ +.TH ELF_FLAGDATA 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_flagdata \- set or clear flags for an ELF data descriptor + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "unsigned int elf_flagdata(Elf_Data *" data ", Elf_Cmd " cmd ", unsigned int " flags ");" + +.SH DESCRIPTION +The .B elf_flagdata function sets or clears flags for the data descriptor referred to by .I data in an ELF object. This function can be used to control various aspects of how the data is handled. + +.SH PARAMETERS +.TP +.I data +An .I Elf_Data pointer to the data descriptor for which the flags are to be set or cleared. The data descriptor must be valid. + +.TP +.I cmd +An .I Elf_Cmd value specifying the operation to be performed. This can be one of the following: +.RS +.IP \- ELF_C_SET +Set the specified flags. +.IP \- ELF_C_CLR +Clear the specified flags. +.RE + +.TP +.I flags +An .I unsigned int value specifying the flags to be set or cleared. Possible flags include: +.RS +.IP \- ELF_F_DIRTY +Indicate that the data descriptor has been modified. +.RE + +.SH RETURN VALUE +The .B elf_flagdata function returns the updated flags for the data descriptor. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf_flagdata fails, it sets the following error codes: + +.TP +.B ELFARG +The .I data parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Set the ELF_F_DIRTY flag for an ELF data descriptor" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor +Elf_Data *data = ...; // Assume data is a valid data descriptor + +if (elf_flagdata(data, ELF_C_SET, ELF_F_DIRTY) == 0) { + // Handle error +} else { + // Flag set successfully +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_flagehdr (3), +.BR elf_flagelf (3), +.BR elf_flagphdr (3), +.BR elf_flagscn (3), +.BR elf_flagshdr (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_flagehdr.3 b/doc/elf_flagehdr.3 new file mode 100644 index 00000000..d6d3094d --- /dev/null +++ b/doc/elf_flagehdr.3 @@ -0,0 +1,82 @@ +.TH ELF_FLAGEHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_flagehdr \- set or clear flags for an ELF header + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "unsigned int elf_flagehdr(Elf *" elf ", Elf_Cmd " cmd ", unsigned int " flags ");" + +.SH DESCRIPTION +The .B elf_flagehdr function sets or clears flags for the ELF header of the ELF descriptor referred to by .I elf. This function can be used to control various aspects of how the ELF header is handled. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF descriptor for which the header flags are to be set or cleared. The ELF descriptor must be valid. + +.TP +.I cmd +An .I Elf_Cmd value specifying the operation to be performed. This can be one of the following: +.RS +.IP \- ELF_C_SET +Set the specified flags. +.IP \- ELF_C_CLR +Clear the specified flags. +.RE + +.TP +.I flags +An .I unsigned int value specifying the flags to be set or cleared. Possible flags include: +.RS +.IP \- ELF_F_DIRTY +Indicate that the ELF header has been modified. +.RE + +.SH RETURN VALUE +The .B elf_flagehdr function returns the updated flags for the ELF header. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf_flagehdr fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Set the ELF_F_DIRTY flag for an ELF header" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer + +if (elf_flagehdr(elf, ELF_C_SET, ELF_F_DIRTY) == 0) { + // Handle error +} else { + // Flag set successfully +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_flagdata (3), +.BR elf_flagelf (3), +.BR elf_flagphdr (3), +.BR elf_flagscn (3), +.BR elf_flagshdr (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_flagelf.3 b/doc/elf_flagelf.3 new file mode 100644 index 00000000..469bf2dc --- /dev/null +++ b/doc/elf_flagelf.3 @@ -0,0 +1,84 @@ +.TH ELF_FLAGELF 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_flagelf \- set or clear flags for an ELF descriptor + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "unsigned int elf_flagelf(Elf *" elf ", Elf_Cmd " cmd ", unsigned int " flags ");" + +.SH DESCRIPTION +The .B elf_flagelf function sets or clears flags for the ELF descriptor referred to by .I elf. This function can be used to control various aspects of how the ELF descriptor is handled. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF descriptor for which the flags are to be set or cleared. The ELF descriptor must be valid. + +.TP +.I cmd +An .I Elf_Cmd value specifying the operation to be performed. This can be one of the following: +.RS +.IP \- ELF_C_SET +Set the specified flags. +.IP \- ELF_C_CLR +Clear the specified flags. +.RE + +.TP +.I flags +An .I unsigned int value specifying the flags to be set or cleared. Possible flags include: +.RS +.IP \- ELF_F_DIRTY +Indicate that the ELF descriptor has been modified. +.IP \- ELF_F_LAYOUT +Indicate that the layout of the ELF file should be preserved. +.RE + +.SH RETURN VALUE +The .B elf_flagelf function returns the updated flags for the ELF descriptor. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf_flagelf fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Set the ELF_F_DIRTY flag for an ELF descriptor" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer + +if (elf_flagelf(elf, ELF_C_SET, ELF_F_DIRTY) == 0) { + // Handle error +} else { + // Flag set successfully +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_flagdata (3), +.BR elf_flagehdr (3), +.BR elf_flagphdr (3), +.BR elf_flagscn (3), +.BR elf_flagshdr (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_flagphdr.3 b/doc/elf_flagphdr.3 new file mode 100644 index 00000000..78dffbfa --- /dev/null +++ b/doc/elf_flagphdr.3 @@ -0,0 +1,82 @@ +.TH ELF_FLAGPHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_flagphdr \- set or clear flags for an ELF program header table + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "unsigned int elf_flagphdr(Elf *" elf ", Elf_Cmd " cmd ", unsigned int " flags ");" + +.SH DESCRIPTION +The .B elf_flagphdr function sets or clears flags for the program header table of the ELF descriptor referred to by .I elf. This function can be used to control various aspects of how the program header table is handled. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF descriptor for which the program header table flags are to be set or cleared. The ELF descriptor must be valid. + +.TP +.I cmd +An .I Elf_Cmd value specifying the operation to be performed. This can be one of the following: +.RS +.IP \- ELF_C_SET +Set the specified flags. +.IP \- ELF_C_CLR +Clear the specified flags. +.RE + +.TP +.I flags +An .I unsigned int value specifying the flags to be set or cleared. Possible flags include: +.RS +.IP \- ELF_F_DIRTY +Indicate that the program header table has been modified. +.RE + +.SH RETURN VALUE +The .B elf_flagphdr function returns the updated flags for the program header table. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf_flagphdr fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Set the ELF_F_DIRTY flag for an ELF program header table" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer + +if (elf_flagphdr(elf, ELF_C_SET, ELF_F_DIRTY) == 0) { + // Handle error +} else { + // Flag set successfully +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_flagdata (3), +.BR elf_flagehdr (3), +.BR elf_flagelf (3), +.BR elf_flagscn (3), +.BR elf_flagshdr (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_flagscn.3 b/doc/elf_flagscn.3 new file mode 100644 index 00000000..cad01497 --- /dev/null +++ b/doc/elf_flagscn.3 @@ -0,0 +1,83 @@ +.TH ELF_FLAGSCN 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_flagscn \- set or clear flags for an ELF section + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "unsigned int elf_flagscn(Elf_Scn *" scn ", Elf_Cmd " cmd ", unsigned int " flags ");" + +.SH DESCRIPTION +The .B elf_flagscn function sets or clears flags for the section referred to by .I scn in an ELF object. This function can be used to control various aspects of how the section is handled. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor for which the flags are to be set or cleared. The section descriptor must be valid. + +.TP +.I cmd +An .I Elf_Cmd value specifying the operation to be performed. This can be one of the following: +.RS +.IP \- ELF_C_SET +Set the specified flags. +.IP \- ELF_C_CLR +Clear the specified flags. +.RE + +.TP +.I flags +An .I unsigned int value specifying the flags to be set or cleared. Possible flags include: +.RS +.IP \- ELF_F_DIRTY +Indicate that the section has been modified. +.RE + +.SH RETURN VALUE +The .B elf_flagscn function returns the updated flags for the section. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf_flagscn fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Set the ELF_F_DIRTY flag for an ELF section" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +if (elf_flagscn(scn, ELF_C_SET, ELF_F_DIRTY) == 0) { + // Handle error +} else { + // Flag set successfully +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_flagdata (3), +.BR elf_flagehdr (3), +.BR elf_flagelf (3), +.BR elf_flagphdr (3), +.BR elf_flagshdr (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_flagshdr.3 b/doc/elf_flagshdr.3 new file mode 100644 index 00000000..0a56301c --- /dev/null +++ b/doc/elf_flagshdr.3 @@ -0,0 +1,83 @@ +.TH ELF_FLAGSHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_flagshdr \- set or clear flags for an ELF section header + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "unsigned int elf_flagshdr(Elf_Scn *" scn ", Elf_Cmd " cmd ", unsigned int " flags ");" + +.SH DESCRIPTION +The .B elf_flagshdr function sets or clears flags for the section header of the section descriptor referred to by .I scn in an ELF object. This function can be used to control various aspects of how the section header is handled. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor for which the section header flags are to be set or cleared. The section descriptor must be valid. + +.TP +.I cmd +An .I Elf_Cmd value specifying the operation to be performed. This can be one of the following: +.RS +.IP \- ELF_C_SET +Set the specified flags. +.IP \- ELF_C_CLR +Clear the specified flags. +.RE + +.TP +.I flags +An .I unsigned int value specifying the flags to be set or cleared. Possible flags include: +.RS +.IP \- ELF_F_DIRTY +Indicate that the section header has been modified. +.RE + +.SH RETURN VALUE +The .B elf_flagshdr function returns the updated flags for the section header. If an error occurs, it returns 0 and sets an appropriate error code. + +.SH ERRORS +If .B elf_flagshdr fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Set the ELF_F_DIRTY flag for an ELF section header" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +if (elf_flagshdr(scn, ELF_C_SET, ELF_F_DIRTY) == 0) { + // Handle error +} else { + // Flag set successfully +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_flagdata (3), +.BR elf_flagehdr (3), +.BR elf_flagelf (3), +.BR elf_flagphdr (3), +.BR elf_flagscn (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_getarhdr.3 b/doc/elf_getarhdr.3 new file mode 100644 index 00000000..6b584d23 --- /dev/null +++ b/doc/elf_getarhdr.3 @@ -0,0 +1,65 @@ +.TH ELF_GETARHDR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_getarhdr \- retrieve the archive header for an ELF archive member + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Arhdr *elf_getarhdr(Elf *" elf ");" + +.SH DESCRIPTION +The .B elf_getarhdr function retrieves the archive header for the current member of the ELF archive referred to by .I elf. This function is used to access metadata about the archive member, such as its name, date, user ID, group ID, mode, and size. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF archive member for which the archive header is to be retrieved. The ELF archive member must be valid. + +.SH RETURN VALUE +The .B elf_getarhdr function returns a pointer to an .I Elf_Arhdr structure representing the archive header. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_getarhdr fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the archive header for an ELF archive member" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer for an archive member + +Elf_Arhdr *arhdr = elf_getarhdr(elf); +if (arhdr == NULL) { + // Handle error +} else { + // Use the retrieved archive header + printf("Member name: %s\n", arhdr->ar_name); + printf("Member size: %ld\n", arhdr->ar_size); +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_begin (3), +.BR elf_next (3), +.BR elf_end (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_getaroff.3 b/doc/elf_getaroff.3 new file mode 100644 index 00000000..6670d111 --- /dev/null +++ b/doc/elf_getaroff.3 @@ -0,0 +1,64 @@ +.TH ELF_GETAROFF 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_getaroff \- retrieve the offset of the current archive member in an ELF archive + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "off_t elf_getaroff(Elf *" elf ");" + +.SH DESCRIPTION +The .B elf_getaroff function retrieves the file offset of the current archive member within the ELF archive referred to by .I elf. This offset is the position in the archive file where the header of the current member begins. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF archive from which the offset of the current archive member is to be retrieved. The ELF archive must be valid. + +.SH RETURN VALUE +The .B elf_getaroff function returns the offset of the current archive member on success. If an error occurs, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf_getaroff fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the offset of the current archive member in an ELF archive" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer for an archive + +off_t offset = elf_getaroff(elf); +if (offset == -1) { + // Handle error +} else { + printf("Offset of current archive member: %ld\n", offset); +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_getarhdr (3), +.BR elf_begin (3), +.BR elf_next (3), +.BR elf_end (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_getarsym.3 b/doc/elf_getarsym.3 new file mode 100644 index 00000000..f0b83c58 --- /dev/null +++ b/doc/elf_getarsym.3 @@ -0,0 +1,75 @@ +.TH ELF_GETARSYM 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_getarsym \- retrieve the archive symbol table for an ELF archive + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Arsym *elf_getarsym(Elf *" elf ", size_t *" ptr ", size_t *" nsyms ");" + +.SH DESCRIPTION +The .B elf_getarsym function retrieves the archive symbol table for the ELF archive referred to by .I elf. The function returns an array of .I Elf_Arsym structures, which provide information about the symbols in the archive. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF archive from which the symbol table is to be retrieved. The ELF archive must be valid. + +.TP +.I ptr +A pointer to a .I size_t variable where the number of bytes used to store the symbol table will be stored. If .I ptr is NULL, this information is not returned. + +.TP +.I nsyms +A pointer to a .I size_t variable where the number of symbols in the symbol table will be stored. If .I nsyms is NULL, this information is not returned. + +.SH RETURN VALUE +The .B elf_getarsym function returns a pointer to an array of .I Elf_Arsym structures on success. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_getarsym fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the archive symbol table for an ELF archive" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer for an archive +size_t nsyms; + +Elf_Arsym *arsym = elf_getarsym(elf, NULL, &nsyms); +if (arsym == NULL) { + // Handle error +} else { + for (size_t i = 0; i < nsyms; ++i) { + printf("Symbol: %s, Offset: %zu\n", arsym[i].as_name, arsym[i].as_off); + } +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_getarhdr (3), +.BR elf_begin (3), +.BR elf_next (3), +.BR elf_end (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_getbase.3 b/doc/elf_getbase.3 new file mode 100644 index 00000000..30e3144b --- /dev/null +++ b/doc/elf_getbase.3 @@ -0,0 +1,63 @@ +.TH ELF_GETBASE 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf_getbase \- retrieve the base offset of an ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +off_t elf_getbase(Elf *elf); +.fi + +.SH DESCRIPTION +.B elf_getbase +returns the base offset of the ELF descriptor +.I elf. +This base offset is the position within the file where the ELF data begins. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor whose base offset is to be determined. + +.SH RETURN VALUE +On success, +.B elf_getbase +returns the base offset as an +.B off_t +value. If the ELF descriptor is invalid, it returns -1. + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_READ, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + off_t base = elf_getbase(elf); + if (base == -1) { + printf("Error retrieving base offset: %s\n", elf_errmsg(-1)); + } else { + printf("Base offset: %ld\n", base); + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf_getbase +first appeared in elfutils 0.186. + diff --git a/doc/elf_getdata_rawchunck.3 b/doc/elf_getdata_rawchunck.3 new file mode 100644 index 00000000..2bb9590c --- /dev/null +++ b/doc/elf_getdata_rawchunck.3 @@ -0,0 +1,82 @@ +.TH ELF_GETDATA_RAWCHUNK 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_getdata_rawchunk \- retrieve a raw data chunk from an ELF object + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf_getdata_rawchunk(Elf *" elf ", off_t " offset ", size_t " size ", unsigned int " type ", Elf_Data *" data ");" + +.SH DESCRIPTION +The .B elf_getdata_rawchunk function retrieves a raw data chunk from the ELF object referred to by .I elf. The data chunk is specified by its file offset, size, and type, and is returned in the .I data structure provided by the caller. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object from which the raw data chunk is to be retrieved. The ELF object must be valid. + +.TP +.I offset +An .I off_t value specifying the offset in the file where the data chunk begins. + +.TP +.I size +A .I size_t value specifying the size of the data chunk to be retrieved. + +.TP +.I type +An .I unsigned int value specifying the type of data chunk. This parameter can be used to specify different types of data (e.g., section data, segment data). + +.TP +.I data +An .I Elf_Data pointer to a data structure where the retrieved raw data chunk will be stored. + +.SH RETURN VALUE +The .B elf_getdata_rawchunk function returns 0 on success. On error, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf_getdata_rawchunk fails, it sets the following error codes: + +.TP +.B ELFARG +One or more of the parameters are NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve a raw data chunk from an ELF object" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +off_t offset = ...; // Specify a valid offset +size_t size = ...; // Specify a valid size +unsigned int type = ...; // Specify a valid type +Elf_Data data; + +if (elf_getdata_rawchunk(elf, offset, size, type, &data) != 0) { + // Handle error +} else { + // Process the raw data chunk +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_getscn (3), +.BR elf_getdata (3), +.BR elf_rawdata (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_getident.3 b/doc/elf_getident.3 new file mode 100644 index 00000000..30a49be6 --- /dev/null +++ b/doc/elf_getident.3 @@ -0,0 +1,74 @@ +.TH ELF_GETIDENT 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf_getident \- retrieve the identification bytes for an ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +char *elf_getident(Elf *elf, size_t *size); +.fi + +.SH DESCRIPTION +.B elf_getident +returns a pointer to the identification bytes of the ELF descriptor +.I elf. +The identification bytes are part of the ELF file's header, which includes important metadata about the file format. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor from which to retrieve the identification bytes. +.TP +.I size +Pointer to a +.B size_t +variable where the size of the identification bytes will be stored. If +.I size +is NULL, no size will be stored. + +.SH RETURN VALUE +On success, +.B elf_getident +returns a pointer to the identification bytes. If the ELF descriptor is invalid, it returns NULL and sets an error code retrievable by +.BR elf_errno (3). + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_READ, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + size_t size; + char *ident = elf_getident(elf, &size); + if (ident == NULL) { + printf("Error retrieving identification bytes: %s\n", elf_errmsg(-1)); + } else { + printf("Identification bytes (size %zu): ", size); + for (size_t i = 0; i < size; i++) { + printf("%02x ", (unsigned char)ident[i]); + } + printf("\n"); + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf_getident +first appeared in elfutils 0.186. + diff --git a/doc/elf_getphdrnum.3 b/doc/elf_getphdrnum.3 new file mode 100644 index 00000000..52322d77 --- /dev/null +++ b/doc/elf_getphdrnum.3 @@ -0,0 +1,69 @@ +.TH ELF_GETPHDRNUM 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf_getphdrnum \- retrieve the number of program headers in an ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +int elf_getphdrnum(Elf *elf, size_t *phnum); +.fi + +.SH DESCRIPTION +.B elf_getphdrnum +retrieves the number of program headers associated with the ELF descriptor +.I elf. +The function stores the number of program headers in the variable pointed to by +.I phnum. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor from which to retrieve the number of program headers. +.TP +.I phnum +Pointer to a +.B size_t +variable where the number of program headers will be stored. + +.SH RETURN VALUE +On success, +.B elf_getphdrnum +returns 0. On failure, it returns -1 and sets an error code retrievable by +.BR elf_errno (3). + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_READ, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + size_t phnum; + if (elf_getphdrnum(elf, &phnum) != 0) { + printf("Error retrieving program header number: %s\n", elf_errmsg(-1)); + } else { + printf("Number of program headers: %zu\n", phnum); + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf_errmsg (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf_getphdrnum +first appeared in elfutils 0.186. + diff --git a/doc/elf_getscn.3 b/doc/elf_getscn.3 new file mode 100644 index 00000000..ef0dc1ba --- /dev/null +++ b/doc/elf_getscn.3 @@ -0,0 +1,71 @@ +.TH ELF_GETSCN 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_getscn \- retrieve a section descriptor for an ELF file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Scn *elf_getscn(Elf *" elf ", size_t " index ");" + +.SH DESCRIPTION +The .B elf_getscn function retrieves a section descriptor for the section at the specified index in the ELF object referred to by .I elf. + +Sections in an ELF file contain various types of data, such as program code, symbol tables, and relocation information. Each section is described by an .I Elf_Scn structure. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object from which the section descriptor is to be retrieved. + +.TP +.I index +A .I size_t value representing the index of the section whose descriptor is to be retrieved. Section indices start at 0. + +.SH RETURN VALUE +The .B elf_getscn function returns a pointer to the .I Elf_Scn structure for the section at the specified index. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_getscn fails, it sets the following error codes: + +.TP +.B ELFMEM +Memory allocation failed. + +.TP +.B ELFARG +The .I elf parameter is NULL, or .I index is out of range. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the section descriptor for the first section" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +size_t index = 1; + +Elf_Scn *scn = elf_getscn(elf, index); +if (scn == NULL) { + // Handle error +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_nextscn (3), +.BR elf_getshdr (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_getshdrnum.3 b/doc/elf_getshdrnum.3 new file mode 100644 index 00000000..6fe2187c --- /dev/null +++ b/doc/elf_getshdrnum.3 @@ -0,0 +1,67 @@ +.TH ELF_GETSHDRNUM 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_getshdrnum \- retrieve the number of section headers in an ELF file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf_getshdrnum(Elf *" elf ", size_t *" shnum ");" + +.SH DESCRIPTION +The .B elf_getshdrnum function retrieves the number of section headers in the ELF object referred to by .I elf. The number of section headers is stored in the location pointed to by .I shnum. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object from which the number of section headers is to be retrieved. + +.TP +.I shnum +A pointer to a .I size_t variable where the number of section headers will be stored. + +.SH RETURN VALUE +The .B elf_getshdrnum function returns 0 on success. On error, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf_getshdrnum fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf or .I shnum parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the number of section headers in an ELF file" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +size_t shnum; + +if (elf_getshdrnum(elf, &shnum) != 0) { + // Handle error +} else { + // Use shnum +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getshdr (3), +.BR elf_getshdrstrndx (3), +.BR elf_getscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_getshdrstrndx.3 b/doc/elf_getshdrstrndx.3 new file mode 100644 index 00000000..97c2dc2d --- /dev/null +++ b/doc/elf_getshdrstrndx.3 @@ -0,0 +1,67 @@ +.TH ELF_GETSHDRSTRNDX 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_getshdrstrndx \- retrieve the section header string table index for an ELF file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf_getshdrstrndx(Elf *" elf ", size_t *" strndx ");" + +.SH DESCRIPTION +The .B elf_getshdrstrndx function retrieves the section header string table index for the ELF object referred to by .I elf. The section header string table index is stored in the location pointed to by .I strndx. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object from which the section header string table index is to be retrieved. + +.TP +.I strndx +A pointer to a .I size_t variable where the section header string table index will be stored. + +.SH RETURN VALUE +The .B elf_getshdrstrndx function returns 0 on success. On error, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf_getshdrstrndx fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf or .I strndx parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the section header string table index in an ELF file" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +size_t strndx; + +if (elf_getshdrstrndx(elf, &strndx) != 0) { + // Handle error +} else { + // Use strndx +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getshdrnum (3), +.BR elf_getshdr (3), +.BR elf_getscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_gnu_hash.3 b/doc/elf_gnu_hash.3 new file mode 100644 index 00000000..8cd4d1c3 --- /dev/null +++ b/doc/elf_gnu_hash.3 @@ -0,0 +1,49 @@ +.TH ELF_GNU_HASH 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_gnu_hash \- compute a GNU-style hash value for a string + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "unsigned long elf_gnu_hash(const char *" name ");" + +.SH DESCRIPTION +The .B elf_gnu_hash function computes a GNU-style hash value for the specified string .I name. This hash function is used for hashing symbol names in ELF files that use the GNU hash table format. + +.SH PARAMETERS +.TP +.I name +A constant .I char pointer to the null-terminated string for which the hash value is to be computed. + +.SH RETURN VALUE +The .B elf_gnu_hash function returns an .I unsigned long value representing the GNU-style hash of the specified string. + +.SH ERRORS +The function does not set any errors. + +.SH EXAMPLES +.B "Example 1: Compute the GNU-style hash value for a symbol name" +.nf +.in +4 +#include <libelf.h> +#include <stdio.h> + +const char *symbol_name = "my_symbol"; +unsigned long hash_value = elf_gnu_hash(symbol_name); +printf("GNU hash value for '%s': %lu\n", symbol_name, hash_value); +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_hash (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_hash.3 b/doc/elf_hash.3 new file mode 100644 index 00000000..86b2d15b --- /dev/null +++ b/doc/elf_hash.3 @@ -0,0 +1,48 @@ +.TH ELF_HASH 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_hash \- compute a hash value for a string + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "unsigned long elf_hash(const char *" name ");" + +.SH DESCRIPTION +The .B elf_hash function computes a hash value for the specified string .I name. This hash function is commonly used to hash symbol names in ELF files. + +.SH PARAMETERS +.TP +.I name +A constant .I char pointer to the null-terminated string for which the hash value is to be computed. + +.SH RETURN VALUE +The .B elf_hash function returns an .I unsigned long value representing the hash of the specified string. + +.SH ERRORS +The function does not set any errors. + +.SH EXAMPLES +.B "Example 1: Compute the hash value for a symbol name" +.nf +.in +4 +#include <libelf.h> +#include <stdio.h> + +const char *symbol_name = "my_symbol"; +unsigned long hash_value = elf_hash(symbol_name); +printf("Hash value for '%s': %lu\n", symbol_name, hash_value); +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_kind.3 b/doc/elf_kind.3 new file mode 100644 index 00000000..f59357ce --- /dev/null +++ b/doc/elf_kind.3 @@ -0,0 +1,77 @@ +.TH ELF_KIND 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf_kind \- get the kind of an ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +Elf_Kind elf_kind(Elf *elf); +.fi + +.SH DESCRIPTION +.B elf_kind +returns the kind of the ELF descriptor +.I elf. +The kind indicates whether the descriptor refers to an executable, a shared object, a core file, or other types of ELF files. + +.SH PARAMETERS +.TP +.I elf +Pointer to the ELF descriptor whose kind is to be determined. + +.SH RETURN VALUE +.B elf_kind +returns one of the following constants defined in <libelf.h>: +.TP +.B ELF_K_NONE +The ELF descriptor is not valid. +.TP +.B ELF_K_AR +The descriptor refers to an archive. +.TP +.B ELF_K_ELF +The descriptor refers to an ELF file. +.TP +.B ELF_K_NUM +The number of ELF kinds defined. + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_READ, NULL); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} else { + Elf_Kind kind = elf_kind(elf); + switch (kind) { + case ELF_K_ELF: + printf("This is an ELF file.\n"); + break; + case ELF_K_AR: + printf("This is an archive.\n"); + break; + default: + printf("Unknown ELF kind.\n"); + } + elf_end(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf_kind +first appeared in elfutils 0.186. + diff --git a/doc/elf_memory.3 b/doc/elf_memory.3 new file mode 100644 index 00000000..af4c0267 --- /dev/null +++ b/doc/elf_memory.3 @@ -0,0 +1,60 @@ +.TH ELF_MEMORY 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf_memory \- initialize an ELF descriptor for an in-memory ELF object + +.SH SYNOPSIS +.nf +#include <libelf.h> + +Elf *elf_memory(char *image, size_t size); +.fi + +.SH DESCRIPTION +.B elf_memory +creates and initializes an ELF descriptor for an ELF object stored in memory. The function takes two arguments: +.TP +.I image +Pointer to the memory location where the ELF image is stored. +.TP +.I size +The size of the ELF image in bytes. + +This function allows manipulation of ELF data that is not associated with a file, but rather exists entirely in memory. + +.SH RETURN VALUE +On success, +.B elf_memory +returns a pointer to the +.B Elf +structure. On failure, it returns NULL and sets an error code retrievable by +.BR elf_errno (3). + +.SH EXAMPLES +.nf +char *elf_data = ...; // ELF data in memory +size_t elf_size = ...; // Size of the ELF data +Elf *elf = elf_memory(elf_data, elf_size); +if (elf == NULL) { + printf("Error: %s\n", elf_errmsg(-1)); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf_errmsg (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf_memory +first appeared in elfutils 0.186. + diff --git a/doc/elf_ndxscn.3 b/doc/elf_ndxscn.3 new file mode 100644 index 00000000..750b1619 --- /dev/null +++ b/doc/elf_ndxscn.3 @@ -0,0 +1,61 @@ +.TH ELF_NDXSCN 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_ndxscn \- retrieve the index of a section descriptor for an ELF file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "size_t elf_ndxscn(Elf_Scn *" scn ");" + +.SH DESCRIPTION +The .B elf_ndxscn function retrieves the index of the section descriptor referred to by .I scn within the ELF object. Section indices are used to identify sections in an ELF file. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor whose index is to be retrieved. The section descriptor must be valid. + +.SH RETURN VALUE +The .B elf_ndxscn function returns the index of the section descriptor. If an error occurs, it returns .B SHN_UNDEF. + +.SH ERRORS +If .B elf_ndxscn fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the index of a section descriptor" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +size_t index = elf_ndxscn(scn); +if (index == SHN_UNDEF) { + // Handle error +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf_nextscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_newdata.3 b/doc/elf_newdata.3 new file mode 100644 index 00000000..f7f522fd --- /dev/null +++ b/doc/elf_newdata.3 @@ -0,0 +1,64 @@ +.TH ELF_NEWDATA 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_newdata \- create a new data descriptor for an ELF section + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Data *elf_newdata(Elf_Scn *" scn ");" + +.SH DESCRIPTION +The .B elf_newdata function creates a new data descriptor for the section descriptor referred to by .I scn in an ELF object. This new data descriptor can be used to add or modify the contents of the section. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor for which a new data descriptor is to be created. The section descriptor must be valid. + +.SH RETURN VALUE +The .B elf_newdata function returns a pointer to the newly created .I Elf_Data structure representing the data descriptor. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_newdata fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Create a new data descriptor for a section" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +Elf_Data *data = elf_newdata(scn); +if (data == NULL) { + // Handle error +} else { + // Use the new data descriptor +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_getscn (3), +.BR elf_getdata (3), +.BR elf_rawdata (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_newscn.3 b/doc/elf_newscn.3 new file mode 100644 index 00000000..bee4e6ce --- /dev/null +++ b/doc/elf_newscn.3 @@ -0,0 +1,67 @@ +.TH ELF_NEWSCN 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_newscn \- create a new section descriptor for an ELF file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Scn *elf_newscn(Elf *" elf ");" + +.SH DESCRIPTION +The .B elf_newscn function creates a new section descriptor for the ELF object referred to by .I elf. This new section is added to the end of the section list for the ELF object. + +Sections in an ELF file contain various types of data, such as program code, symbol tables, and relocation information. This function allows the creation of additional sections in an ELF file. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object to which a new section is to be added. + +.SH RETURN VALUE +The .B elf_newscn function returns a pointer to the .I Elf_Scn structure for the new section. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_newscn fails, it sets the following error codes: + +.TP +.B ELFMEM +Memory allocation failed. + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Create a new section in an ELF file" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer + +Elf_Scn *scn = elf_newscn(elf); +if (scn == NULL) { + // Handle error +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf_nextscn (3), +.BR elf_ndxscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_next.3 b/doc/elf_next.3 new file mode 100644 index 00000000..68275d92 --- /dev/null +++ b/doc/elf_next.3 @@ -0,0 +1,55 @@ +.TH ELF_NEXT 3 "May 2024" "elfutils 0.186" "Library Functions Manual" +.SH NAME +elf_next \- advance to the next ELF descriptor + +.SH SYNOPSIS +.nf +#include <libelf.h> + +Elf *elf_next(Elf *elf); +.fi + +.SH DESCRIPTION +.B elf_next +advances to the next ELF descriptor associated with the current ELF descriptor. This function is used when processing multiple ELF descriptors within the same ELF file. + +The function takes one argument: +.TP +.I elf +Pointer to the current ELF descriptor. + +.SH RETURN VALUE +On success, +.B elf_next +returns a pointer to the next +.B Elf +structure. If there are no more descriptors, it returns NULL. + +.SH EXAMPLES +.nf +Elf *elf = elf_begin(fd, ELF_C_READ, NULL); +while (elf != NULL) { + // Process the current ELF descriptor + elf = elf_next(elf); +} +.fi + +.SH SEE ALSO +.BR elf_begin (3), +.BR elf_end (3), +.BR elf_errmsg (3), +.BR elf (5) + +.SH AUTHOR +Written by the elfutils development team. + +.SH REPORTING BUGS +Report bugs to <[email protected]>. + +.SH COPYRIGHT +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH HISTORY +.B elf_next +first appeared in elfutils 0.186. + diff --git a/doc/elf_nextscn.3 b/doc/elf_nextscn.3 new file mode 100644 index 00000000..b403d800 --- /dev/null +++ b/doc/elf_nextscn.3 @@ -0,0 +1,68 @@ +.TH ELF_NEXTSCN 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_nextscn \- retrieve the next section descriptor for an ELF file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Scn *elf_nextscn(Elf *" elf ", Elf_Scn *" scn ");" + +.SH DESCRIPTION +The .B elf_nextscn function retrieves the section descriptor for the section following the one referred to by .I scn within the ELF object referred to by .I elf. + +If .I scn is NULL, .B elf_nextscn returns the first section descriptor for the ELF object. + +Sections in an ELF file contain various types of data, such as program code, symbol tables, and relocation information. This function allows iteration through all the sections in an ELF file. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object from which the section descriptor is to be retrieved. + +.TP +.I scn +An .I Elf_Scn pointer to the current section descriptor. If NULL, the function returns the first section descriptor. + +.SH RETURN VALUE +The .B elf_nextscn function returns a pointer to the .I Elf_Scn structure for the next section. If there are no more sections, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_nextscn fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Iterate through all section descriptors in an ELF file" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = NULL; + +while ((scn = elf_nextscn(elf, scn)) != NULL) { + // Process each section descriptor +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf_ndxscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_rand.3 b/doc/elf_rand.3 new file mode 100644 index 00000000..f110c7a9 --- /dev/null +++ b/doc/elf_rand.3 @@ -0,0 +1,69 @@ +.TH ELF_RAND 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_rand \- set the archive member position for an ELF descriptor + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "int elf_rand(Elf *" elf ", off_t " offset ");" + +.SH DESCRIPTION +The .B elf_rand function sets the archive member position for the ELF descriptor referred to by .I elf to the archive member at the specified file offset .I offset. This function allows random access to archive members within an ELF archive. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF descriptor representing the archive. + +.TP +.I offset +An .I off_t value specifying the file offset of the archive member to set as the current member. + +.SH RETURN VALUE +The .B elf_rand function returns 0 on success. If an error occurs, it returns -1 and sets an appropriate error code. + +.SH ERRORS +If .B elf_rand fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid, or the .I offset parameter is invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Set the archive member position in an ELF archive" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer for an archive +off_t offset = ...; // Specify a valid offset + +if (elf_rand(elf, offset) != 0) { + // Handle error +} else { + // The current archive member is now set to the member at the specified offset +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_getarhdr (3), +.BR elf_getaroff (3), +.BR elf_begin (3), +.BR elf_next (3), +.BR elf_end (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_rawdata.3 b/doc/elf_rawdata.3 new file mode 100644 index 00000000..7c19bc40 --- /dev/null +++ b/doc/elf_rawdata.3 @@ -0,0 +1,68 @@ +.TH ELF_RAWDATA 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_rawdata \- retrieve raw data from an ELF section + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "Elf_Data *elf_rawdata(Elf_Scn *" scn ", Elf_Data *" data ");" + +.SH DESCRIPTION +The .B elf_rawdata function retrieves the raw, unprocessed data from the section descriptor referred to by .I scn in an ELF object. If .I data is NULL, the function returns the first data descriptor for the section. If .I data is not NULL, the function returns the next data descriptor following .I data in the section. + +This function is useful for accessing the raw contents of a section, as it exists in the ELF file, without any processing or interpretation. + +.SH PARAMETERS +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor from which the raw data is to be retrieved. The section descriptor must be valid. + +.TP +.I data +An .I Elf_Data pointer to the current data descriptor. If NULL, the function returns the first data descriptor for the section. If not NULL, the function returns the next data descriptor following this one in the section. + +.SH RETURN VALUE +The .B elf_rawdata function returns a pointer to the .I Elf_Data structure representing the raw data descriptor. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_rawdata fails, it sets the following error codes: + +.TP +.B ELFARG +The .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve all raw data descriptors for a section" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor +Elf_Data *data = NULL; + +while ((data = elf_rawdata(scn, data)) != NULL) { + // Process each raw data descriptor +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_getscn (3), +.BR elf_getdata (3), +.BR elf_newdata (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_rawfile.3 b/doc/elf_rawfile.3 new file mode 100644 index 00000000..eef0a639 --- /dev/null +++ b/doc/elf_rawfile.3 @@ -0,0 +1,68 @@ +.TH ELF_RAWFILE 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_rawfile \- retrieve the raw ELF file data + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "char *elf_rawfile(Elf *" elf ", size_t *" size ");" + +.SH DESCRIPTION +The .B elf_rawfile function retrieves a pointer to the raw data of the ELF file referred to by .I elf. It also optionally returns the size of the raw data. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF descriptor for which the raw file data is to be retrieved. The ELF descriptor must be valid. + +.TP +.I size +A pointer to a .I size_t variable where the size of the raw data will be stored. If .I size is NULL, the size information is not returned. + +.SH RETURN VALUE +The .B elf_rawfile function returns a pointer to the raw data of the ELF file. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_rawfile fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the raw data of an ELF file" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +size_t size; + +char *data = elf_rawfile(elf, &size); +if (data == NULL) { + // Handle error +} else { + // Use the raw data + printf("Size of raw data: %zu\n", size); +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_begin (3), +.BR elf_end (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_scnshndx.3 b/doc/elf_scnshndx.3 new file mode 100644 index 00000000..79c98422 --- /dev/null +++ b/doc/elf_scnshndx.3 @@ -0,0 +1,66 @@ +.TH ELF_SCNSHNDX 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_scnshndx \- retrieve the extended section index for a section descriptor in an ELF file + +.SH SYNOPSIS +.B #include <gelf.h> + +.BI "size_t elf_scnshndx(Elf *" elf ", Elf_Scn *" scn ");" + +.SH DESCRIPTION +The .B elf_scnshndx function retrieves the extended section index for the section descriptor referred to by .I scn within the ELF object referred to by .I elf. This is used in cases where the section index exceeds the size that can be represented in a 16-bit value. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object containing the section descriptor. + +.TP +.I scn +An .I Elf_Scn pointer to the section descriptor whose extended section index is to be retrieved. + +.SH RETURN VALUE +The .B elf_scnshndx function returns the extended section index of the section descriptor. If an error occurs, it returns .B SHN_UNDEF and sets an appropriate error code. + +.SH ERRORS +If .B elf_scnshndx fails, it sets the following error codes: + +.TP +.B ELFARG +The .I elf or .I scn parameter is NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.SH EXAMPLES +.B "Example 1: Retrieve the extended section index of a section descriptor" +.nf +.in +4 +#include <gelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +Elf_Scn *scn = ...; // Assume scn is a valid section descriptor + +size_t index = elf_scnshndx(elf, scn); +if (index == SHN_UNDEF) { + // Handle error +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf_getscn (3), +.BR elf_ndxscn (3), +.BR elf_nextscn (3), +.BR elf (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + diff --git a/doc/elf_strptr.3 b/doc/elf_strptr.3 new file mode 100644 index 00000000..45f2c52c --- /dev/null +++ b/doc/elf_strptr.3 @@ -0,0 +1,76 @@ +.TH ELF_STRPTR 3 "June 2024" "Elfutils" "Library Functions Manual" + +.SH NAME +elf_strptr \- retrieve a string from a string table in an ELF file + +.SH SYNOPSIS +.B #include <libelf.h> + +.BI "char *elf_strptr(Elf *" elf ", size_t " section_index ", size_t " offset ");" + +.SH DESCRIPTION +The .B elf_strptr function retrieves a pointer to a string located at a specified offset within a specified section, typically a string table, in the ELF object referred to by .I elf. + +.SH PARAMETERS +.TP +.I elf +An .I Elf pointer to the ELF object from which the string is to be retrieved. The ELF object must be valid. + +.TP +.I section_index +A .I size_t value specifying the index of the section containing the string table. + +.TP +.I offset +A .I size_t value specifying the offset within the string table where the string is located. + +.SH RETURN VALUE +The .B elf_strptr function returns a pointer to the string located at the specified offset within the specified section. If an error occurs, it returns NULL and sets an appropriate error code. + +.SH ERRORS +If .B elf_strptr fails, it sets the following error codes: + +.TP +.B ELFARG +One or more of the parameters are NULL or invalid. + +.TP +.B ELFERR +An unspecified internal error occurred. + +.TP +.B ELFNOTFOUND +The specified section or string was not found. + +.SH EXAMPLES +.B "Example 1: Retrieve a string from a string table in an ELF object" +.nf +.in +4 +#include <libelf.h> + +Elf *elf = ...; // Assume elf is a valid Elf pointer +size_t section_index = ...; // Specify a valid section index +size_t offset = ...; // Specify a valid offset + +char *str = elf_strptr(elf, section_index, offset); +if (str == NULL) { + // Handle error +} else { + // Use the retrieved string +} +.in -4 +.fi + +.SH SEE ALSO +.BR elf (3), +.BR elf_getscn (3), +.BR elf_getdata (3), +.BR libelf (3) + +.SH AUTHORS +Elfutils was written by the Elfutils development team. + +.SH COPYRIGHT +Copyright © 2024 Elfutils Development Team. +This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + |