xlate_pro_init(3E)

NAME
     xlate_pro_init, xlate_tablekind, xlate_table_con - Opens translation
     section creator

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

     int xlate_pro_init( xlate_table_pro  *returned_table_pointer,
      xlate_tablekind tablekind,
      xlate_table_con compose_with_table,
       int is64bit);

DESCRIPTION
     The xlate_pro_init, xlate_tablekind, and xlate_table_con functions are
     used to get (open) a handle which assists in producing a translation
     table section.  The functions themselves do not write anything to
     disk. Instead, they create a byte stream which the calling application
     can write to an Elf file as appropriate.

     The handle allows one to call any of the producer functions.

     xlate_pro_init accepts the following arguments:

     returned_table_pointer
             Pointer to a producer table handle.  If the call to
             xlate_pro_init is successful, the handle pointed to is set a
             valid producer library handle.

     tablekind
             Must be one of the types of table defined in the following
             enumeration:  order-preserving, size-preserving, or general.
             See <libXlate.h>.  The order-preserving and size-preserving
             cases allow a slightly more compact disk representation to be
             used.  See the TABLE KINDS section on this man page for more
             information about the table choices.

     compose_with_table
             Must be 0 or a valid open handle on a (nondebug) translate
             table section.  If 0 (the NULL pointer), then the byte stream
             prepared by the library will depend solely on the input from
             producer calls.  A 0 argument means that there will be a
             single byte stream available in the output.  If an open
             consumer handle is passed in, then the library will compose
             the information passed in through producer calls with the
             information from compose_with_table and will make available
             two byte stream outputs:  one will be the composed translation
             table representing all translations and the second (debug)
             table will represent the information passed in through
             producer calls.  xlate_pro_disk_header(3e) gives access to the
             usual (standard) byte stream if called with
             XLATE_PRO_STANDARD_SETUP.  xlate_pro_disk_header(3) gives
             access to the debug stream if called with
             XLATE_PRO_STANDARD_SETUP.  The debug stream will only have
             non-zero length if compose_with_table is a non-NULL consumer
             table handle.

     is64bit Informs the producer library whether the translate table is
             for a 64-bit or 32-bit executable or DSO.  Pass in 0 if for a
             32-bit executable or DSO.  Pass in 1 if for a 64-bit
             executable or DSO.  The flag must match (in the sense of being
             32- or 64-bit) the 64-bitness of the data in the
             compose_with_table.

     Use -lelfutil -lelf on the link command line to link in libelfutil.

TABLE KINDS
     The tablekind argument specifies characteristics of the addresses and
     ranges passed in to the producer functions.  If there is no Table
     Composition (because compose_with_table is NULL), then the tablekind
     argument is the output non-debug table kind (no debug table is
     produced).  If there is Table Composition because compose_with_table
     is non-NULL, then the table kind of the created table may not be
     identical to that specified in the argument.

     If the application specifies that the input is order-preserving and
     then executes xlate_pro_add_range calls which violate that assertion,
     the library may or may not detect the violation. The resulting table
     is not going to be correct in such a case.

     An order-preserving table (xlate_tk_preserve_size) is created by calls
     to xlate_pro_add_range in which successive new-addresses are
     increasing and successive old-addresses are increasing.

     A size-preserving table (xlate_tk_preserve_size) is created by calls
     to xlate_pro_add_range in which the new-range and the old-range are
     identical values (in other words, the new and old instruction streams
     are identical length).  The library assumes that the new-instruction
     addresses form a strictly increasing sequence (the old-instruction
     addresses ordinarily do not).

     A general table is any table not fitting one of the two special
     previously described cases.  The library assumes that the new-
     instruction addresses form a strictly increasing sequence (so that
     while the library can handle "general" transformations, the order that
     the transformations are presented to xlate_pro_add_range is restricted
     to be in increasing new-address order).

