xlate_expand_reg_info(3E)

NAME
     xlate_expand_reg_info: xlate_expand_reg_info2 - expand register
     instructions

SYNOPSIS
     #include <elf.h>
     #include <libelf.h>
     #include <dwarf.h>
     #include <libdwarf.h>
     #include <cmplrs/xlate.h>
     #include <libXlate.h>
     int xlate_expand_reg_info(xlate_table_con con_table_ptr,
       Elf64_Xword      *num_instrs,
       xlate_reg_instr  **instructions
     );
     int xlate_expand_reg_info2(xlate_table_con con_table_ptr,
       Elf64_Xword      *num_instrs,
       xlate_reg_instr2  **instructions
     );

DESCRIPTION
     These are useful for programs like elfdump(1) to show the actual contents
     of the register location expressions.  These are otherwise very useful.
     The functions and the values returned throught the pointers are identical
     except that xlate_reg_instr2 has an extra field in the definition.  The
     extra field, sr_instr_offset, is the byte offset in the register
     instruction stream of the first byte of the particular register
     instruction.

     Aside from the additional field in the structure the functions are
     identical.

     xlate_reg_instr is now considered obsolete.  Applications should cease
     using it in favor of xlate_reg_instr2.

     Applications desiring the fastest possible speed will want to call
     xlate_expand_reg_info2 rather than xlate_expand_reg_info as the former is
     slightly faster (the latter is implemented by mallocing another array and
     copying portions of the xlate_reg_instr2 array and it is the malloc and
     copying that slows xlate_reg_instr down in this implementation).

     The arguments of xlate_expand_reg_info and xlate_expand_reg_info2 are:

     con_table_ptr
             which must be a valid open handle on a translation section.

     The following arguments are pointers thru which values are returned.

     num_instrs
             The value is the number of elements in the instructions array.
     instructions
             The value is a pointer to an array of xlate_reg_instr structs.
             This array must be free(2)d by the application to avoid memory
             leakage.

     See xlate(4) for detailed information on the way each element of this
     array is actually filled out.  Each element of the array contains

     sr_op   which is an 8-bit op-code possibly ORd with data.

     sr_val1 Which is a 64-bit value  whose meaning depends on sr_op .

     sr_val2 Which is a 64-bit value whose meaning depends on sr_op .

     sr_instr_offset
             appears only in the  xlate_reg_instr2 version and is the byte
             offset of the sr_op in the register instruction byte stream
             (before unpacking the byte stream).

     A sample use is:
          int result;
          xlate_reg_instr2 *instructions;
          Elf64_Xword num_instrs;
          result = xlate_expand_reg_info2(con_table,
              &num_instrs,
              &instructions);
          for(i = 0; i < num_instrs; ++i)
          {
            printf("%d %lld %lld %ld0,
             (int)instructions[i].sr_op,
             (long long)instructions[i].sr_val1,
             (long long)instructions[i].sr_val2,
             (long)instructions[i].sr_val2,
          }
          free(instructions);

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
     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 which would return values
     on successful call (values might have been changed thru these pointers
     but any such changes are not meaningful).

     XLATE_TB_STATUS_NO_REG_INFO
             meaning that there is no register info available.  Typically,
             this means the translation was done by cord(1).  This is really
             not an error. It is a special status indicator applications need
             to anticipate.

     XLATE_TB_STATUS_INVALID_TABLE
             means that the tab argument is not a valid open consumer table or
             that the data pointed at has been corrupted by a malloc arena
             corruption.

     XLATE_TB_STATUS_ALLOC_FAIL
             A call to malloc() or realloc() failed.

     XLATE_TB_STATUS_BAD_REG_VAL
             means that the register number (somewhere in the table) is too
             large to be used as an index into the Dwarf_Regtable array (see
             <libdwarf.h>).  This is either a memory corruption, a bogus
             register area on the Elf xlate section, or an internal logic
             error in the internals of this libelfutil function.  Should never
             happen.

     XLATE_TB_STATUS_BAD_FRAME_OP
             means that the Dwarf frame op code is not one of the ones
             expected.  This is data corruption or an internal error in this
             libelfutil function.  Should never happen.

     XLATE_TB_STATUS_REG_REQUEST_BOGUS
             This is an internal error in this libelfutil function.  Should
             never happen.

SEE ALSO
     libelfutil(5), xlate(4), xlate_get_reg_rule(3e), xlate_init_fd(3e),
     xlate_finish(3e), xlate_pro_init(3e), xlate_pro_finish(3e), DWARF
     Debugging Information Format , A Consumer Library Interface to DWARF