st_cm_setup(3)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 com‐
ment section information in an object file
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 );
LIBRARY
Symbol Table and Object File Access Library (libst.a)
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 han‐
dle, 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() func‐
tions. 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 com‐
ment 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 com‐
ment 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. Identi‐
fies a comment subsection that contains comment subsection tag descrip‐
tors. Identifies a comment subsection that contains identifying infor‐
mation for Source Code Control System (SCCS) files. Identifies a com‐
ment subsection that contains tool-specific version information. Iden‐
tifies a comment subsection that contains incremental instrumentation
checksum data used by Atom. Identifies a comment subsection that con‐
tains the incremental instrumentation argument mask used by Atom.
Identifies a comment subsection that contains the incremental instru‐
mentation argument tool string used by Atom. Identifies a comment sub‐
section 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/scncom‐
ment.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 subsec‐
tions that should be removed by tools that strip symbol tables. Iden‐
tifies 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 sub‐
sections 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 sub‐
sections 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 mod‐
ify 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. Spec‐
ifies 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 buf‐
fer. 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 spe‐
cific 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 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 descrip‐
tor 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 con‐
tents. All modifications are buffered and are only applied to the com‐
ment 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 out‐
put 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 pos‐
itive 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 parame‐
ters 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 section\n");
fprintf(stderr, "Found comment subsection tag=%d\n", tag);
exit(1);
} }
/* Layout new comment section */ if (status = st_cm_layout(cmscn, &out‐
buff, &outlen))
/* Report error */
.
.
.
FILES
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
SEE ALSO
Commands: atom(1), mcs(1), odump(1)
Functions: libst_intro(3), st_obj_open(3)st_cm_setup(3)
