 |
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
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
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_TOOLVERO*L
Identifies a comment subsection that contains tool-specific version
information.
dlen
Specifies an address to which st_cm_data returns the size of a 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 display 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 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
/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
RELATED INFORMATION
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 |
|