1/* Interfaces for libdwelf. DWARF ELF Low-level Functions. 2 Copyright (C) 2014, 2015, 2016, 2018 Red Hat, Inc. 3 This file is part of elfutils. 4 5 This file is free software; you can redistribute it and/or modify 6 it under the terms of either 7 8 * the GNU Lesser General Public License as published by the Free 9 Software Foundation; either version 3 of the License, or (at 10 your option) any later version 11 12 or 13 14 * the GNU General Public License as published by the Free 15 Software Foundation; either version 2 of the License, or (at 16 your option) any later version 17 18 or both in parallel, as here. 19 20 elfutils is distributed in the hope that it will be useful, but 21 WITHOUT ANY WARRANTY; without even the implied warranty of 22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 23 General Public License for more details. 24 25 You should have received copies of the GNU General Public License and 26 the GNU Lesser General Public License along with this program. If 27 not, see <http://www.gnu.org/licenses/>. */ 28 29#ifndef _LIBDWELF_H 30#define _LIBDWELF_H 1 31 32#include "libdw.h" 33 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38/* DWARF ELF Low-level Functions (dwelf). 39 Functions starting with dwelf_elf will take a (libelf) Elf object as 40 first argument and might set elf_errno on error. Functions starting 41 with dwelf_dwarf will take a (libdw) Dwarf object as first argument 42 and might set dwarf_errno on error. */ 43 44/* Returns the name and the CRC32 of the separate debug file from the 45 .gnu_debuglink section if found in the ELF. Return NULL if the ELF 46 file didn't have a .gnu_debuglink section, had malformed data in the 47 section or some other error occurred. */ 48extern const char *dwelf_elf_gnu_debuglink (Elf *elf, GElf_Word *crc); 49 50/* Returns the name and build ID from the .gnu_debugaltlink section if 51 found in the ELF. On success, pointers to the name and build ID 52 are written to *NAMEP and *BUILDID_P, and the positive length of 53 the build ID is returned. Returns 0 if the ELF lacks a 54 .gnu_debugaltlink section. Returns -1 in case of malformed data or 55 other errors. */ 56extern ssize_t dwelf_dwarf_gnu_debugaltlink (Dwarf *dwarf, 57 const char **namep, 58 const void **build_idp); 59 60/* Returns the build ID as found in a NT_GNU_BUILD_ID note from either 61 a SHT_NOTE section or from a PT_NOTE segment if the ELF file 62 doesn't contain any section headers. On success a pointer to the 63 build ID is written to *BUILDID_P, and the positive length of the 64 build ID is returned. Returns 0 if the ELF lacks a NT_GNU_BUILD_ID 65 note. Returns -1 in case of malformed data or other errors. */ 66extern ssize_t dwelf_elf_gnu_build_id (Elf *elf, const void **build_idp); 67 68/* Returns the size of the uncompressed data of a GNU compressed 69 section. The section name should start with .zdebug (but this 70 isn't checked by this function). If the section isn't compressed 71 (the section data doesn't start with ZLIB) -1 is returned. If an 72 error occurred -1 is returned and elf_errno is set. */ 73extern ssize_t dwelf_scn_gnu_compressed_size (Elf_Scn *scn); 74 75/* ELF/DWARF string table handling. */ 76typedef struct Dwelf_Strtab Dwelf_Strtab; 77typedef struct Dwelf_Strent Dwelf_Strent; 78 79/* Create a new ELF/DWARF string table object in memory. ELF string 80 tables have a required zero length null string at offset zero. 81 DWARF string tables don't require such a null entry (unless they 82 are shared with an ELF string table). If NULLSTR is true then a 83 null entry is always created (even if the string table is empty 84 otherwise). */ 85extern Dwelf_Strtab *dwelf_strtab_init (bool nullstr); 86 87/* Add string STR to string table ST. Returns NULL if no memory could 88 be allocated. The given STR is owned by the called and must be 89 valid till dwelf_strtab_free is called. dwelf_strtab_finalize 90 might copy the string into the final table and dwelf_strent_str 91 might return it, or a reference to an identical copy/substring 92 added to the string table. */ 93extern Dwelf_Strent *dwelf_strtab_add (Dwelf_Strtab *st, const char *str) 94 __nonnull_attribute__ (1, 2); 95 96/* This is an optimized version of dwelf_strtab_add if the length of 97 the string is already known. LEN is the length of STR including 98 zero terminator. Calling dwelf_strtab_add (st, str) is similar to 99 calling dwelf_strtab_len (st, str, strlen (str) + 1). */ 100extern Dwelf_Strent *dwelf_strtab_add_len (Dwelf_Strtab *st, 101 const char *str, size_t len) 102 __nonnull_attribute__ (1, 2); 103 104/* Finalize string table ST and store size and memory location 105 information in DATA d_size and d_buf. DATA d_type will be set to 106 ELF_T_BYTE, d_off will be zero, d_align will be 1 and d_version 107 will be set to EV_CURRENT. If no memory could be allocated NULL is 108 returned and DATA->d_buf will be set to NULL. Otherwise DATA will 109 be returned. */ 110extern Elf_Data *dwelf_strtab_finalize (Dwelf_Strtab *st, 111 Elf_Data *data) 112 __nonnull_attribute__ (1, 2); 113 114/* Get offset in string table for string associated with entry. Only 115 valid after dwelf_strtab_finalize has been called. */ 116extern size_t dwelf_strent_off (Dwelf_Strent *se) 117 __nonnull_attribute__ (1); 118 119/* Return the string associated with the entry. */ 120extern const char *dwelf_strent_str (Dwelf_Strent *se) 121 __nonnull_attribute__ (1); 122 123/* Free resources allocated for the string table. This invalidates 124 any Dwelf_Strent references returned earlier. */ 125extern void dwelf_strtab_free (Dwelf_Strtab *st) 126 __nonnull_attribute__ (1); 127 128/* Creates a read-only Elf handle from the given file handle. The 129 file may be compressed and/or contain a linux kernel image header, 130 in which case it is eagerly decompressed in full and the Elf handle 131 is created as if created with elf_memory (). On decompression or 132 file errors NULL is returned (and elf_errno will be set). If there 133 was no error, but the file is not an ELF file, then an ELF_K_NONE 134 Elf handle is returned (just like with elf_begin). The Elf handle 135 should be closed with elf_end (). The file handle will not be 136 closed. */ 137extern Elf *dwelf_elf_begin (int fd); 138 139/* Returns a human readable string for the given ELF header e_machine 140 value, or NULL if the given number isn't currently known. */ 141extern const char *dwelf_elf_e_machine_string (int machine); 142 143#ifdef __cplusplus 144} 145#endif 146 147#endif /* libdwelf.h */ 148