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

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)