st_pt_setup(3) Library Functions Manual st_pt_setup(3)
NAME
st_pt_setup, st_obj_pt_setup, st_pt_start, st_pt_next, st_obj_proc_has_ppod, st_proc_has_ppod, st_obj_proc_pp, st_proc_pp, st_pp_start,
st_pp_next, st_pp_find_tag, st_pp_add, st_pp_append, st_pp_delete, st_pp_print, st_ppod_tag, st_ppod_data, st_ppod_print, st_pt_layout,
st_pt_cleanup - Access and modify optimization symbol table information in an object file
LIBRARY
Symbol Table and Object File Access Library (libst.a)
SYNOPSIS
#include <st.h>
st_status_t st_pt_setup (
void *fdrbuf,
unsigned fdrsize,
void *pdrbuf,
unsigned pdrsize,
void *optsym,
unsigned optsize,
st_pt_t *pt);
st_status_t st_obj_pt_setup (
st_obj_t *obj,
st_pt_t *pt);
st_status_t st_pt_start (
st_pt_t pt,
st_pp_t *pp);
st_status_t st_pt_next (
st_pt_t pt,
const st_pp_t pp_cur,
st_pp_t *pp);
st_status_t st_obj_proc_has_ppod (
st_obj_t *obj,
st_proc_t proc,
st_bool_t *has_ppods);
st_status_t st_proc_has_ppod (
st_pt_t pt,
int ipd,
st_bool_t *has_ppods);
st_status_t st_obj_proc_pp (
st_obj_t *obj,
st_proc_t proc,
st_pp_t *pp);
st_status_t st_proc_pp (
st_pt_t pt,
int ipd,
st_pp_t *pp);
st_status_t st_pp_start (
st_pp_t pp,
st_ppod_t *ppod);
st_status_t st_pp_next (
st_pp_t pp,
const st_ppod_t ppod_cur,
st_pp_t *ppod_next);
st_status_t st_pp_find_tag (
st_pp_t pp,
unsigned int tag,
st_ppod_t *ppod);
st_status_t st_pp_add (
st_pp_t pp,
unsigned int tag,
unsigned int len,
void *data);
st_status_t st_pp_append (
st_pp_t pp,
st_ppod_t ppod,
unsigned int len,
void *data);
st_status_t st_pp_delete (
st_pp_t pp,
st_ppod_t ppod);
st_status_t st_pp_print (
st_pp_t pp);
st_status_t st_ppod_tag (
st_pp_t pp,
st_ppod_t ppod,
unsigned int *tag);
st_status_t st_ppod_data (
st_pp_t pp,
st_ppod_t ppod,
unsigned int *dlen,
void **dptr);
st_status_t st_ppod_print (
st_pp_t pp,
st_ppod_t ppod);
st_status_t st_pt_layout (
st_pt_t pt,
void **fddata,
unsigned long *fdlen,
void **pddata,
unsigned long *pdlen,
void **ppdata,
unsigned long *pplen);
st_status_t st_pt_cleanup (
st_pt_t pt);
PARAMETERS
Specifies an address of a file descriptor table in memory. Specifies the number of file descriptor entries. Specifies an address of a
procedure descriptor table in memory. Specifies the number of procedure descriptor entries. Specifies an address of an optimization sym-
bol table in memory. Specifies the size in bytes of an optimization symbol table. Specifies an address to which st_pt_setup, or
st_obj_pt_setup return a ppod table handle. For all other functions, specifies a ppod table handle, as returned by the st_pt_setup, or
st_obj_pt_setup functions. Specifies an object handle, as returned by the st_obj_open function. Specifies an address to which
st_pt_start, st_pt_next, st_obj_proc_pp, or st_proc_pp return a ppod handle for a specific procedure. For all other functions, specifies a
ppod handle, as returned by the st_pt_start, st_pt_next, st_obj_proc_pp, or st_proc_pp functions. Specifies a ppod handle as returned by
the st_pt_start, st_pt_next, st_obj_proc_pp, or st_proc_pp functions. Specifies a procedure handle, as returned by a function such as
st_obj_proc_start. Specifies an address to which st_obj_proc_has_ppod or st_proc_has_ppod return a Boolean value of TRUE/ if the specified
procedure has ppod entries. Specifies the index of a procedure descriptor table entry. Specifies an address to which st_pp_start or
st_pp_find_tag return a ppod entry handle. For all other functions, specifies a ppod entry handle, as returned by the st_pp_start,
st_pp_next, or st_pp_find_tag functions. Specifies a ppod entry handle, as returned by the st_pp_start, st_pp_next, or st_pp_find_tag
functions. Specifies an address to which st_pp_next returns a ppod entry handle. Specifies an address to which st_ppod_tag returns a ppod
entry tag value. For st_pp_find_tag and st_pp_add, specifies a ppod entry tag value. The following ppod entry tag values are defined in
/usr/include/symconst.h: Identifies the first ppod entry in a procedure. This entry contains the version of the ppod structure and file
layout. The current version, PPOD_VERSION, is defined in /usr/include/symconst.h. Identifies the last ppod entry in a procedure. This
entry is always empty. Identifies a ppod entry that contains extended source location information. Identifies a ppod entry that contains
semantic event debug information. Identifies a ppod entry that contains split lifetime debug information. Identifies a ppod entry that
contains discontiguous scope debug information. Identifies a ppod entry that contains inlined procedure call debug information. Identi-
fies a ppod entry that contains profile feedback data. Specifies either the length in bytes of a ppod entry's data or zero if the data is
immediate. Specifies either the address of a ppod entry's data or the data itself. Specifies an address to which st_ppod_data returns
either the length in bytes of a ppod entry's data or zero if the ppod entry contains immediate data. Specifies an address to which
st_ppod_data returns either the address of a ppod entry's data or the data itself. Specifies an address to which st_pt_layout returns the
address of an output file descriptor table. Specifies an address to which st_pt_layout returns the number of file descriptors in an output
file descriptor table. This should match the number of file descriptors passed to st_pt_setup in fdrsize. Specifies an address to which
st_pt_layout returns the address of an output procedure descriptor table. Specifies an address to which st_pt_layout returns the number of
procedure descriptors in an output procedure descriptor table. This should match the number of procedure descriptors passed to st_pt_setup
in pdrsize. Specifies an address to which st_pt_layout returns the address of an output ppod table. Specifies an address to which
st_pt_layout returns the size of an output ppod table.
DESCRIPTION
These functions are used to read, create, or modify optimization symbol table data. The optimization symbol table is a part of an object
file that contains the ppod table. The term, ppod, refers to Per-Procedure Optimization Description (see the Object File/Symbol Table For-
mat Specification, Section 5.3.3 - Optimization Symbols). The ppod table can contain a ppod for each procedure identified in the procedure
descriptor table, and a single procedure's ppod can contain multiple ppod entries.
These functions provide access to ppod tables, ppods, and ppod entries. They are named according to the data types they operate on. Func-
tions that start with st_pt_ operate on ppod tables. Functions that start with st_pp_ operate on ppods, and functions that start with
st_ppod_ operate on ppod entries.
Return an opaque handle for the ppod table to the pt parameter. You can use this handle as an input argument in subsequent calls to other
ppod table access functions. The st_obj_pt_setup function requires an object handle, as returned by st_obj_open. The st_pt_setup function
is passed the contents of three symbol table subsections in buffers: the file descriptor table, the procedure descriptor table, and the
optimization symbol table. All three buffers are needed to read the ppod table, and all three buffers are modified by changes to the ppod
table.
The handle returned by st_obj_pt_setup can only be used to read optimization symbol table data. The handle returned by the
st_pt_setup function can be used to read, create or modify optimization symbol table data. Used to iterate over all of the ppods in
a ppod table. These functions return an opaque ppod handle to the pp parameter. You can use this handle as an input argument in
subsequent calls to other ppod access functions. (To indicate that the iteration over the ppods has been completed, the functions
return NULL to the pp parameter.) These functions test that the specified procedure's ppod is not empty and return a Boolean result
to the has_ppods parameter. Used to access a specific procedure's ppod. These functions return an opaque handle to the pp parame-
ter. If a procedure has no ppod entries, the returned handle is for an empty ppod. The ipd argument to st_proc_pp is an index of
the procedure descriptor array that was passed to st_pt_setup in the pdrbuf argument. Used to iterate over all of the ppod entries
in a ppod. These functions return an opaque ppod entry handle to the ppod and ppod_next parameters respectively. You can use this
handle as an input argument in subsequent calls to other ppod entry access functions. (To indicate that the iteration over the ppod
entries has been completed, the functions return a status of ST_E_PPODE_RANGE and set the handle to NULL.) Used to locate a ppod
entry with a specific tag value. This function returns an opaque ppod entry handle to the ppod parameter. (To indicate that no
matching ppod entries were found, st_pp_find_tag returns NULL to the ppod parameter.) These functions can only be used when the
st_pt_setup function is called to retrieve the ppod table handle. The st_obj_pt_setup function returns a ppod table handle that
cannot be used with modifier interfaces.
The st_pp_add function adds a new ppod entry to a ppod. The st_pp_append function looks up a ppod entry and appends to existing
data. The st_pp_delete function looks up a ppod entry and removes it from the ppod.
All modifications are buffered until the st_pt_layout function is called. Tools that use these functions to modify ppods are
responsible for writing the modified fdr (file descriptor), pdr (procedure descriptor), and ppod (optimization) tables to an object
file. Display the contents of an entire ppod or a single ppod entry, respectively. The ppod data is displayed in raw hex-dump for-
mat. These functions write to standard out. Used to read the components of a ppod entry. The st_ppod_tag function returns the
ppod entry tag value to the tag parameter. The st_ppod_data function reads the ppod entry data into a buffer and returns the address
of this buffer and its length to the dptr and dlen parameters, respectively. If the ppod entry contains immediate data a zero
length is returned to the dlen parameter and the actual data is returned to the dptr parameter. Applies all ppod changes to file
descriptor, procedure descriptor, and ppod tables. Returns the address of the new file descriptor table to the fddata parameter and
the file descriptor count to the fdlen parameter. Returns the address of the new procedure descriptor table to the pddata parameter
and the procedure descriptor count to the pdlen parameter. Returns the address of the new ppod table to the ppdata parameter and
the size of the ppod table to the pplen parameter. Frees memory associated with a ppod table handle. This function will be called
automatically by st_obj_close for ppod table handles returned by the st_obj_pt_setup function.
EXAMPLES
The following code fragment illustrates how to use libst routines to read and modify optimization section data. This particular code frag-
ment shows an algorithm for removing all ppod entries from an object file.
This example has been simplified for illustration purposes. Return status should be tested after each function call. See st_strerror(3)
for an example of return status testing. Reading and writing the symbol table subtables has also been excluded from this example.
#include <st.h> #include <sym.h> #include <symconst.h>
...
FDR *fdr_in; /* Input file descriptor buffer */ unsigned long fdr_inum; /* Input number of file descriptors */ PDR
*pdr_in; /* Input procedure descriptor buffer */ unsigned long pdr_inum; /* Input number of procedure descriptors */ OPTR
*opt_in; /* Input optimization symbol buffer */ unsigned long opt_ilen; /* Input optimization symbol length */
FDR *fdr_out; /* Ouput file descriptor buffer */ unsigned long fdr_onum; /* Output number of file descriptors */ PDR
*pdr_out; /* Output procedure descriptor buffer */ unsigned long pdr_onum; /* Output number of procedure descriptors */ OPTR
*opt_out; /* Output optimization symbol data */ unsigned long opt_olen; /* Output optimization symbol length */
st_status_t status; st_pt_t pt; /* ppod table handle */ st_pp_t pp; /* ppod handle for a single procedure */
st_ppod_t ppod; /* ppod entry handle */ unsigned int tag; /* tag value of ppod entry */
...
/* Setup for processing optimization section */ status = st_pt_setup(fdr_in, fdr_inum, pdr_in, pdr_inum,
opt_in, opt_ilen, &pt);
/* Walk through all ppods. There will be one ppod for each
* procedure descriptor.
*/
for (status = st_pt_start(pt, &pp);
pp;
status = st_pt_next(pt, pp, &pp)) {
/* Walk through all ppod entries for each ppod. */
for (status = st_pp_start(pp, &ppod);
ppod;
status = st_pp_next(pp, ppod, &ppod)) {
/* Get the tag value for the ppod entry. */
status = st_ppod_tag(pp, ppod, &tag);
/* The first ppod entry's tag will always be
* PPODE_STAMP, and the last ppod entry's tag will
* always be PPODE_END. These entries cannot be
* deleted explicitly. If all other ppod entries
* are deleted the PPODE_STAMP and PPODE_END entries
* will be deleted automatically.
*/
if (tag == PPODE_STAMP || tag == PPODE_END)
continue;
/* Delete a ppod entry. After deletion, the ppod
* entry handle can still be used in a subsequent
* call to st_pp_next.
*/
status = st_pp_delete(pp, ppod);
} }
/* Layout new optimization symbol table and update the file
* and procedure descriptors.
*/ status = st_pt_layout(pt, &fdr_out, &fdr_onum, &pdr_out, &pdr_onum,
&opt_out, &opt_olen); ...
RETURN VALUES
All functions indicate success by returning a value of 0 (zero). A posi-tive re turn value is an errno value from a system call. A nega-
tive return value is a library error or informational code. The library codes are documented in st.h.
Return parameters are set to 0 when an error occurs. An exception to this is the case in which an invalid input parameter is passed. 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.
FILES
Header file that contains definitions and function prototypes for libst.a functions Header file that contains definitions for symbol table
structures Header file that contains definitions of symbol table constants
RELATED INFORMATION
Functions: libst_intro(3), st_obj_open(3), st_obj_proc_start(3), st_str_error(3) delim off
st_pt_setup(3)