ELF vs. a.out, libc 5vs 6

Three years ago when this document was first created, I openedthis section by saying "Linux development is in a state of fluxright now" and going on to describe how ELF was replacing the oldera.out binary format.

It still is in a state of flux. It always will be. Though thatparticular change is long since past, development of the Linuxkernel and the surrounding system continues to happen, and thingschange for developers as a result. So it's a good idea to knowupfront what kind of system you have in front of you.

The possible candidates, in order of age, are

• libc 4, a.out: very old systems

• libc 5, ELF: Red Hat 4.2, Debian 2.0

• libc 6 (a.k.a glibc 2), ELF: Red Hat 5 - 5.2, Debian 2.1

• libc 6.1,(a.k.a glibc 2.1) ELF: Red Hat 6

$ ldd /bin/ls
        libc.so.6 => /lib/libc.so.6 (0x4000e000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

This document was created on a Debian 2.1 system, so no surprise there.

It's entirely possible that the system you're using may have amix of different versions on it. What you probably want to know inthat case is the version that its C development environment is setup for, so you're best off compiling "hello world" and runningldd on the output thus created. Note thatfor historical reasons, gcc defaults to anoutput file calleda.outeven on ELFsystems, so don't assume anything from that.

Administrata

The copyright information and like legalese can be found at theend of this document, together with thestatutory warnings about asking dumb questions on Usenet, revealingyour ignorance of the C language by reporting bugs which aren't,and picking your nose while chewing gum.

Typography

If you're reading this in Postscipt, dvi, or html format, youget to see a little more font variation than people with the plaintext version. In particular, filenames, commands, command outputand source code excerpts are set in some form oftypewriterfont, whereas `variables' and randomthings that need emphasizing are emphasized.

You also get a usable index. In dvi or postscript, the numbersin the index are section numbers. In HTML they're just sequentiallyassigned numbers that you can click on. In the plain text version,they really are just numbers. Get an upgrade!

The Bourne (rather than C) shell syntax is used in examples. Cshell users will want to use

% setenv FOO bar

 
$ FOO=bar; export FOO

If the prompt shown is#rather than$, the command shown will probably onlywork as root. Of course, I accept no responsibility for anythingthat happens to your system as a result of trying these examples.Have a nice day:-)

This document

You're reading it. You probably have it already.

This document is one of the Linux HOWTO series, so is probablyalready installed somewhere in/usr/docif you're reading this on a linux box. Failing that, from all LinuxHOWTO repositories (try Metalab) and (possibly in a slightly newerversion) at my personal web site www.telent.net.

Otherdocumentation

The official documentation for gcc is in the source distribution(see below) as texinfo files, and as.infofiles. If you have a fast network connection, a cdrom, or areasonable amount of patience, you can just untar it and copy therelevant bits into/usr/info. If not, youmay find them at tsx-11, but not necessarily always the latestversion.

There are two source of documentation for libc. GNU libc comeswith info files which describe Linux libc fairly accurately exceptfor stdio. Also, the manpagesarchive are written for Linux and describe a lot of system calls(section 2) and libc functions (section 3).

GCC

There are two answers.

(a) The official Linux GCC distribution can always be found inbinary (ready-compiled) form at .At the time of writing, 2.7.2 (gcc-2.7.2.bin.tar.gz) is the latest version.

(b) The latest source distribution of GCC from the Free SoftwareFoundation can be had from GNU archives. This is not necessarily always thesame version as above, though it is just now. The Linux GCCmaintainer(s) have made it easy for you to compile the latestversion available yourself --- theconfigurescript should set it all up for you. Checktsx-11 as well, for patches which you may want toapply.

To compile anything non-trivial (and quite a few trivial thingsalso) you will also need the

C library andheader files

What you want here depends on (i) whether your system is ELF ora.out, and (ii) which you want it to be. If you're upgrading fromlibc 4 to libc 5, you are recommended to look at the ELF-HOWTO fromapproximately the same place as you found this document.

These are available from tsx-11 as above:

Associated tools(as, ld, ar, strings etc)

From tsx-11, just like everything else so far. Thecurrent version isbinutils-2.6.0.2.bin.tar.gz.

Note that the binutils are only available in ELF, the currentlibc version is in ELF and the a.out libc is happiest when used inconjunction with an ELF libc. C library development is movingemphatically ELFwards, and unless you have really good reasons forneeding a.out things you're encouraged to follow suit.

GCCversions

You can find out what GCC version you're running by typinggcc -vat the shell prompt. This is also afairly reliable way to find out whether you are set up for ELF ora.out. On my system it does

$ gcc -v
Reading specs from /usr/lib/gcc-lib/i486-box-linux/2.7.2/specs
gcc version 2.7.2

The key things to note here are

• i486. This indicates that the gcc youare using was built for a 486 processor --- you might have 386 or586 instead. All of these chips can run code compiled for each ofthe others; the difference is that the 486 code has added paddingin some places so runs faster on a 486. This has no detrimentalperformance effect on a 386, but does make the binaries slightlylarger.

• box. This is not at all important, and may say something else(such asslackwareordebian) or nothing at all (so that the completedirectory name isi486-linux). If youbuild your own gcc, you can set this at build time for cosmeticeffect. Just like I did:-)

