*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> elspec (5)              


ELSPEC(5)							     ELSPEC(5)

NAME    [Toc]    [Back]

     ELSPEC - ELF Layout specification

TOPIC    [Toc]    [Back]

     This manpage describes the	ELF Layout Specification language implemented
     by	ld(1) which allows users to exactly specify layout of object files,
     programs, and shared objects.

INTRODUCTION    [Toc]    [Back]

     It	is often desirable to specify the exact	layout of an executable	file.
     Some of the uses of this might be embedded	systems, thread-local data
     layout, reducing cache conflicts, reducing	false sharing, reducing	memory
     utilization.  The current linker allows exact specification of layout via
     the ELF Layout Specification language.

   Invoking Layout Specification    [Toc]    [Back]
     An	elspec file is specified to the	linker using

	  cc -Wl,-elspec,<filename> ...
	  ld -elspec <filename>	...

     You may get a sample elspec file for the default link using:

	  cc -Wl,-elsmap ...
	  ld -elsmap ...

   Basic Building Blocks    [Toc]    [Back]
     The basic units that the linker manipulates are called input sections.
     Each object file may have several of these, with familiar names such as
     `.text', `.data', `.bss', and so on.  The correctness of compiled code
     may depend	on the exact layout of a section, but never depends on the
     relative layout between sections.	For that reason, the linker will never
     rearrange or change the contents of any individual	input section in any

     The one exception to this are COMMON variables, for which space is
     allocated by the linker, and as such, are not allocated to	any input
     section. These can	be manipulated freely, but not split into pieces by
     ELF Layout	Specification.	You get	a COMMON variable by using a FORTRAN
     COMMON, or	from C data variables declared at file scope in	files which
     have been compiled	with either -cckr or -common.

   Segments    [Toc]    [Back]
     Input sections are	linked together	more or	less contiguously into output
     sections.	Output sections	are organized in and ELF file into loadable
     segments which are	specified in the program header. See elf(5). Segments

									Page 1

ELSPEC(5)							     ELSPEC(5)

     represent a contiguous portion of the file	which is to be loaded into
     memory as-is, with	possibly the addition of extra memory at the end.

   Placement Rules    [Toc]    [Back]
     ELF Layout	Specification works by allowing	the user to specify the
     placement of input	sections within	output sections, and the output
     sections within segments.	In order to avoid requiring the	user to
     specify every input file, we give rules for the default placement of an
     input section in an output	section	and the	placement of output sections
     within segments.

     A section from an input file will be placed in the	output file according
     to	these rules:

     1.	If the section (and object and archive)	are mentioned explicitly,
	place it there.

     2.	If there is a section specified	in the map with	the same name,
	which has "default" as one of its contents, and	which has matching
	attributes, place it there. The	input section will maintain
	its layout position relative to	other listed contents.	If there
	is more	than one default-placed	input section, they will be
	allocated space	in the order encountered.  If the attributes of	the
	input section do not match those specified in the map, it is an	error.

     3.	If there is a segment specified	in the map with	matching attributes
	which has specified "default" as one of	its contents,
	the input section will be placed in an output section with the same
	name and attributes. The input section will maintain
	its layout position relative to	other listed contents.	If there
	is more	than one default-placed	input section, they will be
	allocated space	in the order encountered.  If the attributes of	the
	input section do not match those specified in the map or those of
	another	default	input section, it is an	error.

     4.	If an input object is listed as	a segment content
	without	mention	of specific input sections, all	sections with
	appropriate attributes are merged by name and laid out in the order

     5.	File layout will be managed by the linker in any fashion it sees
	fit. We	can provide a flag -ignorevce to allow tighter packing.

     6.	Specifying "headers" as	contents of a segment allows (but does not
	require) the inclusion of headers such as the ELF header and the
	program	header into that segment.  Specifying "default"	has this
	effect as well.	 Specifying "noheaders"	will forbid the	inclusion
	of headers into	that segment

     7.	Loader-generated sections will be placed in to a segment with matching
	attributes which has specified "ldgen" as its segment contents.

									Page 2

ELSPEC(5)							     ELSPEC(5)

	Specific loader-generated sections may be placed by using $ldobj as
	the object name.  When a non-optional loader-generated section has
	no place to be loaded, an error	is generated, unless the global	switch
       "$ignoreldgen" has the value "true".

     8.	Should user-specified alignment	result in R4000	alignment problems,
	ld will	report these to	the user, and produce output anyway.  If
	"$r4kbugfix" is	set to false (or -allow_jump_at_eop specfied on	the
	linkline), no checking will be performed.

     9.	In general, command line options take precedence over
	specifications here.

     10.Overlaps in virtual space or physical space will be reported
	unless at least	one of the segment descriptions	has specified an
	overlap	with the other,	or unless "$ignoreoverlaps" is true.

     11.The name, type,	and flags of an	output section uniquely	determines
	that section. Specifying more than one such section in the file
	will yield unpredictable results.

     12.Sections with flags SHF_ALLOC and SHF_READ but not SHF_WRITE, will be
	placed in the first segment which has PF_R but not PF_W	set.

