diff options
Diffstat (limited to 'rtemstoolkit/elftoolchain/libelftc/elftc_string_table_create.3')
| -rw-r--r-- | rtemstoolkit/elftoolchain/libelftc/elftc_string_table_create.3 | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/rtemstoolkit/elftoolchain/libelftc/elftc_string_table_create.3 b/rtemstoolkit/elftoolchain/libelftc/elftc_string_table_create.3 new file mode 100644 index 0000000..e11e73c --- /dev/null +++ b/rtemstoolkit/elftoolchain/libelftc/elftc_string_table_create.3 @@ -0,0 +1,227 @@ +.\" Copyright (c) 2012-2013 Joseph Koshy. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" $Id: elftc_string_table_create.3 2866 2013-01-06 03:20:14Z jkoshy $ +.\" +.Dd January 5, 2013 +.Os +.Dt ELFTC_STRING_TABLE_CREATE 3 +.Sh NAME +.Nm elftc_string_table_create , +.Nm elftc_string_table_destroy , +.Nm elftc_string_table_from_section , +.Nm elftc_string_table_image , +.Nm elftc_string_table_insert , +.Nm elftc_string_table_lookup , +.Nm elftc_string_table_remove , +.Nm elftc_string_table_to_string +.Nd convenience routines for handling ELF string tables +.Sh SYNOPSIS +.In libelftc.h +.Ft "Elftc_String_Table *" +.Fn elftc_string_table_create "int sizehint" +.Ft int +.Fn elftc_string_table_destroy "Elftc_String_Table *table" +.Ft "Elftc_String_Table *" +.Fn elftc_string_table_from_section "Elf_Scn *scn" "int sizehint" +.Ft "const char *" +.Fo elftc_string_table_image +.Fa "Elftc_String_Table *table" +.Fa "size_t *size" +.Fc +.Ft size_t +.Fo elftc_string_table_insert +.Fa "Elftc_String_Table *table" +.Fa "const char *string" +.Fc +.Ft size_t +.Fo elftc_string_table_lookup +.Fa "Elftc_String_Table *table" +.Fa "const char *string" +.Fc +.Ft int +.Fo elftc_string_table_remove +.Fa "Elftc_String_Table *table" +.Fa "const char *string" +.Fc +.Ft "const char *" +.Fo elftc_string_table_to_string +.Fa "Elftc_String_Table *table" +.Fa "size_t offset" +.Fc +.Sh DESCRIPTION +This manual page documents convenience routines for handling ELF +string tables. +.Pp +Function +.Fn elftc_string_table_create +creates a new, empty string table. +The argument +.Ar sizehint +provides a hint about the expected number of bytes of string data in +the table. +If the argument +.Ar sizehint +is zero, an implementation-defined default will be used instead. +.Pp +Function +.Fn elftc_string_table_destroy +destroys the previously allocated string table specified by +argument +.Ar table , +and frees the internal resources allocated for it. +.Pp +Function +.Fn elftc_string_table_from_section +creates a new string table and initializes it based on the +contents of the section specified by argument +.Ar scn . +This section must be of type +.Dv SHT_STRTAB . +The argument +.Ar sizehint +provides a hint about expected number of bytes of string data in the +table. +If the value of +.Ar sizehint +is zero, an implementation-default will be used instead. +.Pp +Function +.Fn elftc_string_table_image +returns a pointer to the ELF representation of the contents of the +string table specified by argument +.Ar table . +If argument +.Ar size +is not NULL, the size of the ELF representation of the string table is +stored in the location pointed to by argument +.Ar size . +The function +.Fn elftc_string_table_image +will compact the string table if the table contains deleted strings. +The string offsets returned by prior calls to +.Fn elftc_string_table_insert +and +.Fn elftc_string_table_lookup +should be treated as invalid after a call to this function. +.Pp +Function +.Fn elftc_string_table_insert +inserts the NUL-terminated string pointed to by argument +.Ar string +into the string table specified by argument +.Ar table , +and returns an offset value usable in ELF data structures. +Multiple insertions of the same content will return the same offset. +The offset returned will remain valid until the next call to +.Fn elftc_string_table_image . +.Pp +Function +.Fn elftc_string_table_lookup +looks up the string referenced by argument +.Ar string +in the string table specified by argument +.Ar table , +and if found, returns the offset associated with the string. +The returned offset will be valid till the next call to function +.Fn elftc_string_table_image . +.Pp +Function +.Fn elftc_string_table_remove +removes the string pointed by argument +.Ar string +from the string table referenced by argument +.Ar table , +if it is present in the string table. +.Pp +Function +.Fn elftc_string_table_to_string +returns a pointer to the NUL-terminated string residing at argument +.Ar offset +in the string table specified by argument +.Ar table . +The value of argument +.Ar offset +should be one returned by a prior call to +.Fn elftc_string_table_insert +or +.Fn elftc_string_table_lookup . +The returned pointer will remain valid until the next call to +.Fn elftc_string_table_insert +or +.Fn elftc_string_table_image . +.Ss Memory Management +The +.Lb libelftc +library manages its own memory allocations. +The application should not free the pointers returned by the string +table functions. +.El +.Sh IMPLEMENTATION NOTES +The current implementation is optimized for the case where strings are +added to a string table, but rarely removed from it. +.Pp +The functions +.Fn elftc_string_table_insert , +.Fn elftc_string_table_lookup , +.Fn elftc_string_table_remove +and +.Fn elftc_string_table_to_string +have O(1) asymptotic behavior. +The function +.Fn elftc_string_table_image +can have O(size) asymptotic behavior, where +.Ar size +denotes the size of the string table. +.Sh RETURN VALUES +Functions +.Fn elftc_string_table_create +and +.Fn elftc_string_table_from_section +return a valid pointer to an opaque structure of type +.Vt Elftc_String_Table +on success, or NULL in case of an error. +.Pp +The function +.Fn elftc_string_table_image +returns a pointer to an in-memory representation of an ELF string +table on success, or NULL in case of an error. +.Pp +Functions +.Fn elftc_string_table_insert +and +.Fn elftc_string_table_lookup +return a non-zero offset on success, or zero in case of an error. +.Pp +Function +.Fn elftc_string_table_remove +returns a positive value on success, or zero in case of an error. +.Pp +Function +.Fn elftc_string_table_to_string +returns a valid pointer on success, or NULL in case of an error. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr elf 3 , +.Xr elftc 3 |