• linux. This may instead saylinuxelforlinuxaout, and,confusingly, the meaning of each varies according to the versionthat you are using.

  • linuxmeans ELF if the version is 2.7.0or newer, a.out otherwise.

  • linuxaoutmeans a.out. It wasintroduced as a target when the definition oflinuxwas changed from a.out to ELF, so you won'tsee anylinuxaoutgcc older than2.7.0.

  • linuxelfis obsolete. It is generally aversion of gcc 2.6.3 set to produce ELF executables. Note that gcc2.6.3 has known bugs when producing code for ELF --- an upgrade isadvisable.

• 2.7.2is the version number.

So, in summary, I have gcc 2.7.2 producing ELF code. Quellesurprise.

Where did itgo?

If you installed gcc without watching, or if you got it as partof a distribution, you may like to find out where it lives in thefilesystem. The key bits are

• /usr/lib/gcc-lib/target/version/(andsubdirectories) is where most of the compiler lives. This includesthe executable programs that do actual compiling, and someversion-specific libraries and include files.

• /usr/bin/gccis the compiler driver ---the bit that you can actually run from the command line. This canbe used with multiple versions of gcc provided that you havemultiple compiler directories (as above) installed. To find out thedefault version it will use, typegcc -v.To force it to another version, typegcc-Vversion. For example

  # gcc -v Reading specs from /usr/lib/gcc-lib/i486-box-linux/2.7.2/specs gcc version 2.7.2 # gcc -V 2.6.3 -v Reading specs from /usr/lib/gcc-lib/i486-box-linux/2.6.3/specs gcc driver version 2.7.2 executing gcc version 2.6.3

