*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> st_pp_next (3)              
Title
Content
Arch
Section
 

st_pt_setup(3)

Contents


NAME    [Toc]    [Back]

       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    [Toc]    [Back]

       #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    [Toc]    [Back]

       Symbol Table and Object File Access Library (libst.a)

PARAMETERS    [Toc]    [Back]

       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.

DESCRIPTION    [Toc]    [Back]

       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.

RETURN VALUES    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       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

SEE ALSO    [Toc]    [Back]

      
      
       Functions:         libst_intro(3),         st_obj_open(3),
       st_obj_proc_start(3), st_str_error(3)



                                                   st_pt_setup(3)
[ Back ]
 Similar pages
Name OS Title
libst Tru64 symbol table and object file access library
libst_intro Tru64 symbol table and object file access library
ldgetname Tru64 retrieve symbol name for object file symbol table entry
ldgetname IRIX retrieve symbol name for object file symbol table entry
st_cm_del_entry Tru64 access and modify comment section information in an object file
st_cm_print Tru64 access and modify comment section information in an object file
st_cm_delete Tru64 access and modify comment section information in an object file
st_cm_next Tru64 access and modify comment section information in an object file
st_cm_get_flags Tru64 access and modify comment section information in an object file
st_cm_layout Tru64 access and modify comment section information in an object file
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service