IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/libelf/elf_getdata.z/elf_getdata

Text File | 1998-10-30 | 23.2 KB | 289 lines

EEEELLLLFFFF____GGGGEEEETTTTDDDDAAAATTTTAAAA((((3333EEEE))))                                                EEEELLLLFFFF____GGGGEEEETTTTDDDDAAAATTTTAAAA((((3333EEEE))))



NNNNAAAAMMMMEEEE
     _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa, _eeee_llll_ffff______nnnn_eeee_wwww_dddd_aaaa_tttt_aaaa, _eeee_llll_ffff______rrrr_aaaa_wwww_dddd_aaaa_tttt_aaaa - get section data

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _cccc_cccc [_f_l_a_g ...] _f_i_l_e ...  _----_llll_eeee_llll_ffff [_l_i_b_r_a_r_y ...]

     _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_llll_iiii_bbbb_eeee_llll_ffff_...._hhhh_>>>>
     _EEEE_llll_ffff______DDDD_aaaa_tttt_aaaa _****_eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa_((((_EEEE_llll_ffff______SSSS_cccc_nnnn _****_ssss_cccc_nnnn_,,,, _EEEE_llll_ffff______DDDD_aaaa_tttt_aaaa _****_dddd_aaaa_tttt_aaaa_))))_;;;;
     _EEEE_llll_ffff______DDDD_aaaa_tttt_aaaa _****_eeee_llll_ffff______nnnn_eeee_wwww_dddd_aaaa_tttt_aaaa_((((_EEEE_llll_ffff______SSSS_cccc_nnnn _****_ssss_cccc_nnnn_))))_;;;;
     _EEEE_llll_ffff______DDDD_aaaa_tttt_aaaa _****_eeee_llll_ffff______rrrr_aaaa_wwww_dddd_aaaa_tttt_aaaa_((((_EEEE_llll_ffff______SSSS_cccc_nnnn _****_ssss_cccc_nnnn_,,,, _EEEE_llll_ffff______DDDD_aaaa_tttt_aaaa _****_dddd_aaaa_tttt_aaaa_))))_;;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     These functions access and manipulate the data associated with a section
     descriptor, _s_c_n.  When reading an existing file, a section will have a
     single data buffer associated with it.  A program may build a new section
     in pieces, however, composing the new data from multiple data buffers.
     For this reason, ``the'' data for a section should be viewed as a list of
     buffers, each of which is available through a data descriptor.

     _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa lets a program step through a section's data list.  If the
     incoming data descriptor, _d_a_t_a, is null, the function returns the first
     buffer associated with the section.  Otherwise, _d_a_t_a should be a data
     descriptor associated with _s_c_n, and the function gives the program access
     to the next data element for the section.  If _s_c_n is null or an error
     occurs, _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa returns a null pointer.

     _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa translates the data from file representations into memory
     representations [see _eeee_llll_ffff______xxxx_llll_aaaa_tttt_eeee(3E)] and presents objects with memory data
     types to the program, based on the file's _c_l_a_s_s [see _eeee_llll_ffff(3E)].  The
     working library version [see _eeee_llll_ffff______vvvv_eeee_rrrr_ssss_iiii_oooo_nnnn(3E)] specifies what version of
     the memory structures the program wishes _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa to present.

     _eeee_llll_ffff______nnnn_eeee_wwww_dddd_aaaa_tttt_aaaa creates a new data descriptor for a section, appending it to
     any data elements already associated with the section.  As described
     below, the new data descriptor appears empty, indicating the element
     holds no data.  For convenience, the descriptor's type (_dddd______tttt_yyyy_pppp_eeee below) is
     set to _EEEE_LLLL_FFFF______TTTT______BBBB_YYYY_TTTT_EEEE, and the version (_dddd______vvvv_eeee_rrrr_ssss_iiii_oooo_nnnn below) is set to the
     working version.  The program is responsible for setting (or changing)
     the descriptor members as needed.  This function implicitly sets the
     _EEEE_LLLL_FFFF______FFFF______DDDD_IIII_RRRR_TTTT_YYYY bit for the section's data [see _eeee_llll_ffff______ffff_llll_aaaa_gggg(3E)].  If _s_c_n is
     null or an error occurs, _eeee_llll_ffff______nnnn_eeee_wwww_dddd_aaaa_tttt_aaaa returns a null pointer.

     _eeee_llll_ffff______rrrr_aaaa_wwww_dddd_aaaa_tttt_aaaa differs from _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa by returning only uninterpreted
     bytes, regardless of the section type.  This function typically should be
     used only to retrieve a section image from a file being read, and then
     only when a program must avoid the automatic data translation described
     below.  Moreover, a program may not close or disable [see _eeee_llll_ffff______cccc_nnnn_tttt_llll(3E)]
     the file descriptor associated with _e_l_f before the initial raw operation,
     because _eeee_llll_ffff______rrrr_aaaa_wwww_dddd_aaaa_tttt_aaaa might read the data from the file to ensure it
     doesn't interfere with _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa.  See _eeee_llll_ffff______rrrr_aaaa_wwww_ffff_iiii_llll_eeee(3E) for a related
     facility that applies to the entire file.  When _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa provides the


                                                                        PPPPaaaaggggeeee 1111