• /usr/target/(bin|lib|include)/.If you have multiple targets installed (for example, a.out and elf,or a cross-compiler of some sort, the libraries, binutils(as,ldand soon) and header files for the non-native target(s) can be foundhere. Even if you only have one kind of gcc installed you mightfind anyway that various bits for it are kept here. If not, they'rein/usr/(bin|lib|include).

• /lib/,/usr/liband others are library directories for the native system. You willalso need/lib/cppfor many applications(X makes quite a lot of use of it) --- either copy it from/usr/lib/gcc-lib/target/version/or make a symlinkpointing there.

Where are theheader files?

Apart from whatever you install yourself under/usr/local/include, there are three main sources ofheader files in Linux:

• Most of/usr/include/and itssubdirectories are supplied with the libc binary package from H JLu. I say `most' because you may also have files from other sources(cursesanddbmlibraries, for example) in here, especially if you are using thenewest libc distribution (which doesn't come with curses or dbm,unlike the older ones).

• /usr/include/linuxand/usr/include/asm(for the files<linux #endif

  Use__linux__for this purpose,notlinux.Although the latter is defined, it is not POSIX compliant.

Compilerinvocation

The documentation for compiler switches is the gcc info page (inEmacs, useC-h ithen select the `gcc'option). Your distributor may not have packed this with yoursystem, or you may have an old version; the best thing to do inthis case is to download the gcc source archive from or one of itsmirrors, and copy them out of it.

The gcc manual page (gcc.1) is,generally speaking, out of date. It will warn you of this when youtry to look at it.

enabled: -fdefer-pop -fcse-follow-jumps -fcse-skip-blocks
-fexpensive-optimizations
         -fthread-jumps -fpeephole -fforce-mem -ffunction-cse -finline
         -fcaller-saves -fpcc-struct-return -frerun-cse-after-loop
         -fcommon -fgnu-linker -m80387 -mhard-float -mno-soft-float
         -mno-386 -m486 -mieee-fp -mfp-ret-in-387

Portability

It has been said that, these days, if something hasn't beenported to Linux then it is not worth having :-)

Seriously though, in general only minor changes are needed tothe sources to get over Linux's 100% POSIX compliance. It is alsoworthwhile passing back any changes to authors of the code suchthat in the future only `make' need be called to provide a workingexecutable.

#ifdef SIGSYS

#endif

      struct timeval timeout;
      timeout.tv_sec = 1; timeout.tv_usec = 0;
      while (some_condition)
            select(n,readfds,writefds,exceptfds,&timeout); 

      struct timeval timeout;
      while (some_condition) {
            timeout.tv_sec = 1; timeout.tv_usec = 0;
            select(n,readfds,writefds,exceptfds,&timeout);
      }

  signal (sig_nr, my_signal_handler);

  signal (sig_nr, my_signal_handler);
  { struct sigaction sa;
    sigaction (sig_nr, (struct sigaction *)0, &sa);
#ifdef SA_RESTART
    sa.sa_flags |= SA_RESTART;
#endif
#ifdef SA_INTERRUPT
    sa.sa_flags &= ~ SA_INTERRUPT;
#endif
    sigaction (sig_nr, &sa, (struct sigaction *)0);
  }

int result;
while (len > 0) { 
  result = read(fd,buffer,len);
  if (result < 0) break;
  buffer += result; len -= result;
}

int result;
while (len > 0) { 
  result = read(fd,buffer,len);
  if (result < 0) { if (errno != EINTR) break; }
  else { buffer += result; len -= result; }
}

int result;
result = ioctl(fd,cmd,addr);

int result;
do { result = ioctl(fd,cmd,addr); }
while ((result == -1) && (errno == EINTR));

execl("/bin/ls","ls",NULL);

execl("/bin/ls", NULL);

Preventativemaintenance (lint)

There is no widely-used lint for Linux, as most people aresatisfied with the warnings that gcc can generate. Probably themost useful is the-Wallswitch --- thisstands for `Warnings, all' but probably has more mnemonic value ifthought of as the thing you bang your head against.

There is a public domain lint available from . Idon't know how good it is.

Debugging

(gdb) list 
1       #include <stdio.h>
2
3       main()
4       {
5         if(fork()==0) printf("child\n");
6         else printf("parent\n");
7       }
(gdb) break fork
Breakpoint 1 at 0x80003b8
(gdb) run
Starting program: /home/dan/src/hello/./fork 
Breakpoint 1 at 0x400177c4

Breakpoint 1, 0x400177c4 in fork ()
(gdb) return 0
Make selected stack frame return now? (y or n) y
#0  0x80004a8 in main ()
    at fork.c:5
5         if(fork()==0) printf("child\n");
(gdb) next
Single stepping until exit from function fork, 
which has no line number information.
child
7       }

% limit core unlimited

$ ulimit -c unlimited

        memcpy(corefile,"core.",5);
#if 0
        memcpy(corefile+5,current->comm,sizeof(current->comm));
#else
        corefile[4] = '\0';
#endif

Profiling

Profiling is a way to examine which bits of a program are calledmost often or run for longest. It is a good way to optimize codeand look at where time is being wasted. You must compile all objectfiles that you require timing information for with-p, and to make sense of the output file you willalso needgprof(from the binutilspackage). See thegprofmanual page fordetails.

Shared vs staticlibraries

The last stage of building a program is to `link' it; to joinall the pieces of it together and see what is missing. Obviouslythere are some things that many programs will want to do --- openfiles, for example, and the pieces that do these things areprovided for you in the form of libraries. On the average Linuxsystem these can be found in/liband/usr/lib/, among other places.

When using a static library, the linker finds the bits that theprogram modules need, and physically copies them into theexecutable output file that it generates. For shared libraries, itdoesn't --- instead it leaves a note in the output saying `whenthis program is run, it will first have to load this library'.Obviously shared libraries tend to make for smaller executables;they also use less memory and mean that less disk space is used.The default behaviour of Linux is to link shared if it can find theshared libraries, static otherwise. If you're getting staticbinaries when you want shared, check that the shared library files(*.safor a.out,*.sofor ELF) are where they should be, and arereadable.

On Linux, static libraries have names likelibname.a, while shared libraries are calledlibname.so.x.y.zwherex.y.zis some form of version number. Sharedlibraries often also have links pointing to them, which areimportant, and (on a.out configurations) associated.safiles. The standard libraries come in bothshared and static formats.

You can find out what shared libraries a program requires byusingldd(List Dynamic Dependencies)

$ ldd /usr/bin/lynx
        libncurses.so.1 => /usr/lib/libncurses.so.1.9.6
        libc.so.5 => /lib/libc.so.5.2.18

This shows that on my system the WWW browser `lynx' depends onthe presence oflibc.so.5(the C library)andlibncurses.so.1(used for terminalcontrol). If a program has no dependencies,lddwill say `staticallylinked' or `statically linked(ELF)'.

Interrogatinglibraries (`which library issin()in?')

nmlibrarynameshould list all the symbols that libraryname has references to. It works on bothstatic and shared libraries. Suppose that you want to know wheretcgetattr()is defined: you might do

$ nm libncurses.so.1 |grep tcget
         U tcgetattr

TheUstands for `undefined' --- itshows that the ncurses library uses but does not define it. Youcould also do

$ nm libc.so.5 | grep tcget
00010fe8 T __tcgetattr
00010fe8 W tcgetattr
00068718 T tcgetpgrp

The `W' stands for `weak', which meansthat the symbol is defined, but in such a way that it can beoverridden by another definition in a different library. Astraightforward `normal' definition (such as the one fortcgetpgrp) is marked by a `T'

The short answer to the question in the title, by the way, islibm.(so|a). All the functions defined in<math.h>arekept in the maths library; thus you need to link with-lmwhen using any of them.

Findingfiles

ld: Output file requires shared library`libfoo.so.1`

The file search strategy of ld and friends varies according toversion, but the only default you can reasonably assume is/usr/lib. If you want libraries elsewhereto be searched, specify their directories with the-Loption to gcc or ld.

If that doesn't help, check that you have the right file in thatplace. For a.out, linking with-lfoomakesld look forlibfoo.sa(shared stubs), andif unsuccessful then forlibfoo.a(static). For ELF, it looks forlibfoo.sothenlibfoo.a.libfoo.sois usually a symbolic link tolibfoo.so.x.

Building your ownlibraries

$ gcc -fPIC -c *.c
$ gcc -shared -Wl,-soname,libfoo.so.1 -o libfoo.so.1.0 *.o
$ ln -s libfoo.so.1.0 libfoo.so.1
$ ln -s libfoo.so.1 libfoo.so
$ LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH ; export LD_LIBRARY_PATH

$ su
# cp libfoo.so.1.0 /usr/local/lib
# /sbin/ldconfig
# ( cd /usr/local/lib ; ln -s libfoo.so.1 libfoo.so )

gcc -shared -Wl,-soname,libfoo.so.major -o libfoo.so.major.minor

Concepts

Linux has shared libraries, as you will by now be sick ofhearing if you read the whole of the last section at a sitting.Some of the matching-names-to-places work which was traditionallydone at link time must be deferred to load time.

Errormessages

Send me your link errors! I won't do anything about them, but Imight write them up ...

Controlling theoperation of the dynamic loader

There are a range of environment variables that the dynamicloader will respond to. Most of these are more use tolddthan they are to the average user, and can mostconveniently be set by running ldd with various switches. Theyinclude

• LD_BIND_NOW--- normally, functions arenot `looked up' in libraries until they are called. Setting thisflag causes all the lookups to happen when the library is loaded,giving a slower startup time. It's useful when you want to test aprogram to make sure that everything is linked.

• LD_PRELOADcan be set to a filecontaining `overriding' function definitions. For example, if youwere testing memory allocation strategies, and wanted to replace`malloc', you could write your replacement routine, compile it intomalloc.oand then

  $ LD_PRELOAD=malloc.o; export LD_PRELOAD $ some_test_program

  LD_ELF_PRELOADandLD_AOUT_PRELOADare similar, but only apply to theappropriate type of binary. IfLD_something_PRELOADandLD_PRELOADareset, the more specific one is used.

• LD_LIBRARY_PATHis a colon-separatedlist of directories in which to look for shared libraries. It doesnot affect ld; it only has effect atruntime. Also, it is disabled for programs that run setuid orsetgid. Again,LD_ELF_LIBRARY_PATHandLD_AOUT_LIBRARY_PATHcan also be used todirect the search differently for different flavours of binary.LD_LIBRARY_PATHshouldn't be necessary innormal operation; add the directories to/etc/ld.so.conf/and rerun ldconfig instead.

• LD_NOWARNapplies to a.out only. Whenset (e.g. withLD_NOWARN=true; exportLD_NOWARN) it stops the loader from issuing non-fatal warnings(such as minor version incompatibility messages).

• LD_WARNapplies to ELF only. When set,it turns the usually fatal ``Can't find library'' messages intowarnings. It's not much use in normal operation, but important forldd.

• LD_TRACE_LOADED_OBJECTSapplies to ELFonly, and causes programs to think they're being run underldd:

  $ LD_TRACE_LOADED_OBJECTS=true /usr/bin/lynx libncurses.so.1 => /usr/lib/libncurses.so.1.9.6 libc.so.5 => /lib/libc.so.5.2.18

Writing programswith dynamic loading

This is very close to the way that Solaris 2.x dynamic loadingsupport works, if you're familiar with that. It is coveredextensively in H J Lu's ELF programming document, and thedlopen(3)manual page, which can be foundin the ld.so package. Here's a nice simple example though: link itwith-ldl

#include <dlfcn.h>
#include <stdio.h>

main()
{
  void *libc;
  void (*printf_call)();

  if(libc=dlopen("/lib/libc.so.5",RTLD_LAZY))
  {
    printf_call=dlsym(libc,"printf");
    (*printf_call)("hello, world\n");
  }

}

Bugreports

Start by narrowing the problem down. Isit specific to Linux, or does it happen with gcc on other systems?Is it specific to the kernel version? Library version? Does it goaway if you link static? Can you trim the program down to somethingshort that demonstrates the bug?

Having done that, you'll know what program(s) the bug is in. ForGCC, the bug reporting procedure is explained in the info file. Forld.so or the C or maths libraries, send mail tolinux-gcc@vger.rutgers.edu. If possible, include ashort and self-contained program that exhibits the bug, and adescription both of what you want it to do, and what it actuallydoes.

Helping withdevelopment

If you want to help with the development effort for GCC or the Clibrary, the first thing to do is join thelinux-gcc@vger.rutgers.edumailing list. If you justwant to see what the discussion is about, there are list archivesat .The second and subsequent things depend on what you want to do!

The Credits

" Only presidents, editors, and people withtapeworms have the right to use the editorial ``we''." (MarkTwain)

This HOWTO is based very closely on Mitchum DSouza's GCC-FAQ;most of the information (not to mention a reasonable amount of thetext) in it comes directly from that document. Instances of thefirst person pronoun in this HOWTO could refer to either of us;generally the ones that say ``I have not tested this; don't blameme if it toasts your hard disk/system/spouse'' apply to both ofus.

Contributors to this document have included (in ASCII orderingby first name) Andrew Tefft, Axel Boldt, Bill Metzenthen, BruceEvans, Bruno Haible, Daniel Barlow, Daniel Quinlan, David Engel,Dirk Hohndel, Eric Youngdale, Fergus Henderson, H.J. Lu, JensSchweikhardt, Kai Petzke, Michael Meissner, Mitchum DSouza, OlafFlebbe, Paul Gortmaker, Rik Faith, Steven S. Dick, Tuomas J Lukka,and of course Linus Torvalds, without whom the whole exercise wouldhave been pointless, let alone impossible :-)

Please do not feel offended if your name has not appeared hereand you have contributed to this document (either as HOWTO or asFAQ). Email me and I will rectify it.

Translations

• French, Eric Dumas

  <dumas@freenix.fr>

  http://www.freenix.fr/unix/linux/HOWTO/GCC-HOWTO.html

• Italian, Andrea Girotto

  <andrea.girotto@usa.net>

  http://www.pluto.linux.it/ildp/HOWTO/GCC-HOWTO.html

• Japanese,

  <nakano@apm.seikei.ac.jp>

Feedback

is welcomed. Mail me at daniel.barlow@linux.org. My PGP public key (ID5F263625) is available from my web pages, if you feel the need to be secretiveabout things.

Legalese

All trademarks used in this document are acknowledged as beingowned by their respective owners.

This document is copyright (C) 1996,1999 Daniel Barlow<dan@detached.demon.co.uk>.It may be reproduced and distributed in whole or in part, in anymedium physical or electronic, as long as this copyright notice isretained on all copies. Commercial redistribution is allowed andencouraged; however, the author would like to be notified of anysuch distributions.

All translations, derivative works, or aggregate worksincorporating any Linux HOWTO documents must be covered under thiscopyright notice. That is, you may not produce a derivative workfrom a HOWTO and impose additional restrictions on itsdistribution. Exceptions to these rules may be granted undercertain conditions; please contact the Linux HOWTO coordinator atthe address given below.

In short, we wish to promote dissemination of this informationthrough as many channels as possible. However, we do wish to retaincopyright on the HOWTO documents, and would like to be notified ofany plans to redistribute the HOWTOs.

If you have questions, please contact Tim Bynum, the Linux HOWTOcoordinator, atlinux-howto@sunsite.unc.eduvia email.