xlate_address(3E)

NAME
     xlate_address - Performs address translation

SYNOPSIS
     #include <elf.h>
     #include <libelf.h>
     #include <dwarf.h>
     #include <libdwarf.h>
     #include <cmplrs/xlate.h>
     #include <libXlate.h>

     int xlate_address(xlate_table_con con_table_ptr,
       int           is_new_address,
       Elf64_Addr  address_in,
       Elf64_Addr  *address_out,
       xlate_block *range
     );

IMPLEMENTATION
     IRIX systems

DESCRIPTION
     xlate_address performs the address translation needed by tools such as
     dbx(1) and dis(1).

     If address_in is an address that does not exist in the translation
     table, the identity translation is returned through the pointers and
     XLATE_TB_STATUS_NO_ERROR is returned by the function.

     The data structure, xlate_block, is defined to contain the following:

          Elf64_Addr          xe_new_address;
          Elf64_Xword         xe_new_range;
          Elf64_Addr          xe_old_address;
          Elf64_Xword         xe_old_range;

     This data structure is used for both 32 and 64 bit applications and
     DSOs.

     xlate_address translates an individual address.  It accepts the
     following arguments:

     con_table_ptr
             Specifies a valid open translation table handle.

     is_new_address
             Specifies which direction the translation is to be done.  If
             XLATE_ADDRESS_INPUT_NEW_ADDRESS (1), then the translation is
             done from a new (translated) to an old (original,
             untranslated) address.  If XLATE_ADDRESS_INPUT_OLD_ADDRESS
             (0), then the translation is done from an old (original,
             untranslated text) address to a new (translated) address.  Any
             value other than 0 or 1 passed in can produce invalid results
             (the library reserves all other values for its own internal
             use).

     address_in
             Specifies the input address.  The address value must be a
             multiple of 4.  The library does not check the alignment of
             the passed-in address.

     address_out
             Specifies the output address (returned through the pointer
             argument).  The address value must be a multiple of 4.

     range   Must be the NULL pointer (0) or a valid pointer to an
             xlate_block structure provided by the caller.  If range is 0
             then it is ignored.  If range is non-0 then the structure
             pointed to is filled in by xlate_address.  In the filled-in
             structure, xe_new_address and xe_range always refer to the new
             (translated) text, and xe_old_address and xe_old_range always
             refer to the old (untranslated) text regardless of the value
             of is_new_address.  All the xe_* values will be a multiple of
             4.

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 through the pointer arguments which would return
     values on a successful call (values might have been changed through
     these pointers but any such changes are not meaningful).  The
     following error codes may be returned:

     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_BAD_BLOCK_INDEX
             The library has somehow made an internal error (should not
             happen unless a portion of memory was corrupted).

     XLATE_TB_STATUS_NOT_YET_IMPLEMENT
             A table kind that was thought not to exist has been
             encountered.  This should have been caught by a table
             initialization call (xlate_init_fd or xlate_init_elf).  This
             suggests that there was a memory corruption or internal
             library logic error.

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.

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

     This man page is available only online.