EEEELLLLFFFF____GGGGEEEETTTTDDDDAAAATTTTAAAA((((3333EEEE))))                                                EEEELLLLFFFF____GGGGEEEETTTTDDDDAAAATTTTAAAA((((3333EEEE))))



     right translation, its use is recommended over _eeee_llll_ffff______rrrr_aaaa_wwww_dddd_aaaa_tttt_aaaa.  If _s_c_n is
     null or an error occurs, _eeee_llll_ffff______rrrr_aaaa_wwww_dddd_aaaa_tttt_aaaa returns a null pointer.

     The _EEEE_llll_ffff______DDDD_aaaa_tttt_aaaa structure includes the following members.

                  _vvvv_oooo_iiii_dddd            _****_dddd______bbbb_uuuu_ffff_;;;;
                  _EEEE_llll_ffff______TTTT_yyyy_pppp_eeee        _dddd______tttt_yyyy_pppp_eeee_;;;;
                  _ssss_iiii_zzzz_eeee______tttt          _dddd______ssss_iiii_zzzz_eeee_;;;;
                  _oooo_ffff_ffff______tttt           _dddd______oooo_ffff_ffff_;;;;
                  _ssss_iiii_zzzz_eeee______tttt          _dddd______aaaa_llll_iiii_gggg_nnnn_;;;;
                  _uuuu_nnnn_ssss_iiii_gggg_nnnn_eeee_dddd        _dddd______vvvv_eeee_rrrr_ssss_iiii_oooo_nnnn_;;;;

     These members are available for direct manipulation by the program.
     Descriptions appear below.

     _dddd______bbbb_uuuu_ffff         A pointer to the data buffer resides here.  A data element
                   with no data has a null pointer.

     _dddd______tttt_yyyy_pppp_eeee        This member's value specifies the type of the data to which
                   _dddd______bbbb_uuuu_ffff points.  A section's type determines how to interpret
                   the section contents, as summarized below.

     _dddd______ssss_iiii_zzzz_eeee        This member holds the total size, in bytes, of the memory
                   occupied by the data.  This may differ from the size as
                   represented in the file.  The size will be zero if no data
                   exist.  [See the discussion of _SSSS_HHHH_TTTT______NNNN_OOOO_BBBB_IIII_TTTT_SSSS below for more
                   information.]

     _dddd______oooo_ffff_ffff         This member gives the offset, within the section, at which
                   the buffer resides.  This offset is relative to the file's
                   section, not the memory object's.

     _dddd______aaaa_llll_iiii_gggg_nnnn       This member holds the buffer's required alignment, from the
                   beginning of the section.  That is, _dddd______oooo_ffff_ffff will be a
                   multiple of this member's value.  For example, if this
                   member's value is four, the beginning of the buffer will be
                   four-byte aligned within the section.  Moreover, the entire
                   section will be aligned to the maximum of its constituents,
                   thus ensuring appropriate alignment for a buffer within the
                   section and within the file.

     _dddd______vvvv_eeee_rrrr_ssss_iiii_oooo_nnnn     This member holds the version number of the objects in the
                   buffer.  When the library originally read the data from the
                   object file, it used the working version to control the
                   translation to memory objects.

