xlate_address(3E)

NAME
     xlate_address - do 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
     );

DESCRIPTION
     xlate_address does 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

          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. Its arguments are:

     con_table_ptr
             must be 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
             is the input address.  Addresses must be a multiple of 4.  The
             library does not check the alignment of the passed-in address.

     address_out
             is the output address (returned thru the pointer argument).  The
             output address value will 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 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).  Error codes that may be
     returned are:

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

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

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