xlate_pro_disk_header(3E)

NAME
     xlate_pro_disk_header - get translation byte stream block count

SYNOPSIS
     #include <elf.h>
     #include <libelf.h>
     #include <dwarf.h>
     #include <libdwarf.h>
     #include <cmplrs/xlate.h>
     #include <libXlate.h>
     int xlate_pro_disk_header(xlate_table_pro pro_table_ptr,
       int          standard_or_debug,
       Elf64_Xword *total_memory_required,
       Elf64_Xword *number_of_blocks
     );

DESCRIPTION
     This function gets the total size and the number-of-blocks of either the
     standard or debug stream of data.  Following this one calls
     xlate_pro_disk_block number-of-blocks times to get pointers the blocks of
     actual data bytes of the byte stream.  The library does not write
     anything to disk.  It is up to the application calling the library to
     write the information to disk (or to do whatever else is appropriate with
     the byte stream).

     xlate_pro_disk_header gets the size of the net translation table data
     stream thru the pointer arguments.

     If there are no translation ranges supplied but there  is register
     information supplied (or if there is a consumer translation table
     supplied) an output stream may have non-zero length and block count but
     such a stream is surely useless.

     If there are no translations the block count and length will be returned
     as 0 (see below).

     The arguments are a as follows.

     pro_table_ptr must be a valid open producer translate table handle.

     standard_or_debug specifies whether the byte stream returned by calls to
     xlate_pro_disk_next_block is the standard or debug stream.  Call with
     XLATE_PRO_STANDARD_SETUP to request the standard stream.  Call with
     XLATE_PRO_DEBUG_SETUP to request the debug stream.

     total_memory_required
             The pointed at memory is set to the total number of bytes in the
             translation byte stream.  If there is no translation data the
             pointed at memory will be set to 0.
     number_of_blocks
             The pointed at memory is set to the number of calls of
             xlate_pro_disk_next_block required to get pointers to the pieces
             of the byte stream.  If there is no translation data the pointed
             at memory will be set to 0.

     An example showing typical use of these functions follows.

          res = xlate_pro_disk_header(pro_tab,
                 XLATE_PRO_STANDARD_SETUP,
                     &totmem,&blk_ct);
          for( i = 0; i < blk_ct; ++i )
          {
            res = xlate_pro_disk_next_block(pro_tab,
                      &datap,&data_size);
            /* do something with the bytes*/
            free(datap);
          }
          res = xlate_pro_disk_header(pro_tab,
                 XLATE_PRO_DEBUG_SETUP
                     &totmemdebug,&blk_ctdebug);
          for( i = 0; i < blk_ctdebug; ++i )
          {
            res = xlate_pro_disk_next_block(pro_tab,
                  &datap,&data_size);
            /* do something with the bytes*/
            free(datap);
          }

FILES
     /usr/include/libXlate.h
     /usr/include/cmplrs/xlate.h
     /usr/include/elf.h
     /usr/include/dwarf.h
     /usr/include/libdwarf.h
     /usr/lib/libelfutil.a

DIAGNOSTICS
     This returns XLATE_TB_STATUS_NO_ERROR (0) on success.  In case of error,
     a negative number is returned indicating the error.  In case of error
     nothing is returned thru the pointer arguments.

     Error returns possible are:

     XLATE_TB_STATUS_INVALID_TABLE
             means that that the table is not a valid open producer handle.

     XLATE_TB_STATUS_PRO_REQ_INVALID
             means that the standard_or_debug argument is neither
             XLATE_PRO_STANDARD_SETUP nor XLATE_PRO_DEBUG_SETUP.
SEE ALSO
     libelfutil(5), xlate(4), xlate_pro_init(3e), xlate_pro_finish(3e),
     xlate_pro_disk_next_block(3e),