DDDDAAAATTTTAAAA AAAALLLLIIIIGGGGNNNNMMMMEEEENNNNTTTT
     As mentioned above, data buffers within a section have explicit alignment
     constraints.  Consequently, adjacent buffers sometimes will not abut,
     causing ``holes'' within a section.  Programs that create output files
     have two ways of dealing with these holes.




                                                                        PPPPaaaaggggeeee 2222






EEEELLLLFFFF____GGGGEEEETTTTDDDDAAAATTTTAAAA((((3333EEEE))))                                                EEEELLLLFFFF____GGGGEEEETTTTDDDDAAAATTTTAAAA((((3333EEEE))))



     First, the program can use _eeee_llll_ffff______ffff_iiii_llll_llll to tell the library how to set the
     intervening bytes.  When the library must generate gaps in the file, it
     uses the fill byte to initialize the data there.  The library's initial
     fill value is zero, and _eeee_llll_ffff______ffff_iiii_llll_llll lets the application change that.

     Second, the application can generate its own data buffers to occupy the
     gaps, filling the gaps with values appropriate for the section being
     created.  A program might even use different fill values for different
     sections.  For example, it could set text sections' bytes to no-operation
     instructions, while filling data section holes with zero.  Using this
     technique, the library finds no holes to fill, because the application
     eliminated them.

