XLATE_PRO_ADD_RANGE(3E)XLATE_PRO_ADD_RANGE(3E)NAMExlate_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
);
DESCRIPTIONxlate_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);
Page 1
XLATE_PRO_ADD_RANGE(3E)XLATE_PRO_ADD_RANGE(3E)
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.
Page 2
XLATE_PRO_ADD_RANGE(3E)XLATE_PRO_ADD_RANGE(3E)
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 ALSOlibelfutil(5), xlate(4), xlate_pro_init(3e), xlate_pro_finish(3e),
xlate_pro_add_reg_info(3e)
Page 3