TABLE COMPOSITION
     Table composition allows the application of a (potentially unlimited)
     series of transformation tools while preserving the ability to use a
     debugger or other tool needing to correctly associate text address in
     memory with the symbolic information and with the original
     untransformed text addresses.  If compose_with_table is NULL then
     Table Composition is not done (there being no input table provided to
     compose with).

     If compose_with_table is non-NULL then table composition will occur.
     Composing a size-preserving with a size-preserving table results in a
     size-preserving table.  Composing an order-preserving with an order-
     preserving table results in a order-preserving table.  Any other
     composition results in a general table.

     The application doing the transformation should treat its composition
     as the only composition and should treat the executable text as being
     transformed.  The library does the composition.

     Composition of addresses is done by the library.  The following
     describes how each of the fields in the each of the translate headers
     is treated.

     hd_version
             This will be the same in the output of both the debug and
             non-debug tables.

     hd_tablekind
             This will be taken directly from the tablekind argument for
             the debug table.  For the non-debug table, the value will be
             as described in the TABLE KINDS section on this man page.

     hd_block_size
             The library supplies this value for both the debug and non-
             debug tables.  (It is a fixed value of 4096).

     hd_num_blocks
             This value is set appropriately by the library for each table
             output.

     hd_num_entries
             This value is set appropriately by the library for each table
             output.

     hd_new_addr_low
             This is the lowest of the new addresses and will be the same
             value for both the tables.

     hd_new_addr_high
             This is the highest of the new addresses and will be the same
             value for both the tables.

     hd_old_addr_low
             For the non-debug table, this is copied from the
             hd_old_addr_low of the input table-to-be-composed-with.  For
             the debug table, this is calculated from the ranges seen by
             xlate_pro_add_range.

     hd_old_addr_high
             For the non-debug table, this is copied from the
             hd_old_addr_high of the input table-to-be-composed-with.  For
             the debug table, this is calculated from the ranges seen by
             xlate_pro_add_range.

     hd_data_moved
             For the debug table, this is taken from the xlate_pro_add_info
             call (defaults to 0).  For the non-debug table, the output
             value is the sum (using 32-bit arithmetic for 32-bit programs
             and 64-bit arithmetic for 64-bit programs) of the
             hd_data_moved argument from the input table-to-be-composed-
             with and the data_moved argument of the xlate_pro_add_info
             call.

     hd_startup_fwa
             For the debug table, this is taken from the appropriate
             xlate_pro_add_info call argument (defaults to 0).  For the
             non-debug table, take that argument if non-zero; if the
             xlate_pro_add_info is not provided or the argument is 0, take
             the value from the hd_startup_fwa from the input table-to-be-
             composed-with.

     hd_startup_lwa
             For the debug table, this is taken from the appropriate
             xlate_pro_add_info call argument (defaults to 0).  For the
             non-debug table, take that argument if non-zero; if the
             xlate_pro_add_info is not provided or the argument is 0; take
             the value from the hd_startup_lwa from the input table-to-be-
             composed-with.

     hd_old_text_exists
             For the non-debug table, take the value from the input table-
             to-be-composed with.  For the debug table, take the value from
             the xlate_pro_add_info call argument (defaults to 0).

     hd_old_text_alloc
             For the non-debug table, take the value from the input table-
             to-be-composed with.  For the debug table, take the value from
             the xlate_pro_add_info call argument (defaults to 0).

     hd_reg_info_size
             For the debug table, take the data provided with
             xlate_pro_add_reg_info calls.  For the non-debug table, add
             the data provided with xlate_pro_add_reg_info calls to the end
             of the data in the input table-to-be-composed-with.  This
             behavior is incorrect, since any DW_CFA_set_loc or
             DW_CFA_advance_loc operations in the table-to-be-composed-with
             are not updated appropriately.

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
     XLATE_TB_STATUS_NO_ERROR (0) is returned 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).

     The following error returns are possible:

     XLATE_TB_STATUS_BAD_TABLEKIND
             The passed in tablekind is not one of the three defined
             values.

     XLATE_TB_STATUS_ALLOC_FAIL
             malloc() failed.

     XLATE_TB_STATUS_PRO_CON_TABLE_MISMATCH
             The compose_with_table and the table being created are not
             both 64-bit or both 32-bit. Instead, one is marked as a 32-bit
             translation table and the other is 64-bit.

             In addition, if the compose_with_table is non-null, then any
             error which might be returned by xlate_get_info() on the
             compose_with_table may be returned.

NOTES
     Any register information in a table-to-be-composed-with that contains
     a DW_CFA_set_loc or DW_CFA_advance_loc operation is not updated or
     corrected by the library at present: this is a bug.

     If an xlate section is created in an Elf file, it is required to have
     at least one range record.  An xlate section without at least one
     range is illegal (and the effect is undefined).

SEE ALSO
     xlate_init_fd(3e), xlate_pro_add_info(3e), xlate_pro_add_range(3e),
     xlate_pro_add_reg_info(3e), xlate_pro_disk_header(3e),
     xlate_pro_disk_next_block(3e), xlate_pro_finish(3e)

     xlate(4)

     libelfutil(5)