Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

st_cm_print_one(3) [osf1 man page]

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)
Man Page