contrib/elftoolchain/libelftc/elftc_string_table_create.3

   1 .\" Copyright (c) 2012-2013 Joseph Koshy.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" This software is provided by Joseph Koshy ``as is'' and
  14 .\" any express or implied warranties, including, but not limited to, the
  15 .\" implied warranties of merchantability and fitness for a particular purpose
  16 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  17 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  18 .\" damages (including, but not limited to, procurement of substitute goods
  19 .\" or services; loss of use, data, or profits; or business interruption)
  20 .\" however caused and on any theory of liability, whether in contract, strict
  21 .\" liability, or tort (including negligence or otherwise) arising in any way
  22 .\" out of the use of this software, even if advised of the possibility of
  23 .\" such damage.
  24 .\"
  25 .\" $Id: elftc_string_table_create.3 3750 2019-06-28 01:12:10Z emaste $
  26 .\"
  27 .Dd June 27, 2019
  28 .Dt ELFTC_STRING_TABLE_CREATE 3
  29 .Os
  30 .Sh NAME
  31 .Nm elftc_string_table_create ,
  32 .Nm elftc_string_table_destroy ,
  33 .Nm elftc_string_table_from_section ,
  34 .Nm elftc_string_table_image ,
  35 .Nm elftc_string_table_insert ,
  36 .Nm elftc_string_table_lookup ,
  37 .Nm elftc_string_table_remove ,
  38 .Nm elftc_string_table_to_string
  39 .Nd convenience routines for handling ELF string tables
  40 .Sh SYNOPSIS
  41 .In libelftc.h
  42 .Ft "Elftc_String_Table *"
  43 .Fn elftc_string_table_create "size_t sizehint"
  44 .Ft void
  45 .Fn elftc_string_table_destroy "Elftc_String_Table *table"
  46 .Ft "Elftc_String_Table *"
  47 .Fn elftc_string_table_from_section "Elf_Scn *scn" "size_t sizehint"
  48 .Ft "const char *"
  49 .Fo elftc_string_table_image
  50 .Fa "Elftc_String_Table *table"
  51 .Fa "size_t *size"
  52 .Fc
  53 .Ft size_t
  54 .Fo elftc_string_table_insert
  55 .Fa "Elftc_String_Table *table"
  56 .Fa "const char *string"
  57 .Fc
  58 .Ft size_t
  59 .Fo elftc_string_table_lookup
  60 .Fa "Elftc_String_Table *table"
  61 .Fa "const char *string"
  62 .Fc
  63 .Ft int
  64 .Fo elftc_string_table_remove
  65 .Fa "Elftc_String_Table *table"
  66 .Fa "const char *string"
  67 .Fc
  68 .Ft "const char *"
  69 .Fo elftc_string_table_to_string
  70 .Fa "Elftc_String_Table *table"
  71 .Fa "size_t offset"
  72 .Fc
  73 .Sh DESCRIPTION
  74 This manual page documents convenience routines for handling ELF
  75 string tables.
  76 .Pp
  77 Function
  78 .Fn elftc_string_table_create
  79 creates a new, empty string table.
  80 The argument
  81 .Ar sizehint
  82 provides a hint about the expected number of bytes of string data in
  83 the table.
  84 If the argument
  85 .Ar sizehint
  86 is zero, an implementation-defined default will be used instead.
  87 .Pp
  88 Function
  89 .Fn elftc_string_table_destroy
  90 destroys the previously allocated string table specified by
  91 argument
  92 .Ar table ,
  93 and frees the internal resources allocated for it.
  94 .Pp
  95 Function
  96 .Fn elftc_string_table_from_section
  97 creates a new string table and initializes it based on the
  98 contents of the section specified by argument
  99 .Ar scn .
 100 This section must be of type
 101 .Dv SHT_STRTAB .
 102 The argument
 103 .Ar sizehint
 104 provides a hint about expected number of bytes of string data in the
 105 table.
 106 If the value of
 107 .Ar sizehint
 108 is zero, an implementation-default will be used instead.
 109 .Pp
 110 Function
 111 .Fn elftc_string_table_image
 112 returns a pointer to the ELF representation of the contents of the
 113 string table specified by argument
 114 .Ar table .
 115 If argument
 116 .Ar size
 117 is not NULL, the size of the ELF representation of the string table is
 118 stored in the location pointed to by argument
 119 .Ar size .
 120 The function
 121 .Fn elftc_string_table_image
 122 will compact the string table if the table contains deleted strings.
 123 The string offsets returned by prior calls to
 124 .Fn elftc_string_table_insert
 125 and
 126 .Fn elftc_string_table_lookup
 127 should be treated as invalid after a call to this function.
 128 .Pp
 129 Function
 130 .Fn elftc_string_table_insert
 131 inserts the NUL-terminated string pointed to by argument
 132 .Ar string
 133 into the string table specified by argument
 134 .Ar table ,
 135 and returns an offset value usable in ELF data structures.
 136 Multiple insertions of the same content will return the same offset.
 137 The offset returned will remain valid until the next call to
 138 .Fn elftc_string_table_image .
 139 .Pp
 140 Function
 141 .Fn elftc_string_table_lookup
 142 looks up the string referenced by argument
 143 .Ar string
 144 in the string table specified by argument
 145 .Ar table ,
 146 and if found, returns the offset associated with the string.
 147 The returned offset will be valid until the next call to
 148 .Fn elftc_string_table_image .
 149 .Pp
 150 Function
 151 .Fn elftc_string_table_remove
 152 removes the string pointed by argument
 153 .Ar string
 154 from the string table referenced by argument
 155 .Ar table ,
 156 if it is present in the string table.
 157 .Pp
 158 Function
 159 .Fn elftc_string_table_to_string
 160 returns a pointer to the NUL-terminated string residing at argument
 161 .Ar offset
 162 in the string table specified by argument
 163 .Ar table .
 164 The value of argument
 165 .Ar offset
 166 should be one returned by a prior call to
 167 .Fn elftc_string_table_insert
 168 or
 169 .Fn elftc_string_table_lookup .
 170 The returned pointer will remain valid until the next call to
 171 .Fn elftc_string_table_insert
 172 or
 173 .Fn elftc_string_table_image .
 174 .Ss Memory Management
 175 The
 176 .Lb libelftc
 177 library manages its own memory allocations.
 178 The application should not free the pointers returned by the string
 179 table functions.
 180 .Sh IMPLEMENTATION NOTES
 181 The current implementation is optimized for the case where strings are
 182 added to a string table, but rarely removed from it.
 183 .Pp
 184 The functions
 185 .Fn elftc_string_table_insert ,
 186 .Fn elftc_string_table_lookup ,
 187 .Fn elftc_string_table_remove
 188 and
 189 .Fn elftc_string_table_to_string
 190 have O(1) asymptotic behavior.
 191 The function
 192 .Fn elftc_string_table_image
 193 can have O(size) asymptotic behavior, where
 194 .Ar size
 195 denotes the size of the string table.
 196 .Sh RETURN VALUES
 197 Functions
 198 .Fn elftc_string_table_create
 199 and
 200 .Fn elftc_string_table_from_section
 201 return a valid pointer to an opaque structure of type
 202 .Vt Elftc_String_Table
 203 on success, or NULL in case of an error.
 204 .Pp
 205 The function
 206 .Fn elftc_string_table_image
 207 returns a pointer to an in-memory representation of an ELF string
 208 table on success, or NULL in case of an error.
 209 .Pp
 210 Functions
 211 .Fn elftc_string_table_insert
 212 and
 213 .Fn elftc_string_table_lookup
 214 return a non-zero offset on success, or zero in case of an error.
 215 .Pp
 216 Function
 217 .Fn elftc_string_table_remove
 218 returns a positive value on success, or zero in case of an error.
 219 .Pp
 220 Function
 221 .Fn elftc_string_table_to_string
 222 returns a valid pointer on success, or NULL in case of an error.
 223 .Sh SEE ALSO
 224 .Xr dwarf 3 ,
 225 .Xr elf 3 ,
 226 .Xr elftc 3