st_cm_setup, st_obj_cm_setup, st_cm_start, st_cm_next,
st_cm_find_sscn, st_cm_tag, st_cm_data, st_cm_flags,
st_cm_get_flags, st_cm_set_flags, st_cm_add, st_cm_append,
st_cm_delete, st_cm_del_entry, st_cm_print,
st_cm_print_one, st_cm_layout, st_cm_cleanup - access and
modify comment section information in an object file
#include <st.h>
st_status_t st_cm_setup(
void *sdata,
unsigned int ssize,
st_cmscn_t *cmscn ); st_status_t st_obj_cm_setup(
st_obj_t *obj,
st_cmscn_t *cmscn ); st_status_t st_cm_start(
st_cmscn_t cmscn,
st_cm_sscn_t *sscn ); st_status_t st_cm_next(
st_cmscn_t cmscn,
st_cm_sscn_t cmcur,
st_cm_sscn_t *cmnext ); st_status_t
st_cm_find_sscn(
st_cmscn_t cmscn,
unsigned int tag,
st_cm_sscn_t *sscn ); st_status_t st_cm_tag(
st_cmscn_t cmscn,
st_cm_sscn_t sscn,
unsigned int *tag ); st_status_t st_cm_data(
st_cmscn_t cmscn,
st_cm_sscn_t sscn,
unsigned int *dlen,
void **dptr ); st_status_t st_cm_flags(
st_cmscn_t cmscn,
st_cm_sscn_t sscn,
cm_flags_t *flags ); st_status_t st_cm_get_flags(
st_cmscn_t cmscn,
unsigned int tag,
cm_flags_t *flags,
st_bool_t *is_default ); st_status_t
st_cm_set_flags(
st_cmscn_t cmscn,
unsigned int tag,
cm_flags_t flags ); st_status_t st_cm_add(
st_cmscn_t cmscn,
unsigned int tag,
unsigned int len,
void *data ); st_status_t st_cm_append(
st_cmscn_t cmscn,
st_cm_sscn_t sscn,
unsigned int len,
void *data ); st_status_t st_cm_delete(
st_cmscn_t cmscn,
st_cm_sscn_t sscn ); st_status_t st_cm_del_entry(
st_cmscn_t cmscn,
st_cm_sscn_t sscn,
void *key ); st_status_t st_cm_print(
st_cmscn_t cmscn,
st_bool_t verbose ); st_status_t st_cm_print_one(
st_cmscn_t cmscn,
unsigned int tag,
st_bool_t verbose ); st_status_t st_cm_layout(
st_cmscn_t cmscn,
void **cmdata,
long *cmlen ); st_status_t st_cm_cleanup(
st_cmscn_t cmscn );
Symbol Table and Object File Access Library (libst.a)
Specifies an address of a comment section in memory.
Specifies the size of a comment section. Specifies an
address to which st_cm_setup() or st_obj_cm_setup() return
a comment section handle. For all other functions, specifies
a comment section handle, as returned by the
st_cm_setup() or st_obj_cm_setup() functions. Specifies
an object handle, as returned by the st_obj_open() function.
Specifies an address to which st_cm_start() or
st_cm_find_sscn() return a comment subsection handle. For
st_cm_tag(), st_cm_data, st_cm_flags(), st_cm_append(),
st_cm_delete(), and st_cm_del_entry(), specifies a comment
subsection handle, as returned by the st_cm_start() or
st_cm_find_sscn() functions. Specifies a comment subsection
handle as returned by the st_cm_start() or
st_cm_find_sscn() functions. Specifies an address to
which st_cm_next() returns a comment subsection handle.
Specifies an address to which st_cm_tag() returns a comment
subsection tag value. For st_cm_find_sscn(),
st_cm_get_flags(), st_cm_set_flags(), st_cm_add(), and
st_cm_print_one(), specifies a comment subsection tag
value. The following comment subsection tag values are
defined in /usr/include/scncomment.h: Identifies the last
subsection in the comment section. This subsection is
always empty. Identifies the first subsection in the comment
section. This subsection contains the version of the
comment section structure and file layout. The current
version, CM_VERSION, is defined in /usr/include/scncomment.h.
Identifies a comment subsection that contains
compact relocation data. Identifies a comment subsection
that contains generic strings. This is the default subsection
tag for comment data added by the mcs(1) utility.
Identifies a comment subsection that contains comment subsection
tag descriptors. Identifies a comment subsection
that contains identifying information for Source Code Control
System (SCCS) files. Identifies a comment subsection
that contains tool-specific version information. Identifies
a comment subsection that contains incremental
instrumentation checksum data used by Atom. Identifies a
comment subsection that contains the incremental instrumentation
argument mask used by Atom. Identifies a comment
subsection that contains the incremental instrumentation
argument tool string used by Atom. Identifies a comment
subsection that contains the incremental instrumentation
analysis addresses used by Atom. Identifies a comment
subsection that contains the incremental instrumentation
object id used by Atom. Identifies a comment subsection
that contains post-link relocation information for
linker-defined symbols. Specifies an address to which
st_cm_data() returns the size of a comment subsection's
data. Specifies an address to which st_cm_data() returns
the address of a comment subsection's data. Specifies an
address to which st_cm_flags() or st_cm_get_flags() return
tag descriptor flags. For st_cm_set_flags(), specifies tag
descriptor flags. Tag descriptor flags include three
fields which can be extracted by the following macros
defined in /usr/include/scncomment.h: Returns the flag
setting for tools that strip object files. The following
strip flag settings are defined in /usr/include/scncomment.h:
Identifies subsections that should not be
stripped. Identifies subsections that should be removed
by tools that strip symbol tables. Identifies subsections
that should be removed by tools that strip local symbols
from symbol tables. Returns the flag setting for tools
that combine multiple input comment sections to form a
single output comment section. The following combine flag
settings are defined in /usr/include/scncomment.h: Identifies
subsections for which input subsections of the same
type are appended to form an output subsection. Identifies
subsections for which one of the input subsections is
selected randomly and copied to an output subsection.
Identifies subsections that should not be copied as output
subsections. Identifies subsections for which more than
one input subsection should be reported as an error. A
single input subsection marked with this flag should be
copied to an output subsection. Identifies subsections
for which an error should be reported. Returns the flag
setting for tools that modify object files. The following
modify flag settings are defined in /usr/include/scncomment.h:
Identifies subsections that should not be removed.
Identifies subsections that should be removed. Identifies
subsections for which an error should be reported.
Assigns tag descriptor flags to the flags argument using
the strip, combine, and modify flag settings in s, c, and
m, respectively. Specifies an address to which
st_cm_get_flags() returns a value describing the tag
descriptor flags. The following settings for this argument
are defined in /usr/include/st.h: Indicates that no tag
descriptor flags for the specified tag value are in the
comment section and that default flags are used. Indicates
that no tag descriptor flags for the specified tag
value are in the comment section. Specifies the length of
a comment subsection's data. Specifies the address of a
comment subsection's data. Specifies the address of a
data item used by the st_cm_del_entry() function to locate
an entry in a comment subsection. Specifies the style of
output that should be produced by st_cm_print() or
st_cm_print_one(). The following settings for this argument
are defined in /usr/include/st.h: Specifies comment
subsection data should be printed in hex dump format.
Specifies comment subsection data should be printed in its
interpreted form. Subsections of unknown type should be
printed in hex dump format. Specifies an address to which
st_cm_layout() returns the address of an output comment
section. Specifies an address to which st_cm_layout()
returns the size of an output comment section.
These functions are used to read, create or modify comment
section data.
Return an opaque handle for the comment section to the
cmscn parameter. You can use this handle as an input argument
in subsequent calls to other comment section access
functions. The st_obj_cm_setup() function requires an
object handle, as returned by st_obj_open(). The
st_cm_setup() function is passed the contents of the comment
section in a buffer. Returns the comment section
contents to the cmdata parameter and the size of the comment
section to the cmlen parameter. Changes made to the
comment section by comment section modification functions
are applied to the comment section data returned by
st_cm_layout(). Frees memory associated with a comment
section handle. This function will be called automatically
by st_obj_close(). Used to iterate over all of the comment
subsections in a comment section. These functions
return an opaque comment subsection handle to the sscn
parameter. You can use this handle as an input argument in
subsequent calls to other comment subsection access functions.
(To indicate that the iteration over the comment
subsections has been completed, the functions return NULL
to the sscn parameter.) Used to locate a comment subsection
with a specific tag value. This function returns an
opaque comment subsection handle to the sscn parameter.
You can use this handle as an input argument in subsequent
calls to other comment subsection access functions. (To
indicate that no matching subsections were found,
st_cm_find_sscn() returns NULL to the sscn parameter.)
Used to read the components of a comment subsection. The
st_cm_tag() function returns the comment subsection tag
value to the tag parameter. The st_cm_data() function
reads the comment subsection data into a buffer and
returns the address of this buffer and its length to the
dptr and dlen parameters, respectively. The st_cm_flags()
function returns the tag descriptor flags to the flags
parameter. Returns the tag descriptor flags in effect for
a given tag value to the flags parameter. If the comment
section associated with the comment section handle does
not have a tag descriptor entry for the given tag value,
the default tag descriptor flags for that tag are returned
and the value True is returned to the is_default parameter.
Modify the comment section contents. All modifications
are buffered and are only applied to the comment
section data returned by the st_cm_layout() function.
Tools that use these functions to modify comment sections
are responsible for writing the new comment section contents
and the associated section header to an object file.
The st_cm_set_flags() function modifies the tag
descriptor flags for a comment subsection tag
value. The st_cm_add() function adds a new comment
subsection. The st_cm_append() function appends
more data to a comment subsection, and the
st_cm_delete() function removes a comment subsection.
Removes an entry from either the tag
descriptor subsection or the tool version subsection.
To identify the entry that should be deleted
from a tag descriptor subsection, set the key
parameter to a tag value. To identify the entry
that should be deleted from a tool version subsection,
set the key parameter to the tool version
name (defined in /usr/include/stamp.h). Display
the contents of the entire comment section or a
single comment subsection, respectively. The verbose
parameter controls the form in which the contents
are display. If the verbose parameter is set
to True, the comment section contents are displayed
in interpreted form; otherwise, contents are displayed
in raw hex-dump format. These functions
write to standard out, and the output is equivalent
to that produced by the odump(1) and mcs(1) utilities.
All functions indicate success by returning a value of 0
(zero). A positive return value is an errno value from a
system call. A negative return value is a library error or
informational code. The library codes are documented in
st.h.
Return parameters are set to 0 or -1 when an error occurs.
Address parameters are set to 0, and file and procedure
handles are set to -1. An exception to this is the case in
which a NULL pointer for the object or other return parameter
is input. In such cases, the return parameters will
be unchanged. A non-zero return status is the recommended
method for detecting an error return from a libst function.
The following code fragment illustrates how to use libst
routines to read and modify comment section data. This
particular code fragment shows a comment section processing
algorithm appropriate for a tool that modifies an
object file. For example, atom(1) based tools use this
algorithm to update the comment section for the instrumented
version of an application program.
#include <st.h>
... char *inbuff; /* Input comment section
data */ long inlen; /* Input comment section
length */ char *outbuff; /* Output comment
section data */ long outlen; /* Output
comment section length */ st_status_t status;
st_cmscn_t cmscn; st_cm_sscn_t sscn; cm_flags_t
flags; unsigned int tag;
... /* Setup for processing comment section */ if (status
= st_cm_setup(inbuff, inlen, &cmscn)) /* report error
*/
/* Walk through all comment subsections. The st_cm_next
call
* is guaranteed to work properly even if a subsections
are
* removed between calls.
*/
for (st_cm_start(cmscn, &sscn);
sscn;
st_cm_next(cmscn, sscn, &sscn)) {
/* Each comment subsection type has a set of flags
associated
* with it. Tag descriptor entries may record specific
* settings for these flags, or defaults may be used
by the
* API's.
*
* The subsection flags are actually 3 separate settings
which
* direct comment processing for 3 different categories
of
* tools: strippers, linkers and modifiers. Strippers
are
* any tools that remove symbol table entries. Linkers
are
* any tools that combine more than one object to
produce a
* single output object. Modifiers are any tools that
modify
* an object in place, or convert a single input
object to a
* single output object. Some tools may fit more than
one of
* these categories. This example uses only the
object modifer
* flags.
*/
/* Get the flags */
st_cm_flags(cmscn, sscn, &flags);
switch (CMFM_FLAG(flags)) {
case CMFM_COPY:
/* Leave this subsection alone */
break;
case CMFM_DELETE:
/* Remove this subsection */
st_cm_delete(cmscn, sscn);
break;
case CMFM_ERROR:
/* Report an error and terminate processing
*/
st_cm_tag(cmscn, sscn, &tag);
fprintf(stderr, "Tool: Error updating comment
section\n");
fprintf(stderr, "Found comment subsection
tag=%d\n", tag);
exit(1);
} }
/* Layout new comment section */ if (status = st_cm_layout(cmscn,
&outbuff, &outlen))
/* Report error */
.
.
.
Header file that contains definitions and function prototypes
for libst.a functions Header file that contains definitions
for comment section structures and values Header
file that contains object file and tool version definitions
Commands: atom(1), mcs(1), odump(1)
Functions: libst_intro(3), st_obj_open(3)
st_cm_setup(3)
[ Back ] |
