1 .\" Copyright (c) 2012-2013 Joseph Koshy.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: elftc_string_table_create.3 2866 2013-01-06 03:20:14Z jkoshy $
29 .Dt ELFTC_STRING_TABLE_CREATE 3
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
42 .Ft "Elftc_String_Table *"
43 .Fn elftc_string_table_create "int sizehint"
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"
49 .Fo elftc_string_table_image
50 .Fa "Elftc_String_Table *table"
54 .Fo elftc_string_table_insert
55 .Fa "Elftc_String_Table *table"
56 .Fa "const char *string"
59 .Fo elftc_string_table_lookup
60 .Fa "Elftc_String_Table *table"
61 .Fa "const char *string"
64 .Fo elftc_string_table_remove
65 .Fa "Elftc_String_Table *table"
66 .Fa "const char *string"
69 .Fo elftc_string_table_to_string
70 .Fa "Elftc_String_Table *table"
74 This manual page documents convenience routines for handling ELF
78 .Fn elftc_string_table_create
79 creates a new, empty string table.
82 provides a hint about the expected number of bytes of string data in
86 is zero, an implementation-defined default will be used instead.
89 .Fn elftc_string_table_destroy
90 destroys the previously allocated string table specified by
93 and frees the internal resources allocated for it.
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
100 This section must be of type
104 provides a hint about expected number of bytes of string data in the
108 is zero, an implementation-default will be used instead.
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
117 is not NULL, the size of the ELF representation of the string table is
118 stored in the location pointed to by argument
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
126 .Fn elftc_string_table_lookup
127 should be treated as invalid after a call to this function.
130 .Fn elftc_string_table_insert
131 inserts the NUL-terminated string pointed to by argument
133 into the string table specified by argument
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 .
141 .Fn elftc_string_table_lookup
142 looks up the string referenced by argument
144 in the string table specified by argument
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 .
151 .Fn elftc_string_table_remove
152 removes the string pointed by argument
154 from the string table referenced by argument
156 if it is present in the string table.
159 .Fn elftc_string_table_to_string
160 returns a pointer to the NUL-terminated string residing at argument
162 in the string table specified by argument
164 The value of argument
166 should be one returned by a prior call to
167 .Fn elftc_string_table_insert
169 .Fn elftc_string_table_lookup .
170 The returned pointer will remain valid until the next call to
171 .Fn elftc_string_table_insert
173 .Fn elftc_string_table_image .
174 .Ss Memory Management
177 library manages its own memory allocations.
178 The application should not free the pointers returned by the string
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.
186 .Fn elftc_string_table_insert ,
187 .Fn elftc_string_table_lookup ,
188 .Fn elftc_string_table_remove
190 .Fn elftc_string_table_to_string
191 have O(1) asymptotic behavior.
193 .Fn elftc_string_table_image
194 can have O(size) asymptotic behavior, where
196 denotes the size of the string table.
199 .Fn elftc_string_table_create
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.
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.
212 .Fn elftc_string_table_insert
214 .Fn elftc_string_table_lookup
215 return a non-zero offset on success, or zero in case of an error.
218 .Fn elftc_string_table_remove
219 returns a positive value on success, or zero in case of an error.
222 .Fn elftc_string_table_to_string
223 returns a valid pointer on success, or NULL in case of an error.