elf_newdata man page on Solaris

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

elf_getdata(3ELF)	     ELF Library Functions	     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 ele‐
		       ment 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 mem‐
		       ory 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
		       member'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
		       constituents, thus ensuring appropriate alignment for a
		       buffer 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)

SunOS 5.10			  11 Jul 2001		     elf_getdata(3ELF)
[top]

List of man pages available for Solaris

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