xlate_pro_add_range(3E)

NAME
     xlate_pro_add_range - add 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
             The low address in a range of text instructions in the output
             (post-transformation) text.

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

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

     old_range
             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 can not 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, a pair of calls like

          res = xlate_pro_add_range(protab,12, 8, 12,4);
          res = xlate_pro_add_range(protab,16,24, 16,8);
     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.

     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 not normally detect any error in the input sequence.

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. In case of error, therefore, the byte stream is quite useless.

     Error return values are:

     XLATE_TB_STATUS_INVALID_TABLE
             meaning that 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
             meaning that 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
             meaning malloc of memory to record translation information
             failed.

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

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

     XLATE_TB_STATUS_INVALID_SEQUENCE
             means that 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
     libelfutil(5), xlate(4), xlate_pro_init(3e), xlate_pro_finish(3e),
     xlate_pro_add_reg_info(3e)