xlate_pro_add_range(3E)

NAME
     xlate_pro_add_range - Adds a translation range

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

     int xlate_pro_add_range(xlate_table_pro pro_table_ptr,
       Elf64_Addr  new_address,
       Elf64_Xword new_range,
       Elf64_Addr  old_address,
       Elf64_Xword old_range );

DESCRIPTION
     xlate_pro_add_range is used to put the translation ranges into the
     xlate data stream.  pro_table_ptr must be a valid open producer
     translate table handle.

     new_address
             Specifies the low address in a range of text instructions in
             the output (post-transformation) text.

     new_range
             Specifies the number of bytes in the range.  All byte counts
             must be a multiple of 4.

     old_address
             Specifies the low address in a range of text instructions in
             the input (pre-transformation) text.

     old_range
             Specifies the number of bytes in the range.  All byte counts
             must be a multiple of 4.

     It is absolutely vital that the new_address plus new_range of call N
     of xlate_pro_add_range have the same value as the new_address of call
     N+1.  If this is not true, the library may silently generate
     transformation information that cannot be read back correctly by the
     consumer xlate routines.  In other words, gaps in the new_address are
     not allowed.

     If the combination of an address and range pair overlaps an address
     and range pair in some other call, the input is considered ill-formed.

     For example, the following pair of calls is erroneous because the
     new_address ranges overlap (12 + 8 is 20 which is inside the range
     16,16+24).  The old_address ranges do not overlap each other so there
     is no error in those arguments.  The new address range overlap of the
     old address range is not an error.

          res = xlate_pro_add_range(protab,12, 8, 12,4);
          res = xlate_pro_add_range(protab,16,24, 16,8);

     If xlate_tk_preserve_order is the translation block format in use,
     then old_address must also be increasing and the old_address+old_range
     of one call must equal the old_address of the next call.

     If xlate_tk_preserve_size is the translation block format in use, then
     the new_range and old_range must be identical.

     The library will usually not detect any error in the input sequence.

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.

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 added to the byte stream being prepared unless there is a
     consumer-table merge being done, in which case there may be some
     entries added.

     Error return values are:

     XLATE_TB_STATUS_INVALID_TABLE
             pro_table_ptr does not point to a valid open handle on a
             translation.  This could be due to malloc arena corruption,
             writing on the beggining of the data pointed to by
             pro_table_ptr, or it could be caused by using an uninitialized
             or no-longer-open pro_table_ptr handle.

     XLATE_TB_STATUS_ADD_TOO_LATE
             xlate_pro_disk_header has already been called on this
             translation handle.  All ranges must be added before calling
             xlate_pro_disk_header.

     XLATE_TB_STATUS_ALLOC_FAIL
             malloc of memory to record translation information failed.

     XLATE_TB_STATUS_UNEQUAL_RANGE
             An attempt to add a preserve_size range was made but the two
             ranges were not identical.

     XLATE_TB_STATUS_INVALID_PO_INPUT
             In an attempt to add a range in a preserve-order table, the
             new address was lower than the previous range's address+range
             (could be either the new or old address+range).

     XLATE_TB_STATUS_INVALID_SEQUENCE
             The new-address was not identical to the previous new-address
             plus the previous new-range.  Or, in the case of preserve-size
             input, means that the old-address was not identical to the
             previous old-address plus the previous old-range.

             In addition, error values from xlate_address(3e) may be
             returned (if a consumer-table merge is being done).

SEE ALSO
     xlate_pro_add_reg_info(3e), xlate_pro_finish(3e), xlate_pro_init(3e)

     xlate(4)

     libelfutil(5)