 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
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
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
sdata
Specifies an address of a comment section in memory.
ssize
Specifies the size of a comment section.
cmscn
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.
obj Specifies an object handle, as returned by the st_obj_open() function.
sscn
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.
cmcur
Specifies a comment subsection handle as returned by the st_cm_start()
or st_cm_find_sscn() functions.
cmnext
Specifies an address to which st_cm_next() returns a comment subsection
handle.
tag 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:
CM_END Identifies the last subsection in the comment section. This
subsection is always empty.
CM_CMSTAMP
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.
CM_COMPACT_RLC
Identifies a comment subsection that contains compact
relocation data.
CM_STRSPACE
Identifies a comment subsection that contains generic strings.
This is the default subsection tag for comment data added by
the mcs(1) utility.
CM_TAGDESC
Identifies a comment subsection that contains comment
subsection tag descriptors.
CM_IDENT
Identifies a comment subsection that contains identifying
information for Source Code Control System (SCCS) files.
CM_TOOLVER
Identifies a comment subsection that contains tool-specific
version information.
CM_II_CHECKSUMS
Identifies a comment subsection that contains incremental
instrumentation checksum data used by Atom.
CM_II_ATOMARGS
Identifies a comment subsection that contains the incremental
instrumentation argument mask used by Atom.
CM_II_TOOLARGS
Identifies a comment subsection that contains the incremental
instrumentation argument tool string used by Atom.
CM_II_ANALADDRS
Identifies a comment subsection that contains the incremental
instrumentation analysis addresses used by Atom.
CM_II_OBJID
Identifies a comment subsection that contains the incremental
instrumentation object id used by Atom.
CM_II_LINKERDEF
Identifies a comment subsection that contains post-link
relocation information for linker-defined symbols.
dlen
Specifies an address to which st_cm_data() returns the size of a
comment subsection's data.
dptr
Specifies an address to which st_cm_data() returns the address of a
comment subsection's data.
flags
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:
CMFS_FLAG(flags)
Returns the flag setting for tools that strip object files. The
following strip flag settings are defined in
/usr/include/scncomment.h:
CMFS_KEEP
Identifies subsections that should not be stripped.
CMFS_STRIP
Identifies subsections that should be removed by tools
that strip symbol tables.
CMFS_LSTRIP
Identifies subsections that should be removed by tools
that strip local symbols from symbol tables.
CMFC_FLAG(flags)
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:
CMFC_APPEND
Identifies subsections for which input subsections of
the same type are appended to form an output
subsection.
CMFC_CHOOSE
Identifies subsections for which one of the input
subsections is selected randomly and copied to an
output subsection.
CMFC_DELETE
Identifies subsections that should not be copied as
output subsections.
CMFC_ERRMULT
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.
CMFC_ERROR
Identifies subsections for which an error should be
reported.
CMFM_FLAG(flags)
Returns the flag setting for tools that modify object files.
The following modify flag settings are defined in
/usr/include/scncomment.h:
CMFM_COPY
Identifies subsections that should not be removed.
CMFM_DELETE
Identifies subsections that should be removed.
CMFM_ERROR
Identifies subsections for which an error should be
reported.
CM_SET_FLAGS(flags, s, c, m)
Assigns tag descriptor flags to the flags argument using the
strip, combine, and modify flag settings in s, c, and m,
respectively.
is_default
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:
True Indicates that no tag descriptor flags for the specified tag
value are in the comment section and that default flags are
used.
False Indicates that no tag descriptor flags for the specified tag
value are in the comment section.
len Specifies the length of a comment subsection's data.
data
Specifies the address of a comment subsection's data.
key Specifies the address of a data item used by the st_cm_del_entry()
function to locate an entry in a comment subsection.
verbose
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:
False Specifies comment subsection data should be printed in hex dump
format.
True Specifies comment subsection data should be printed in its
interpreted form. Subsections of unknown type should be printed
in hex dump format.
cmdata
Specifies an address to which st_cm_layout() returns the address of an
output comment section.
cmlen
Specifies 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.
st_obj_cm_setup and st_cm_setup
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.
st_cm_layout
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().
st_cm_cleanup
Frees memory associated with a comment section handle. This function
will be called automatically by st_obj_close().
st_cm_start and st_cm_next
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.)
st_cm_find_sscn
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.)
st_cm_tag, st_cm_data, and st_cm_flags
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.
st_cm_get_flags
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.
st_cm_set_flags, st_cm_add, st_cm_append, and st_cm_delete
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.
st_cm_del_entry
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).
st_cm_print and st_cm_print_one
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.
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 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 */
.
.
.
FILES
/usr/include/st.h
Header file that contains definitions and function prototypes for
libst.a functions
/usr/include/scncomment.h
Header file that contains definitions for comment section structures
and values
/usr/include/stamp.h
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|