st_cm_setup(3) Library Functions Manual st_cm_setup(3)
NAME
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
LIBRARY
Symbol Table and Object File Access Library (libst.a)
SYNOPSIS
#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);
PARAMETERS
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 sub-
section is always empty. Identifies the first subsection in the comment section. This subsection contains the version of the comment sec-
tion 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. Identi-
fies a comment subsection that contains identifying information for Source Code Control System (SCCS) files. Identifies a comment subsec-
tion 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 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 sec-
tion. 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 ran-
domly 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 com-
ment 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. Speci-
fies an address to which st_cm_layout returns the size of an output comment section.
DESCRIPTION
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_set-
up 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 func-
tions. (To indicate that no matching subsections were found, st_cm_find_sscn returns NULL to the sscn parameter.) Used to read the compo-
nents of a comment subsection. The st_cm_tag function returns the comment subsection tag value to the tag parameter. The st_cm_data func-
tion 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 com-
ment 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 display in inter-
preted 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.
RETURN VALUES
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.
EXAMPLE
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 section0);
fprintf(stderr, "Found comment subsection tag=%d0, tag);
exit(1);
} }
/* Layout new comment section */ if (status = st_cm_layout(cmscn, &outbuff, &outlen))
/* Report error */
...
FILES
Header file that contains definitions and function prototypes for libst.a functions Header file that contains definitions for comment sec-
tion structures and values Header file that contains object file and tool version definitions
RELATED INFORMATION
Commands: atom(1), mcs(1), odump(1)
Functions: libst_intro(3), st_obj_open(3) delim off
st_cm_setup(3)