 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
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
fdrbuf
Specifies an address of a file descriptor table in memory.
fdrsize
Specifies the number of file descriptor entries.
pdrbuf
Specifies an address of a procedure descriptor table in memory.
pdrsize
Specifies the number of procedure descriptor entries.
optsym
Specifies an address of an optimization symbol table in memory.
optsize
Specifies the size in bytes of an optimization symbol table.
pt
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.
obj
Specifies an object handle, as returned by the st_obj_open function.
pp
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.
pp_cur
Specifies a ppod handle as returned by the st_pt_start, st_pt_next,
st_obj_proc_pp, or st_proc_pp functions.
proc
Specifies a procedure handle, as returned by a function such as
st_obj_proc_start.
has_ppods
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.
ipd
Specifies the index of a procedure descriptor table entry.
ppod
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.
ppod_cur
Specifies a ppod entry handle, as returned by the st_pp_start,
st_pp_next, or st_pp_find_tag functions.
ppod_next
Specifies an address to which st_pp_next returns a ppod entry handle.
tag
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:
PPODE_STAMP
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.
PPODE_END
Identifies the last ppod entry in a procedure. This entry is always
empty.
PPODE_EXT_SRC
Identifies a ppod entry that contains extended source location
information.
PPODE_SEM_EVENT
Identifies a ppod entry that contains semantic event debug
information.
PPODE_SPLIT
Identifies a ppod entry that contains split lifetime debug
information.
PPODE_DISCONTIG_SCOPE
Identifies a ppod entry that contains discontiguous scope debug
information.
PPODE_INLINED_CALL
Identifies a ppod entry that contains inlined procedure call debug
information.
PPODE_PROFILE_INFO
Identifies a ppod entry that contains profile feedback data.
len
Specifies either the length in bytes of a ppod entry's data or zero if
the data is immediate.
data
Specifies either the address of a ppod entry's data or the data itself.
dlen
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.
dptr
Specifies an address to which st_ppod_data returns either the address of
a ppod entry's data or the data itself.
fddata
Specifies an address to which st_pt_layout returns the address of an
output file descriptor table.
fdlen
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.
pddata
Specifies an address to which st_pt_layout returns the address of an
output procedure descriptor table.
pdlen
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.
ppdata
Specifies an address to which st_pt_layout returns the address of an
output ppod table.
pplen
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
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.
st_obj_pt_setup and st_pt_setup
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.
st_pt_start and st_pt_next
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.)
st_obj_proc_has_ppod and st_proc_has_ppod
These functions test that the specified procedure's ppod is not empty and
return a Boolean result to the has_ppods parameter.
st_obj_proc_pp and st_proc_pp
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.
st_pp_start and st_pp_next
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.)
st_pp_find_tag
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.)
st_pp_add, st_pp_append, and st_pp_delete
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.
st_pp_print and st_ppod_print
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.
st_ppod_tag and st_ppod_data
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.
st_pt_layout
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.
st_pt_cleanup
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 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);
...
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 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 non-zero return status is the
recommended method for detecting an error return from a libst function.
FILES
/usr/include/st.h
Header file that contains definitions and function prototypes for libst.a
functions
/usr/include/sym.h
Header file that contains definitions for symbol table structures
/usr/include/symconst.h
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|