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 2866 2013-01-06 03:20:14Z jkoshy $
  26 .\"
  27 .Dd January 5, 2013
  28 .Os
  29 .Dt ELFTC_STRING_TABLE_CREATE 3
  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 "int sizehint"
  44 .Ft int
  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" "int 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 till the next call to function
 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 .El
 181 .Sh IMPLEMENTATION NOTES
 182 The current implementation is optimized for the case where strings are
 183 added to a string table, but rarely removed from it.
 184 .Pp
 185 The functions
 186 .Fn elftc_string_table_insert ,
 187 .Fn elftc_string_table_lookup ,
 188 .Fn elftc_string_table_remove
 189 and
 190 .Fn elftc_string_table_to_string
 191 have O(1) asymptotic behavior.
 192 The function
 193 .Fn elftc_string_table_image
 194 can have O(size) asymptotic behavior, where
 195 .Ar size
 196 denotes the size of the string table.
 197 .Sh RETURN VALUES
 198 Functions
 199 .Fn elftc_string_table_create
 200 and
 201 .Fn elftc_string_table_from_section
 202 return a valid pointer to an opaque structure of type
 203 .Vt Elftc_String_Table
 204 on success, or NULL in case of an error.
 205 .Pp
 206 The function
 207 .Fn elftc_string_table_image
 208 returns a pointer to an in-memory representation of an ELF string
 209 table on success, or NULL in case of an error.
 210 .Pp
 211 Functions
 212 .Fn elftc_string_table_insert
 213 and
 214 .Fn elftc_string_table_lookup
 215 return a non-zero offset on success, or zero in case of an error.
 216 .Pp
 217 Function
 218 .Fn elftc_string_table_remove
 219 returns a positive value on success, or zero in case of an error.
 220 .Pp
 221 Function
 222 .Fn elftc_string_table_to_string
 223 returns a valid pointer on success, or NULL in case of an error.
 224 .Sh SEE ALSO
 225 .Xr dwarf 3 ,
 226 .Xr elf 3 ,
 227 .Xr elftc 3