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 3750 2019-06-28 01:12:10Z emaste $
28 .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 "size_t 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" "size_t 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 until the next call to
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
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.
185 .Fn elftc_string_table_insert ,
186 .Fn elftc_string_table_lookup ,
187 .Fn elftc_string_table_remove
189 .Fn elftc_string_table_to_string
190 have O(1) asymptotic behavior.
192 .Fn elftc_string_table_image
193 can have O(size) asymptotic behavior, where
195 denotes the size of the string table.
198 .Fn elftc_string_table_create
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.
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.
211 .Fn elftc_string_table_insert
213 .Fn elftc_string_table_lookup
214 return a non-zero offset on success, or zero in case of an error.
217 .Fn elftc_string_table_remove
218 returns a positive value on success, or zero in case of an error.
221 .Fn elftc_string_table_to_string
222 returns a valid pointer on success, or NULL in case of an error.