st_pt_setup(3)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 ta‐
ble information in an object file
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 );
LIBRARY
Symbol Table and Object File Access Library (libst.a)
PARAMETERS
Specifies an address of a file descriptor table in memory. Specifies
the number of file descriptor entries. Specifies an address of a pro‐
cedure descriptor table in memory. Specifies the number of procedure
descriptor entries. Specifies an address of an optimization symbol ta‐
ble in memory. Specifies the size, in bytes, of an optimization symbol
table. Specifies an address to which st_pt_setup() or st_obj_pt_set‐
up() 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_set‐
up() 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() func‐
tions. 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 proce‐
dure. This entry is always empty. Identifies a ppod entry that con‐
tains 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. Iden‐
tifies a ppod entry that contains inlined procedure call debug informa‐
tion. 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 out‐
put 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 Format Spec‐
ification, Section 5.3.3 -- Optimization Symbols). The ppod table can
contain a ppod for each procedure identified in the procedure descrip‐
tor 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 han‐
dle 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 func‐
tions. (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 con‐
tains 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 descrip‐
tor, 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 pro‐
cedure 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.
RETURN VALUES
All functions indicate success by returning a value of 0 (zero). A pos‐
itive 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.
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 sta‐
tus should be tested after each function call. See st_strerror(3) for
an example of return status testing. Reading and writing the symbol ta‐
ble 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_set‐
up(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); ...
FILES
Header file that contains definitions and function prototypes for
libst.a functions Header file that contains definitions for symbol ta‐
ble structures Header file that contains definitions of symbol table
constants
SEE ALSO
Functions: libst_intro(3), st_obj_open(3), st_obj_proc_start(3),
st_str_error(3)st_pt_setup(3)
