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 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 till the next call to function 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.El 181.Sh IMPLEMENTATION NOTES 182The current implementation is optimized for the case where strings are 183added to a string table, but rarely removed from it. 184.Pp 185The functions 186.Fn elftc_string_table_insert , 187.Fn elftc_string_table_lookup , 188.Fn elftc_string_table_remove 189and 190.Fn elftc_string_table_to_string 191have O(1) asymptotic behavior. 192The function 193.Fn elftc_string_table_image 194can have O(size) asymptotic behavior, where 195.Ar size 196denotes the size of the string table. 197.Sh RETURN VALUES 198Functions 199.Fn elftc_string_table_create 200and 201.Fn elftc_string_table_from_section 202return a valid pointer to an opaque structure of type 203.Vt Elftc_String_Table 204on success, or NULL in case of an error. 205.Pp 206The function 207.Fn elftc_string_table_image 208returns a pointer to an in-memory representation of an ELF string 209table on success, or NULL in case of an error. 210.Pp 211Functions 212.Fn elftc_string_table_insert 213and 214.Fn elftc_string_table_lookup 215return a non-zero offset on success, or zero in case of an error. 216.Pp 217Function 218.Fn elftc_string_table_remove 219returns a positive value on success, or zero in case of an error. 220.Pp 221Function 222.Fn elftc_string_table_to_string 223returns 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 228