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
#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 );
Symbol Table and Object File Access Library (libst.a)
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 symbol 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. Identifies 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.
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 Format 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. Functions 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 parameter. 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 format. 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.
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 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 nonzero return status is the recommended
method for detecting an error return from a libst
function.
The following code fragment illustrates how to use libst
routines to read and modify optimization section data.
This particular code fragment 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); ...
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
Functions: libst_intro(3), st_obj_open(3),
st_obj_proc_start(3), st_str_error(3)
st_pt_setup(3)
[ Back ] |
