home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libelf / elf_getdata.z / elf_getdata
Encoding:
Text File  |  2002-10-03  |  12.2 KB  |  219 lines
  1. ELF_GETDATA(3E)                                      Last changed: 10-13-98
  2.  
  3.  
  4. NNAAMMEE
  5.      eellff__ggeettddaattaa, eellff__nneewwddaattaa, eellff__rraawwddaattaa - Gets section data
  6.  
  7. SSYYNNOOPPSSIISS
  8.      cccc [_f_l_a_g ...] _f_i_l_e ...  --lleellff [_l_i_b_r_a_r_y ...]
  9.  
  10.      ##iinncclluuddee <<lliibbeellff..hh>>
  11.  
  12.      EEllff__DDaattaa **eellff__ggeettddaattaa((EEllff__SSccnn **ssccnn,, EEllff__DDaattaa **ddaattaa));;
  13.  
  14.      EEllff__DDaattaa **eellff__nneewwddaattaa((EEllff__SSccnn **ssccnn));;
  15.  
  16.      EEllff__DDaattaa **eellff__rraawwddaattaa((EEllff__SSccnn **ssccnn,, EEllff__DDaattaa **ddaattaa));;
  17.  
  18. IIMMPPLLEEMMEENNTTAATTIIOONN
  19.      IRIX systems
  20.  
  21. DDEESSCCRRIIPPTTIIOONN
  22.      These functions access and manipulate the data associated with a
  23.      section descriptor, ssccnn.  When reading an existing file, a section
  24.      will have a single data buffer associated with it.  A program may
  25.      build a new section in pieces, however, composing the new data from
  26.      multiple data buffers.  For this reason, the data for a section should
  27.      be viewed as a list of buffers, each of which is available through a
  28.      data descriptor.
  29.  
  30.      eellff__ggeettddaattaa lets a program step through a section's data list.  If the
  31.      incoming data descriptor, ddaattaa, is null, the function returns the
  32.      first buffer associated with the section.  Otherwise, ddaattaa should be a
  33.      data descriptor associated with ssccnn, and the function gives the
  34.      program access to the next data element for the section.  If ssccnn is
  35.      null or an error occurs, eellff__ggeettddaattaa returns a null pointer.
  36.  
  37.      eellff__ggeettddaattaa translates the data from file representations into memory
  38.      representations [see eellff__xxllaattee(3E)] and presents objects with memory
  39.      data types to the program, based on the file's ccllaassss [see eellff(3E)].
  40.      The working library version [see eellff__vveerrssiioonn(3E)] specifies what
  41.      version of the memory structures the program wants eellff__ggeettddaattaa to
  42.      present.
  43.  
  44.      eellff__nneewwddaattaa creates a new data descriptor for a section, appending it
  45.      to any data elements already associated with the section.  As the
  46.      following descriptions state, the new data descriptor appears empty,
  47.      indicating that the element holds no data.  For convenience, the
  48.      descriptor's type (dd__ttyyppee) is set to EELLFF__TT__BBYYTTEE, and the version
  49.      (dd__vveerrssiioonn) is set to the working version.  The program is responsible
  50.      for setting (or changing) the descriptor members as needed.  This
  51.      function implicitly sets the EELLFF__FF__DDIIRRTTYY bit for the section's data
  52.      [see eellff__ffllaagg(3E)].  If ssccnn is null or an error occurs, eellff__nneewwddaattaa
  53.      returns a null pointer.
  54.  
  55.      eellff__rraawwddaattaa differs from eellff__ggeettddaattaa by returning only uninterpreted
  56.      bytes, regardless of the section type.  This function typically should
  57.      be used only to retrieve a section image from a file being read, and
  58.      then only when a program must avoid the automatic data translation in
  59.      the following description.  Moreover, a program may not close or
  60.      disable [see eellff__ccnnttll(3E)] the file descriptor associated with eellff
  61.      before the initial raw operation, because eellff__rraawwddaattaa might read the
  62.      data from the file to ensure that it does not interfere with
  63.      eellff__ggeettddaattaa.  See eellff__rraawwffiillee(3E) for a related facility that applies
  64.      to the entire file.  When eellff__ggeettddaattaa provides the right translation,
  65.      its use is recommended over eellff__rraawwddaattaa.  If ssccnn is null or an error
  66.      occurs, eellff__rraawwddaattaa returns a null pointer.
  67.  
  68.      The EEllff__DDaattaa structure includes the following members:
  69.  
  70.      vvooiidd            **dd__bbuuff;;
  71.  
  72.      EEllff__TTyyppee        dd__ttyyppee;;
  73.  
  74.      ssiizzee__tt          dd__ssiizzee;;
  75.  
  76.      ooffff__tt           dd__ooffff;;
  77.  
  78.      ssiizzee__tt          dd__aalliiggnn;;
  79.  
  80.      uunnssiiggnneedd        dd__vveerrssiioonn;;
  81.  
  82.      These members are available for direct manipulation by the program.
  83.      The following are member descriptions:
  84.  
  85.      dd__bbuuff         Contains a pointer to the data buffer.  A data element
  86.                    with no data has a null pointer.
  87.  
  88.      dd__ttyyppee        This member's value specifies the type of the data to
  89.                    which dd__bbuuff points.  A section's type determines how to
  90.                    interpret the section contents.
  91.  
  92.      dd__ssiizzee        This member holds the total size, in bytes, of the
  93.                    memory occupied by the data.  This may differ from the
  94.                    size as represented in the file.  The size will be zero
  95.                    if no data exist.  [See the discussion of SSHHTT__NNOOBBIITTSS
  96.                    below for more information.]
  97.  
  98.      dd__ooffff         This member gives the offset, within the section, at
  99.                    which the buffer resides.  This offset is relative to
  100.                    the file's section, not the memory object's section.
  101.  
  102.      dd__aalliiggnn       This member holds the buffer's required alignment, from
  103.                    the beginning of the section.  That is, dd__ooffff will be a
  104.                    multiple of this member's value.  For example, if this
  105.                    member's value is four, the beginning of the buffer will
  106.                    be four-byte aligned within the section.  Moreover, the
  107.                    entire section will be aligned to the maximum of its
  108.                    constituents, thus ensuring appropriate alignment for a
  109.                    buffer within the section and within the file.
  110.  
  111.      dd__vveerrssiioonn     This member holds the version number of the objects in
  112.                    the buffer.  When the library originally read the data
  113.                    from the object file, it used the working version to
  114.                    control the translation to memory objects.
  115.  
  116. DDAATTAA AALLIIGGNNMMEENNTT
  117.      As mentioned above, data buffers within a section have explicit
  118.      alignment constraints.  Consequently, adjacent buffers sometimes will
  119.      not abut, causing _h_o_l_e_s within a section.  Programs that create output
  120.      files have two ways of dealing with these holes.
  121.  
  122.      First, the program can use eellff__ffiillll to tell the library how to set the
  123.      intervening bytes.  When the library must generate gaps in the file,
  124.      it uses the fill byte to initialize the data.  The library's initial
  125.      fill value is zero, and eellff__ffiillll lets the application change that
  126.      value.
  127.  
  128.      Second, the application can generate its own data buffers to occupy
  129.      the gaps, filling the gaps with values appropriate for the section
  130.      being created.  A program might even use different fill values for
  131.      different sections.  For example, it could set text sections' bytes to
  132.      no-operation instructions, while filling data section holes with zero.
  133.      Using this technique, the library finds no holes to fill, because the
  134.      application eliminated them.
  135.  
  136. SSeeccttiioonn aanndd MMeemmoorryy TTyyppeess
  137.      eellff__ggeettddaattaa interprets sections' data according to the section type,
  138.      as noted in the section header available through eellff__ggeettsshhddrr.  The
  139.      following table shows the section types and how the library represents
  140.      them with memory data types for the 32-bit file class.  Other classes
  141.      would have similar tables.  By implication, the memory data types
  142.      control translation by eellff__xxllaattee.
  143.  
  144.  --------------------------------------------------------------------------
  145.       Section Type               Elf_Type                32-Bit Type
  146.  --------------------------------------------------------------------------
  147.  SHT_DYNAMIC              ELF_T_DYN                 Elf32_Dyn
  148.  SHT_DYNSYM               ELF_T_SYM                 Elf32_Sym
  149.  SHT_HASH                 ELF_T_WORD                Elf32_Word
  150.  SHT_NOBITS               ELF_T_BYTE                unsigned char
  151.  SHT_NOTE                 ELF_T_BYTE                unsigned char
  152.  SHT_NULL                 nnoonnee                      nnoonnee
  153.  SHT_PROGBITS             ELF_T_BYTE                unsigned char
  154.  SHT_REL                  ELF_T_REL                 Elf32_Rel
  155.  SHT_RELA                 ELF_T_RELA                Elf32_Rela
  156.  SHT_STRTAB               ELF_T_BYTE                unsigned char
  157.  SHT_SYMTAB               ELF_T_SYM                 Elf32_Sym
  158.  ootthheerr                    ELF_T_BYTE                unsigned char
  159.  --------------------------------------------------------------------------
  160.  
  161.      eellff__rraawwddaattaa creates a buffer with type EELLFF__TT__BBYYTTEE.
  162.  
  163.      As previously mentioned, the program's working version controls what
  164.      structures the library creates for the application.  The library
  165.      similarly interprets section types according to the versions.  If a
  166.      section type belongs to a version newer than the application's working
  167.      version, the library does not translate the section data.  Because the
  168.      application cannot know the data format in this case, the library
  169.      presents an untranslated buffer of type EELLFF__TT__BBYYTTEE, just as it would
  170.      for an unrecognized section type.
  171.  
  172.      A section with a special type, SSHHTT__NNOOBBIITTSS, occupies no space in an
  173.      object file, even when the section header indicates a non-zero size.
  174.      eellff__ggeettddaattaa and eellff__rraawwddaattaa work on such a section, setting the ddaattaa
  175.      structure to have a null buffer pointer and the type previously
  176.      indicated.  Although no data are present, the dd__ssiizzee value is set to
  177.      the size from the section header.  When a program is creating a new
  178.      section of type SSHHTT__NNOOBBIITTSS, it should use eellff__nneewwddaattaa to add data
  179.      buffers to the section.  These empty data buffers should have the
  180.      dd__ssiizzee members set to the desired size and the dd__bbuuff members set to
  181.      null.
  182.  
  183. NNOOTTEESS
  184.      The 64-bit class functions work identically, simply replacing all
  185.      instances of 32 in the descriptions with 64.
  186.  
  187. EEXXAAMMPPLLEESS
  188.      The following fragment obtains the string table that holds section
  189.      names (ignoring error checking).  See eellff__ssttrrppttrr(3E) for a variation
  190.      of string table handling.
  191.  
  192.           ehdr = elf32_getehdr(elf);
  193.           scn = elf_getscn(elf, (size_t)ehdr->e_shstrndx);
  194.           shdr = elf32_getshdr(scn);
  195.           if (shdr->sh_type != SHT_STRTAB)
  196.           {
  197.                /* not a string table */
  198.           }
  199.           data = 0;
  200.           if ((data = elf_getdata(scn, data)) == 0 || data->d_size == 0)
  201.           {
  202.                /* error or no data */
  203.           }
  204.  
  205.      The ee__sshhssttrrnnddxx member in an ELF header holds the section table index
  206.      of the string table.  The program gets a section descriptor for that
  207.      section, verifies it is a string table, and then retrieves the data.
  208.      When this fragment finishes, ddaattaa-->>dd__bbuuff points at the first byte of
  209.      the string table, and ddaattaa-->>dd__ssiizzee holds the string table's size in
  210.      bytes.
  211.  
  212. SSEEEE AALLSSOO
  213.      eellff(3E), eellff__ccnnttll(3E), eellff__ffiillll(3E), eellff__ffllaagg(3E), eellff__ggeetteehhddrr(3E),
  214.      eellff__ggeettssccnn(3E), eellff__ggeettsshhddrr(3E), eellff__rraawwffiillee(3E), eellff__vveerrssiioonn(3E),
  215.      eellff__xxllaattee(3E)
  216.  
  217.      This man page is available only online.
  218.  
  219.