SYNTAX    [Toc]    [Back]

     This section describes the	actual syntax of an ELSPEC file.  There	are
     some examples at the end.

   Overview    [Toc]    [Back]
     There are three main parts	to the layout specification (lspec) file.  In
     order expected, they are: a list of global	variable settings, a list of
     symbols attribute specifications, and a list of segment specifications.

	       <layoutspec> ::=	<globals> <symlist> <seglist>;

   Segments    [Toc]    [Back]
     Segments are the basic runtime building blocks.  They are necessarily
     contiguous, both in memory	and in the file.  They have a uniform set of
     protections associated.

	       <segdef>	::= beginseg <segname> <segattr>
			       <segspecial> contents <segcontents> endseg;

	       <segname> ::= /*	empty */ | name	<idstring>;

	       <segattr> ::= /*	empty */
			 | <segattr> segtype <segtype>
			 | <segattr> vaddr <address>
			 | <segattr> paddr <address>
			 | <segattr> segflags <segflags>

									Page 3

ELSPEC(5)							     ELSPEC(5)

			| <segattr> segalign <number>

	       <segtype> ::= noload /* include in output segment */
			  | <number>
			  | LOAD /* this is the	default	*/
		       | REL

	       <segflags> ::= /* empty,	default	settings are RWX */
			 | <segflags> R	/* Set the PF_R	flag */
		      |	<segflags> W /*	Set the	PF_W flag */
		      |	<segflags> X /*	Set the	PF_X flag */
		      |	<segflags> L;/*	Set the	PF_MIPS_LOCAL flag */

     For programs under	the IRIX 5.3 and above,	segments with the
     PF_MIPS_LOCAL flag	set will be thread-local and not shared	in the event
     of	an sproc(2) system call.  For other applications, the meaning of this
     bit is undefined.

   Segment contents    [Toc]    [Back]
     Contents of a segment are usually in the form of output sections.	These
     section are further specified to contain input sections (see below), and
     are laid out in the order specified.  The default is to build upwards in
     virtual address space.

     Specifying	"default" as segment contents allows the linker	to place input
     sections with compatible attributes which are not otherwise mentioned in
     the current segment.  This	is accomplished	by creating a distinct output
     sections for each unique set of section type, flags, and section name,
     and placing it in the "best" segment which	has specified "default"	as one
     of	its segment contents.

	       <segcontents> ::= /* empty */
			 | <segcontents> <outsection>
			 | <segcontents> noheaders
			 | <segcontents> default;

   Output sections    [Toc]    [Back]
     Output sections are a convenient way to group material within a segment.
     For example, we may wish to have read-only	data and program text in the
     same segment, but within that segment we want to have all the read-only
     data together and all the text together.  We define two output sections
     named ".rdata" and	".text"	and place them both within a single segment.

	       <outsection> ::=	beginscn <idstring> <scnattr> <scnspecial>
			 <scncontents> endscn
		    | beginscn <idstring> relfor <idstring> endscn
		    | beginscn <idstring> relafor <idstring> endscn

									Page 4

ELSPEC(5)							     ELSPEC(5)

	      <scnattr>	::= /* empty string */
		    | <scnattr>	scntype	<scntype>
		    | <scnattr>	scnflags <scnflags>
		    | <scnattr>	scnsize	<size>
		    | <scnattr>	link <number>
		    | <scnattr>	info <number
		    | <scnattr>	scnalign <number>
		    | <scnattr>	entsize	<number>

	       <scntype> ::= PROGBITS |	NOTE | NOBITS |	<number>;

	       <scnflags> ::= <scnflaglist> | <number> | none;

	       <scnflaglist> ::= /* empty */
		    | <scngflaglist> WRITE
		    | <scnflaglist> ALLOC
		    | <scnflaglist> EXECINSTR
		    | <scnflaglist> GPREL
		    | <scnflaglist> MERGE
		    | <scnflaglist> ADDR
		    | <scnflaglist> NOSTRIP
		    | <scnflaglist> LOCAL;

     Layout specification for relocatable ("-r") links is supported.  Unlike
     other types of output sections, the contents of relocation	sections
     cannot be freely specified.  Rather, the contents of a given "relfor"
     section are determined relative to	some other output section.  For
     example, the section specified by
	       beginscn	.rel.mytext relfor .mytext endscn
     contains all the Rel-type relocations for the output section named
     ".mytext".	 Relocation sections can be given any name, but	the relocation
     must be preceded by the section the relocations are relative to.

   Input sections    [Toc]    [Back]
     Input sections are	the basic building blocks which	the linker
     manipulates.  Each	object file read by the	linker may contain several of
     these input section.  The lspec file works	by specifying the arrangement
     of	these input sections.  Input sections may be specified in two basic
     ways.  The	user may attempt to specify the	section	directly, or may
     specify an	external symbol	name, which has	the effect of specifying the
     section in	which that symbol definition resides.

	       <scncontents> ::= /* Nothing */
			 | <scncontents> default
			 | <scncontents> <inputscn>
			 | <scncontents> <symspec>;

     In	the rule below,	the <idstring> specifies the name of the input
     section. If no name is specified, all sections from the mentioned object
     with matching attributes are selected.

									Page 5

