xlate_pro_disk_header(3E)

NAME
     xlate_pro_disk_header - Gets 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, call
     xlate_pro_disk_block number-of-blocks times to get pointers to 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 through the pointer arguments.

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

     If there are no translations, the block count and length will be
     returned as 0.

     xlate_pro_disk_header accepts the following arguments:

     pro_table_ptr  Specifies 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.

EXAMPLES
     The following example shows typical use of the functions:

          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);
          }

THREAD SAFETY
     The xlate functions are thread safe.  This means that if distinct
     xlate_table_con and xlate_table_pro handles are used in distinct
     threads to call xlate functions simultaneously in multiple threads,
     the threads will not interfere.

     However, using a particular xlate_table_con handle or a particular
     xlate_table_pro handle to call xlate functions simultaneously in
     multiple threads is not supported and may cause unpredictable results.

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
     XLATE_TB_STATUS_NO_ERROR (0) is returned 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.

     The following error returns are possible:

     XLATE_TB_STATUS_INVALID_TABLE
             The table is not a valid open producer handle.

     XLATE_TB_STATUS_PRO_REQ_INVALID
             The standard_or_debug argument is neither
             XLATE_PRO_STANDARD_SETUP nor XLATE_PRO_DEBUG_SETUP.

SEE ALSO
     xlate_pro_init(3e), xlate_pro_finish(3e),
     xlate_pro_disk_next_block(3e)

     xlate(4)

     libelfutil(5)