 |
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
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
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.
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 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 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);
...
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
SEE ALSO
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 |
|