ELSPEC(5)							     ELSPEC(5)

     Sometimes it may occur that the attributes	of an input section are	not
     compatible	with those of the enclosing output section.  Below you see
     different input section specifications categorized	as either specific or
     generic.  If a specific mention conflicts with default output section
     attributes, the output section attributes are promoted to be compatible.
     If	a specific mention conflicts with user-specified output	section
     attributes, the input section is included with a warning, but the output
     section attributes	are not	altered.  If a generic mention conflicts with
     output section attributes,	the input section is not included in the
     output section, regardless	of whether the output sections attributes were
     user-specified or not.

	       <inputscn> ::= sec <idstring> /*	specific mention */
			      |	sec <idstring> in <object> /* specific mention */
			      |	<object>; /* generic mention */

	       <object>	::= obj[ect] <idstring>	( <idstring> )
		       /* archive(filename) */
			  | obj[ect] <idstring>
			  | ar[chive] <idstring>
			  | ldobj;
		       /* for specifying loader-defined	sections */

	       <symspec> ::=  sym <idstring> in	<inputscn>
			    | sym <idstring>;

   ELSpec Variables    [Toc]    [Back]
     Various ELF layout	Specification (ELSpec) variables can be	given values.
     These values will be used by the linker when laying out your program.

	       <globals> ::= /*	NULL */	| globals set_global;

	       <set_global ::= <gsize> = <size>
			 | <gbool> = <boolean>;

	       <gsize> ::=    $blocksize
			 | $cachesize
			 | $pagesize
			 | $cachelinesize;

	       <gbool> ::=    $ignoreldgen
			 | $r4kbugfix
			 | $ignoreoverlaps;

   Segment Special attributes    [Toc]    [Back]
     These allow users to specify special attributes of	a segment.

     Specifying	"ascending" means that the components will be laid out in
     order of increasing address, beginning at the specified (or default)
     address. This is the default behavior.

									Page 6

ELSPEC(5)							     ELSPEC(5)

     Specifying	"overlap <idstring>" denotes that the normal linker checking
     for overlaps in virtual address are not to	be performed between the
     current segment and the segment named by <idstring>.  This	is to
     facilitate	overlay	links.

	       <segspecial> ::=	/* empty */
			 | <segspecial>	ascending
			 | <segspecial>	overlap	<idstring>;

   Base	Data Types
     Here is the syntax	for numbers, booleans, strings and so on.
	       <size> ::= <number> | <number> K	| <number> M
	       <address> ::= <number>
	       <number>	::=   0x[0-9a-f]+ /* Hex number	*/
			 | 0[0-7]+ /* Octal number */
			 | [0-9]+  /* decimal number */

	       <boolean> ::= true | false;
	       <idstring> ::= [a-zA-Z0-9$_.]+
			 | "<any string>";

   Comments    [Toc]    [Back]
     If	the character '#' appears in a layout specification (except when with
     in	a string specified with	""), the remainder of the line,	including the
     '#' will be treated as a comment and ignored.

EXAMPLES    [Toc]    [Back]

   Default link	spec
	  #  This is the default link spec.  Using it should give the
	  #  same result as not	using -elspec

	       name text
	       segtype LOAD
	       vaddr 0x10000000
	       segflags	R X
	       segalign	0x10000

	       contents	default
	       name data
	       segtype LOAD
	       segflags	R W X
	       segalign	0x1000

	       contents	default

									Page 7

ELSPEC(5)							     ELSPEC(5)

	      name noload
	       segtype noload

	       contents	default

   Aligning a COMMON symbol    [Toc]    [Back]
	  # This link spec will	give the COMMON	symbol a_ an alignment of 128
	  # bytes.  This can be	useful to prevent false	sharing, among other
	  # things.

	      segtype LOAD
	      segflags R X
	  #   vaddr 0x10000000
	      segalign 0x1000
	      contents default

	      segtype LOAD
	      segflags R W
	  #   vaddr 0x10011000
	      segalign 0x1000
	      contents default
	      beginscn .mybss
		  scntype NOBITS
		  scnflags ALLOC WRITE
		  scnalign 0x80
		  sym a_

SEE ALSO    [Toc]    [Back]

     ld(1), elf(5), elfdump(5)

UPDATES    [Toc]    [Back]

     This manpage is updated periodically, the last update was on 3/1/95 for
     IRIX 6.0.2

									PPPPaaaaggggeeee 8888
[ Back ]
 Similar pages
Name OS Title
xfs IRIX layout of the XFS filesystem
hier OpenBSD layout of filesystems
hier FreeBSD layout of file systems
glcgetmaxcharmetric IRIX measure layout of characters
efs IRIX layout of the Extent File System
ipkbd IRIX changes a user's keyboard layout setting.
vxrelayout HP-UX convert online storage from one layout to another
ConvertLayout IRIX convert old desktop layout files to new format
vxupgrade HP-UX upgrade the disk layout of a VxFS file system
flushCache IRIX remove all desktop type or layout cache entries
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service