xlate_expand_reg_info(3E)

NAME
     xlate_expand_reg_info, xlate_expand_reg_info2 - Expands 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 commands are useful for programs like elfdump(1) to show the
     actual contents of the register location expressions.  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.

     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 performing
     malloc on 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 are accepted by xlate_expand_reg_info and
     xlate_expand_reg_info2:

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

     The following arguments are pointers through which values are
     returned.

     num_instrs      Number of elements in the instructions array.

     instructions    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 the
     following:

     sr_op   An 8-bit op-code possibly ORd with data.

     sr_val1 A 64-bit value, whose meaning depends on sr_op.

     sr_val2 A 64-bit value whose meaning depends on sr_op.

     sr_instr_offset
             (xlate_reg_instr2 only) Byte offset of the sr_op in the
             register instruction byte stream (before unpacking the byte
             stream).

EXAMPLES
     The following is an example of the use of xlate_reg_instr2/*E:

          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

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

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.

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

     XLATE_TB_STATUS_NO_REG_INFO
             No register information is available.  Typically, this means
             the translation was done by cord(1).  This is actually not an
             error but rather a special status indicator that applications
             need to anticipate.

     XLATE_TB_STATUS_INVALID_TABLE
             The tab argument is not a valid open consumer table or 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
             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.

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

     XLATE_TB_STATUS_REG_REQUEST_BOGUS
             There is an internal error in this libelfutil function.

SEE ALSO
     xlate_get_reg_rule(3e), xlate_init_fd(3e), xlate_finish(3e),
     xlate_pro_init(3e), xlate_pro_finish(3e), xlate(4), libelfutil(5),