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
74This manual page documents convenience routines for handling ELF
75string tables.
76.Pp
77Function
78.Fn elftc_string_table_create
79creates a new, empty string table.
80The argument
81.Ar sizehint
82provides a hint about the expected number of bytes of string data in
83the table.
84If the argument
85.Ar sizehint
86is zero, an implementation-defined default will be used instead.
87.Pp
88Function
89.Fn elftc_string_table_destroy
90destroys the previously allocated string table specified by
91argument
92.Ar table ,
93and frees the internal resources allocated for it.
94.Pp
95Function
96.Fn elftc_string_table_from_section
97creates a new string table and initializes it based on the
98contents of the section specified by argument
99.Ar scn .
100This section must be of type
101.Dv SHT_STRTAB .
102The argument
103.Ar sizehint
104provides a hint about expected number of bytes of string data in the
105table.
106If the value of
107.Ar sizehint
108is zero, an implementation-default will be used instead.
109.Pp
110Function
111.Fn elftc_string_table_image
112returns a pointer to the ELF representation of the contents of the
113string table specified by argument
114.Ar table .
115If argument
116.Ar size
117is not NULL, the size of the ELF representation of the string table is
118stored in the location pointed to by argument
119.Ar size .
120The function
121.Fn elftc_string_table_image
122will compact the string table if the table contains deleted strings.
123The string offsets returned by prior calls to
124.Fn elftc_string_table_insert
125and
126.Fn elftc_string_table_lookup
127should be treated as invalid after a call to this function.
128.Pp
129Function
130.Fn elftc_string_table_insert
131inserts the NUL-terminated string pointed to by argument
132.Ar string
133into the string table specified by argument
134.Ar table ,
135and returns an offset value usable in ELF data structures.
136Multiple insertions of the same content will return the same offset.
137The offset returned will remain valid until the next call to
138.Fn elftc_string_table_image .
139.Pp
140Function
141.Fn elftc_string_table_lookup
142looks up the string referenced by argument
143.Ar string
144in the string table specified by argument
145.Ar table ,
146and if found, returns the offset associated with the string.
147The returned offset will be valid until the next call to
148.Fn elftc_string_table_image .
149.Pp
150Function
151.Fn elftc_string_table_remove
152removes the string pointed by argument
153.Ar string
154from the string table referenced by argument
155.Ar table ,
156if it is present in the string table.
157.Pp
158Function
159.Fn elftc_string_table_to_string
160returns a pointer to the NUL-terminated string residing at argument
161.Ar offset
162in the string table specified by argument
163.Ar table .
164The value of argument
165.Ar offset
166should be one returned by a prior call to
167.Fn elftc_string_table_insert
168or
169.Fn elftc_string_table_lookup .
170The returned pointer will remain valid until the next call to
171.Fn elftc_string_table_insert
172or
173.Fn elftc_string_table_image .
174.Ss Memory Management
175The
176.Lb libelftc
177library manages its own memory allocations.
178The application should not free the pointers returned by the string
179table functions.
180.Sh IMPLEMENTATION NOTES
181The current implementation is optimized for the case where strings are
182added to a string table, but rarely removed from it.
183.Pp
184The functions
185.Fn elftc_string_table_insert ,
186.Fn elftc_string_table_lookup ,
187.Fn elftc_string_table_remove
188and
189.Fn elftc_string_table_to_string
190have O(1) asymptotic behavior.
191The function
192.Fn elftc_string_table_image
193can have O(size) asymptotic behavior, where
194.Ar size
195denotes the size of the string table.
196.Sh RETURN VALUES
197Functions
198.Fn elftc_string_table_create
199and
200.Fn elftc_string_table_from_section
201return a valid pointer to an opaque structure of type
202.Vt Elftc_String_Table
203on success, or NULL in case of an error.
204.Pp
205The function
206.Fn elftc_string_table_image
207returns a pointer to an in-memory representation of an ELF string
208table on success, or NULL in case of an error.
209.Pp
210Functions
211.Fn elftc_string_table_insert
212and
213.Fn elftc_string_table_lookup
214return a non-zero offset on success, or zero in case of an error.
215.Pp
216Function
217.Fn elftc_string_table_remove
218returns a positive value on success, or zero in case of an error.
219.Pp
220Function
221.Fn elftc_string_table_to_string
222returns 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
227