ELF_GETDATA man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

ELF_GETDATA(3ELF)					     ELF_GETDATA(3ELF)

NAME
       elf_getdata, elf_newdata, elf_rawdata - get section data

SYNOPSIS
       cc [ flag ... ] file ... -lelf [ library ... ]
       #include <libelf.h>

       Elf_Data *elf_getdata(Elf_Scn *scn, Elf_Data *data);

       Elf_Data *elf_newdata(Elf_Scn *scn);

       Elf_Data *elf_rawdata(Elf_Scn *scn, Elf_Data *data);

DESCRIPTION
       These  functions	 access and manipulate the data associated with a sec‐
       tion descriptor, scn. 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.

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

       The  elf_getdata()  function  translates the data from file representa‐
       tions  into  memory  representations  (see  elf32_xlatetof(3ELF))   and
       presents	 objects  with	memory data types to the program, based on the
       file's class (see elf(3ELF)). The working library version (see elf_ver‐
       sion(3ELF)) specifies what version of the memory structures the program
       wishes elf_getdata() to present.

       The elf_newdata() function 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
       (d_type below) is set to ELF_T_BYTE, and the version (d_version	below)
       is  set	to the working version. The program is responsible for setting
       (or changing) the descriptor members as needed. This  function  implic‐
       itly  sets  the	ELF_F_DIRTY  bit for the section's data (see elf_flag‐
       data(3ELF)). If
	scn is null or an error occurs, elf_newdata() returns a null pointer.

       The elf_rawdata() function differs from elf_getdata() by returning only
       uninterpreted bytes, regardless of the section type. This function typ‐
       ically 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  dis‐
       able  (see  elf_cntl(3ELF))  the	 file  descriptor  associated with elf
       before the initial raw operation, because elf_rawdata() might read  the
       data  from  the file to ensure it doesn't interfere with elf_getdata().
       See elf_rawfile(3ELF) for a related facility that applies to the entire
       file.   When  elf_getdata()  provides the right translation, its use is
       recommended over elf_rawdata(). If scn is  null	or  an	error  occurs,
       elf_rawdata() returns a null pointer.

       The Elf_Data structure includes the following members:

	 void	     *d_buf;
	 Elf_Type    d_type;
	 size_t	     d_size;
	 off_t	     d_off;
	 size_t	     d_align;
	 unsigned    d_version;

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

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

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

       d_size
		    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 SHT_NOBITS  below  for  more
		    information.)

       d_off
		    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.

       d_align
		    This  member  holds	 the buffer's required alignment, from
		    the beginning of the section. That is,  d_off  will	 be  a
		    multiple of this member's value. For example, if this mem‐
		    ber's value is 4, 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  con‐
		    stituents,	thus ensuring appropriate alignment for a buf‐
		    fer within the section and within the file.

       d_version
		    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.

   Data Alignment
       As  mentioned above, data buffers within a section have explicit align‐
       ment 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.

       First, the program can use elf_fill() 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  ini‐
       tial fill value is 0, and elf_fill() 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-opera‐
       tion  instructions,  while  filling data section holes with zero. Using
       this technique, the library finds no holes to fill, because the	appli‐
       cation eliminated them.

   Section and Memory Types
       The  elf_getdata()  function interprets sections' data according to the
       section	type,  as  noted  in  the  section  header  available  through
       elf32_getshdr().	 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 elf32_xlatetof(3ELF)

	 Section Type	     Elf_Type	      32-bit Type
       SHT_DYNAMIC	   ELF_T_DYN	   Elf32_Dyn
       SHT_DYNSYM	   ELF_T_SYM	   Elf32_Sym
       SHT_FINI_ARRAY	   ELF_T_ADDR	   Elf32_Addr
       SHT_GROUP	   ELF_T_WORD	   Elf32_Word
       SHT_HASH		   ELF_T_WORD	   Elf32_Word
       SHT_INIT_ARRAY	   ELF_T_ADDR	   Elf32_Addr
       SHT_NOBITS	   ELF_T_BYTE	   unsigned char
       SHT_NOTE		   ELF_T_NOTE	   unsigned char
       SHT_NULL		   none		   none
       SHT_PREINIT_ARRAY   ELF_T_ADDR	   Elf32_Addr
       SHT_PROGBITS	   ELF_T_BYTE	   unsigned char
       SHT_REL		   ELF_T_REL	   Elf32_Rel
       SHT_RELA		   ELF_T_RELA	   Elf32_Rela
       SHT_STRTAB	   ELF_T_BYTE	   unsigned char
       SHT_SYMTAB	   ELF_T_SYM	   Elf32_Sym
       SHT_SUNW_comdat	   ELF_T_BYTE	   unsigned char
       SHT_SUNW_move	   ELF_T_MOVE	   Elf32_Move (sparc)
       SHT_SUNW_move	   ELF_T_MOVEP	   Elf32_Move (ia32)
       SHT_SUNW_syminfo	   ELF_T_SYMINFO   Elf32_Syminfo
       SHT_SUNW_verdef	   ELF_T_VDEF	   Elf32_Verdef
       SHT_SUNW_verneed	   ELF_T_VNEED	   Elf32_Verneed
       SHT_SUNW_versym	   ELF_T_HALF	   Elf32_Versym
       other		   ELF_T_BYTE	   unsigned char

       The elf_rawdata() function creates a buffer with type ELF_T_BYTE.

       As mentioned above, the program's working version controls what	struc‐
       tures  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 ELF_T_BYTE, just as it would for an	unrec‐
       ognized section type.

       A  section  with	 a  special  type, SHT_NOBITS, occupies no space in an
       object file, even when the section header indicates  a  non-zero	 size.
       elf_getdata()  and  elf_rawdata()  work	on such a section, setting the
       data structure to have a null buffer pointer  and  the  type  indicated
       above.  Although	 no  data  are present, the d_size value is set to the
       size from the section header. When a program is creating a new  section
       of  type SHT_NOBITS, it should use elf_newdata() to add data buffers to
       the section. These empty data buffers should have  the  d_size  members
       set to the desired size and the d_buf members set to  NULL.

EXAMPLES
       Example 1 A sample program of calling elf_getdata().

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

	 ehdr = elf32_getehdr(elf);
	 scn = elf_getscn(elf, (size_t)ehdr->e_shstrndx);
	 shdr = elf32_getshdr(scn);
	 if (shdr->sh_type != SHT_STRTAB)
	 {
	 /* not a string table */
	 }
	 data = 0;
	 if ((data = elf_getdata(scn, data)) == 0 || data->d_size == 0)
	 {
	 /* error or no data */
	 }

       The e_shstrndx member in an ELF header holds the section table index of
       the string table. The program gets a section descriptor for  that  sec‐
       tion,  verifies it is a string table, and then retrieves the data. When
       this fragment finishes, data->d_buf points at the  first	 byte  of  the
       string table, and data->d_size holds the string table's size in bytes.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Stable	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ MT-Safe	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       elf(3ELF),    elf32_getehdr(3ELF),    elf64_getehdr(3ELF),   elf32_get‐
       shdr(3ELF),	   elf64_getshdr(3ELF),		 elf32_xlatetof(3ELF),
       elf64_xlatetof(3ELF),	elf_cntl(3ELF),	   elf_fill(3ELF),   elf_flag‐
       data(3ELF),  elf_getscn(3ELF),	elf_rawfile(3ELF),   elf_strptr(3ELF),
       elf_version(3ELF), libelf(3LIB), attributes(5)

				 Jul 11, 2001		     ELF_GETDATA(3ELF)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net