SSSSEEEECCCCTTTTIIIIOOOONNNN AAAANNNNDDDD MMMMEEEEMMMMOOOORRRRYYYY TTTTYYYYPPPPEEEESSSS
     _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa interprets sections' data according to the section type, as
     noted in the section header available through _eeee_llll_ffff______gggg_eeee_tttt_ssss_hhhh_dddd_rrrr.  The following
     table shows the section types and how the library represents them with
     memory data types for the 32-bit file class.  Other classes would have
     similar tables.  By implication, the memory data types control
     translation by _eeee_llll_ffff______xxxx_llll_aaaa_tttt_eeee.

                     Section Type    _EEEE_llll_ffff______TTTT_yyyy_pppp_eeee     32-Bit Type
                     _________________________________________
                     _SSSS_HHHH_TTTT______DDDD_YYYY_NNNN_AAAA_MMMM_IIII_CCCC    _EEEE_LLLL_FFFF______TTTT______DDDD_YYYY_NNNN    _EEEE_llll_ffff_3333_2222______DDDD_yyyy_nnnn
                     _SSSS_HHHH_TTTT______DDDD_YYYY_NNNN_SSSS_YYYY_MMMM     _EEEE_LLLL_FFFF______TTTT______SSSS_YYYY_MMMM    _EEEE_llll_ffff_3333_2222______SSSS_yyyy_mmmm
                     _SSSS_HHHH_TTTT______HHHH_AAAA_SSSS_HHHH       _EEEE_LLLL_FFFF______TTTT______WWWW_OOOO_RRRR_DDDD   _EEEE_llll_ffff_3333_2222______WWWW_oooo_rrrr_dddd
                     _SSSS_HHHH_TTTT______NNNN_OOOO_BBBB_IIII_TTTT_SSSS     _EEEE_LLLL_FFFF______TTTT______BBBB_YYYY_TTTT_EEEE   _uuuu_nnnn_ssss_iiii_gggg_nnnn_eeee_dddd _cccc_hhhh_aaaa_rrrr
                     _SSSS_HHHH_TTTT______NNNN_OOOO_TTTT_EEEE       _EEEE_LLLL_FFFF______TTTT______BBBB_YYYY_TTTT_EEEE   _uuuu_nnnn_ssss_iiii_gggg_nnnn_eeee_dddd _cccc_hhhh_aaaa_rrrr
                     _SSSS_HHHH_TTTT______NNNN_UUUU_LLLL_LLLL       _n_o_n_e         _n_o_n_e
                     _SSSS_HHHH_TTTT______PPPP_RRRR_OOOO_GGGG_BBBB_IIII_TTTT_SSSS   _EEEE_LLLL_FFFF______TTTT______BBBB_YYYY_TTTT_EEEE   _uuuu_nnnn_ssss_iiii_gggg_nnnn_eeee_dddd _cccc_hhhh_aaaa_rrrr
                     _SSSS_HHHH_TTTT______RRRR_EEEE_LLLL        _EEEE_LLLL_FFFF______TTTT______RRRR_EEEE_LLLL    _EEEE_llll_ffff_3333_2222______RRRR_eeee_llll
                     _SSSS_HHHH_TTTT______RRRR_EEEE_LLLL_AAAA       _EEEE_LLLL_FFFF______TTTT______RRRR_EEEE_LLLL_AAAA   _EEEE_llll_ffff_3333_2222______RRRR_eeee_llll_aaaa
                     _SSSS_HHHH_TTTT______SSSS_TTTT_RRRR_TTTT_AAAA_BBBB     _EEEE_LLLL_FFFF______TTTT______BBBB_YYYY_TTTT_EEEE   _uuuu_nnnn_ssss_iiii_gggg_nnnn_eeee_dddd _cccc_hhhh_aaaa_rrrr
                     _SSSS_HHHH_TTTT______SSSS_YYYY_MMMM_TTTT_AAAA_BBBB     _EEEE_LLLL_FFFF______TTTT______SSSS_YYYY_MMMM    _EEEE_llll_ffff_3333_2222______SSSS_yyyy_mmmm
                     _o_t_h_e_r          _EEEE_LLLL_FFFF______TTTT______BBBB_YYYY_TTTT_EEEE   _uuuu_nnnn_ssss_iiii_gggg_nnnn_eeee_dddd _cccc_hhhh_aaaa_rrrr
                     _________________________________________
                                  ||||||||||||||












                                               ||||||||||||||














     _eeee_llll_ffff______rrrr_aaaa_wwww_dddd_aaaa_tttt_aaaa creates a buffer with type _EEEE_LLLL_FFFF______TTTT______BBBB_YYYY_TTTT_EEEE.

     As mentioned above, the program's working version controls what
     structures the library creates for the application.  The library
     similarly interprets section types according to the versions.  If a
     section type ``belongs'' to a version newer than the application's
     working version, the library does not translate the section data.
     Because the application cannot know the data format in this case, the
     library presents an untranslated buffer of type _EEEE_LLLL_FFFF______TTTT______BBBB_YYYY_TTTT_EEEE, just as it
     would for an unrecognized section type.

     A section with a special type, _SSSS_HHHH_TTTT______NNNN_OOOO_BBBB_IIII_TTTT_SSSS, occupies no space in an object
     file, even when the section header indicates a non-zero size.
     _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa and _eeee_llll_ffff______rrrr_aaaa_wwww_dddd_aaaa_tttt_aaaa ``work'' on such a section, setting the _d_a_t_a



                                                                        PPPPaaaaggggeeee 3333






EEEELLLLFFFF____GGGGEEEETTTTDDDDAAAATTTTAAAA((((3333EEEE))))                                                EEEELLLLFFFF____GGGGEEEETTTTDDDDAAAATTTTAAAA((((3333EEEE))))



     structure to have a null buffer pointer and the type indicated above.
     Although no data are present, the _dddd______ssss_iiii_zzzz_eeee value is set to the size from
     the section header.  When a program is creating a new section of type
     _SSSS_HHHH_TTTT______NNNN_OOOO_BBBB_IIII_TTTT_SSSS, it should use _eeee_llll_ffff______nnnn_eeee_wwww_dddd_aaaa_tttt_aaaa to add data buffers to the section.
     These ``empty'' data buffers should have the _dddd______ssss_iiii_zzzz_eeee members set to the
     desired size and the _dddd______bbbb_uuuu_ffff members set to null.

EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     The following fragment obtains the string table that holds section names
     (ignoring error checking).  See _eeee_llll_ffff______ssss_tttt_rrrr_pppp_tttt_rrrr(3E) for a variation of string
     table handling.

          _eeee_hhhh_dddd_rrrr _==== _eeee_llll_ffff_3333_2222______gggg_eeee_tttt_eeee_hhhh_dddd_rrrr_((((_eeee_llll_ffff_))))_;;;;
          _ssss_cccc_nnnn _==== _eeee_llll_ffff______gggg_eeee_tttt_ssss_cccc_nnnn_((((_eeee_llll_ffff_,,,, _((((_ssss_iiii_zzzz_eeee______tttt_))))_eeee_hhhh_dddd_rrrr_----_>>>>_eeee______ssss_hhhh_ssss_tttt_rrrr_nnnn_dddd_xxxx_))))_;;;;
          _ssss_hhhh_dddd_rrrr _==== _eeee_llll_ffff_3333_2222______gggg_eeee_tttt_ssss_hhhh_dddd_rrrr_((((_ssss_cccc_nnnn_))))_;;;;
          _iiii_ffff _((((_ssss_hhhh_dddd_rrrr_----_>>>>_ssss_hhhh______tttt_yyyy_pppp_eeee _!!!!_==== _SSSS_HHHH_TTTT______SSSS_TTTT_RRRR_TTTT_AAAA_BBBB_))))
          _{{{{
                  _////_**** _nnnn_oooo_tttt _aaaa _ssss_tttt_rrrr_iiii_nnnn_gggg _tttt_aaaa_bbbb_llll_eeee _****_////
          _}}}}
          _dddd_aaaa_tttt_aaaa _==== _0000_;;;;
          _iiii_ffff _((((_((((_dddd_aaaa_tttt_aaaa _==== _eeee_llll_ffff______gggg_eeee_tttt_dddd_aaaa_tttt_aaaa_((((_ssss_cccc_nnnn_,,,, _dddd_aaaa_tttt_aaaa_))))_)))) _====_==== _0000 _||||_|||| _dddd_aaaa_tttt_aaaa_----_>>>>_dddd______ssss_iiii_zzzz_eeee _====_==== _0000_))))
          _{{{{
                  _////_**** _eeee_rrrr_rrrr_oooo_rrrr _oooo_rrrr _nnnn_oooo _dddd_aaaa_tttt_aaaa _****_////
          _}}}}

     The _eeee______ssss_hhhh_ssss_tttt_rrrr_nnnn_dddd_xxxx member in an ELF header holds the section table index of
     the string table.  The program gets a section descriptor for that
     section, verifies it is a string table, and then retrieves the data.
     When this fragment finishes, _dddd_aaaa_tttt_aaaa_----_>>>>_dddd______bbbb_uuuu_ffff points at the first byte of the
     string table, and _dddd_aaaa_tttt_aaaa_----_>>>>_dddd______ssss_iiii_zzzz_eeee holds the string table's size in bytes.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _eeee_llll_ffff(3E), _eeee_llll_ffff______cccc_nnnn_tttt_llll(3E), _eeee_llll_ffff______ffff_iiii_llll_llll(3E), _eeee_llll_ffff______ffff_llll_aaaa_gggg(3E), _eeee_llll_ffff______gggg_eeee_tttt_eeee_hhhh_dddd_rrrr(3E),
     _eeee_llll_ffff______gggg_eeee_tttt_ssss_cccc_nnnn(3E), _eeee_llll_ffff______gggg_eeee_tttt_ssss_hhhh_dddd_rrrr(3E), _eeee_llll_ffff______rrrr_aaaa_wwww_ffff_iiii_llll_eeee(3E), _eeee_llll_ffff______vvvv_eeee_rrrr_ssss_iiii_oooo_nnnn(3E),
     _eeee_llll_ffff______xxxx_llll_aaaa_tttt_eeee(3E).

NNNNOOOOTTTTEEEESSSS
     The 64-bit class functions work identically, simply replacing all
     instances of 32 in the descriptions with 64.
















                                                                        PPPPaaaaggggeeee 4444