Previous versions of IRIX used an extended version of the Common Object File Format (COFF) for object files. The current compiler system produces ELF object files instead. ELF is the format specified by the System V Release 4 Applications Binary Interface (the SVR4 ABI). In addition, ELF provides support for Dynamic Shared Objects, described below. Types of ELF object files include:

COFF executables continue to run on new releases of IRIX, but the current compiler system has no facility for creating or linking COFF executables. COFF and ELF object files may not be linked together. To take advantage of new IRIX features, you must recompile your code.

IRIX executes all binaries that are compliant with the SVR4 ABI, as specified in the System V Applications Binary Interface—Revised Edition and the System V ABI MIPS Processor Supplement. However, binaries compiled under this version of the compiler system are not guaranteed to comply with the SVR4 ABI. The MIPS-specific version of the SVR4 ABI is referred to as the MIPS ABI. Programs that comply with the MIPS ABI can be run on any machine that supports the MIPS ABI.

IRIX 5.0 introduced a new kind of shared object called a Dynamic Shared Object, or DSO. The object code of a DSO is position-independent code (PIC), which can be mapped into the virtual address space of several different processes at once. DSOs are loaded at run time instead of at linking time, by the run-time loader, rld. As is true for static shared libraries, the code for DSOs is not included in executable files; thus, executables built with DSOs are smaller than those built with non-shared libraries, and multiple programs may use the same DSO at the same time.

Static shared libraries are only supported under this release for the purposes of running old (COFF) binaries. The current compiler system has no facilities for generating static shared libraries.

You can find additional information about DSOs in Chapter 3, "Dynamic Shared Objects."

Dynamic linking requires that all object code used in the executable be position-independent code. For source files in high-level languages, you just need to recompile to produce PIC. Assembly language files must be modified to produce PIC; see Appendix A, "Position-Independent Coding in Assembly Language," for details.

Position-independent code satisfies references indirectly by using a global offset table (GOT), which allows code to be relocated simply by updating the GOT. Each executable and each DSO has its own GOT.

The compiler system now produces PIC by default when compiling higher-level language files. All of the standard libraries are now provided as DSOs, and therefore contain PIC code; if you compile a program into non-PIC, you will be unable to use those DSOs. One of the few reasons to compile non-PIC is to build a device driver, which doesn't rely on standard libraries; in this case, you should use the –non_shared option to the compiler driver to negate the default option, –KPIC. For convenience, the C library and math library are provided in non-shared format as well as in DSO format (although the non-shared versions are not installed by default). These libraries can be linked –non_shared with other non-PIC files.

When running position-independent code, the global pointer is used to point to the global offset table, so you can no longer use the –G option to store data in the global pointer region (that is, –KPIC, the default, implies –G 0). The compiler ignores any user-specified –G number other than zero. For more information about this option, see the ld(1) reference page.

You can find additional information about PIC in Appendix A, "Position-Independent Coding in Assembly Language."

Each compiler driver recognizes the type of an input file by the suffix assigned to the file name. Table 2-1 describes the possible file name suffixes.

The following example compiles preprocessed source code:

f77 -c tickle.i

The Fortran compiler, f77, assumes the file tickle.i contains Fortran statements (because the Fortran driver is specified). f77 also assumes the file has already been preprocessed (because the suffix is .i), and therefore does not invoke the preprocessor.

Header files, also called include files, contain information about the libraries they're associated with. They define such things as data structures, symbolic constants, and prototypes and parameters for the functions in the library.

For example, the stdio.h header file describes, among other things, the data types of the parameters required by printf(). To use those definitions without having to type them into each of your source files, you can use the #include command to tell the macro preprocessor to include the complete text of the given header file in the current source file. Including header files in your source files allows you to specify such definitions conveniently and consistently in each source file that uses any of the library routines.

By convention, header file names have a .h suffix. Each programming language handles these files the same way, via the macro preprocessor.

---

Note: Do not put any code other than definitions in an include file, particularly if you intend to debug your program using dbx. The debugger recognizes an include file as only one line of source code, so source lines in an include file do not appear during debugging sessions.

---

Specifying a Header File

The #include command tells the preprocessor to replace the #include line with the text of the indicated header file. The usual way to specify a header file is with the line:

#include <filename>

where filename is the name of the header file to be included. The angle brackets (< >) surrounding the file name tell the macro preprocessor to search for the specified file only in directories specified by command-line options and in the default header-file directory (/usr/include).

Another specification format exists, in which the file name is given between double quotation marks:

#include "filename"

In this case, the macro preprocessor searches for the specified header file in the current directory first, then (if it doesn't find the requested file) goes on and searches in the other directories as in the angle-bracket specification.

---

Note: When you specify header files in your source files, the #include keyword should always start in column 1 (that is, the left-most column) to be recognized by the preprocessor.

---

Creating a Header File for Multiple Languages

A single header file can contain definitions for multiple languages; this setup allows you to use the same header file for all programs that use a given library, no matter what language those programs are in.

To set up a shareable header file, create a .h file and enter the definitions for the various languages as follows:

#ifdef _LANGUAGE_C C definitions #endif #ifdef _LANGUAGE_C_PLUS_PLUS C++ definitions #endif #ifdef _LANGUAGE_FORTRAN Fortran definitions #endif and so on for other language definitions

---

Note: To indicate C++ definitions you must use _LANGUAGE_C_PLUS_PLUS, not _LANGUAGE_C++.

---

You can specify the various language definitions in any order, but you must specify _LANGUAGE_ before the language name.

At compilation time, you can select one or more options that affect a variety of program development functions, including debugging, optimization, and profiling facilities. You can also specify the names assigned to output files. However, some options have default values that apply if you do not specify the option.

When you invoke a compiler driver with source files as arguments, the driver calls other commands that compile your source code into object code. It then optimizes the object code (if requested to do so) and links together the object files, the default libraries, and any other libraries you specify.

Given a source file foo.c, the default name for the object file is foo.o. The default name for an executable file is a.out. So the following example compiles source files foo.c and bar.c with the default options:

cc foo.c bar.c

This example produces two object files (foo.o and bar.o), then links those together with the default C library libc to produce an executable called a.out.

---

Note: If you compile a single source directly to an executable, the compiler does not create an object file.

---

The command-line options for IRIS-4D compiler drivers are listed and explained in Table 2-2. The table lists only the most frequently used options; for a list of all available options, refer to the appropriate compiler reference page. Note that not all of the options work with every driver.

You can use the compiler system to generate profiled programs that, when executed, provide operational statistics. To perform this procedure, use the –p compiler option (for pc sampling information) and the pixie program (for profiles of basic block counts). Refer to Chapter 4, "Using the Performance Tools," for details on prof and pixie.

In addition to the general options in Table 2-2, each driver has options that you typically won't use. These options primarily aid compiler development work. For information about nonstandard driver options, consult the appropriate driver reference page.

---

Note: To use 4.3 BSD extensions in C, compile using –xansi or by using the –D__EXTENSIONS__ option on the command line. For example: cc prog.c -ansi -prototypes -fullwarn -lm -D__EXTENSIONS__

---

Usually the linker is invoked by the compiler driver as the final step in compilation (as explained in "Compiler Drivers"). If you have object files produced by previous compilations that you want to link together, you can invoke the linker using a compiler driver instead of calling ld directly; just pass the object-file names to the compiler driver in place of source-file names. If the original source files were in a single language, simply invoke the associated driver and specify the list of object files. (For information about linking together objects derived from several languages, see "Linking Multilanguage Programs.")

A few command-line options to ld, such as –p, have different meanings when used as command-line options to cc. To pass such options to ld through an invocation of a compiler driver, use the –Wl option to the driver (see the reference page for details).

Typically, the compiler driver invokes ld as necessary. Circumstances exist under which you may need to invoke ld directly, such as when you're building a shared object or doing special linking not supported by compiler drivers (such as building an embedded system). To build C++ shared objects, use the CC driver.

ld options object1 [object2...objectn]

Linker Example

The following command tells the linker to search for the DSO libcurses.so in the directory /lib. If it does not find that DSO, the linker then looks for libcurses.a in /lib; then for libcurses.so in /usr/lib, then in the same directory for libcurses.a. If it hasn't found an appropriate library by then, it looks in /usr/local/lib for libcurses.a. (Note that the linker does not look for DSOs in /usr/local/lib, so don't put shared objects there.) If found in any of those places, the DSO or library is linked with the objects foiled.o and again.o:

ld foiled.o again.o -lcurses

---

Note: The –G option, which formerly allowed you to specify which data items should be stored in the global pointer region, is no longer useful. –KPIC, the default, implies –G 0, and the compiler ignores any user attempts to specify otherwise. Compiling –non_shared (to avoid –KPIC) is primarily useful only for creating device drivers, in which case there is no direct linking step in which to specify a –G number. For more information, see the cc and ld reference pages.

---

The assembler driver as1 does not run the linker. To link a program written in assembly language, use one of these procedures:

The linker ld processes its arguments from left to right as they appear on the command line. Arguments to ld can be DSOs, object files, or libraries.

When ld reads a DSO, it adds all the symbols from that DSO to a cumulative symbol table. If it encounters a symbol that's already in the symbol table, it does not change the symbol table entry. If you define the same symbol in more than one DSO, only the first definition is used.

When ld reads an archive, usually denoted by a file name ending in .a, it uses only the object files from that archive that can resolve currently unresolved symbol references. (When a symbol is referred to but not defined in any of the object files that have been loaded so far, it's called unresolved.) Once a library has been searched in this way, it is never searched again. Therefore, libraries should come after object files on the command line in order to resolve as many references as possible. Note that if a symbol is already in the cumulative symbol table from having been encountered in a DSO, its definition in any subsequent library is ignored.

Specifying Libraries and DSOs

You can specify libraries and DSOs either by explicitly stating a pathname or by use of the library search rules. To specify a library or DSO by path, simply include that path on the command line (relative to the current directory, or else absolute):

ld myprog.o /usr/lib/libc.so.1 mylib.so

---

Note: libc.so.1 is the name of the standard C DSO, replacing the older libc.a. Similarly, libX11.so.1 is the X11 DSO. Most other DSOs are simply named name.so, without a .1 extension.

---

To use the linker's library search rules, specify the library with the –llibname option:

ld myprog.o -lmylib

When the –lmylib argument is processed, ld searches for a file called libmylib.so. If it can't find libmylib.so in a given directory, it tries to find libmylib.a there; if it can't find that either, it moves on to the next directory in its search order. The default search order is to look first in /lib, then in /usr/lib. After looking in both of those directories, ld looks in /usr/local/lib for archives only (DSOs should not be installed in /usr/local/lib). You can modify these defaults by specifying the –Ldir and/or –nostdlib options. Directories specified by –Ldir before the –llibname argument are searched in the order they appear on the command line, before the default directories are searched. If –nostdlib is specified, then –Ldir must also be specified because the default directories aren't searched at all.

If ld is invoked from one of the compiler drivers, all –L and –nostdlib options are moved up on the command line so that they appear before any –llibname option. For example:

cc file1.o -lm -L mydir

This command invokes, at the linking stage of compilation:

ld -L mydir file1.o -lm

---

Note: There are three different kinds of files that contain object code files: non-shared libraries, PIC archives, and DSOs. Non-shared libraries are the old-fashioned kind of library, built using ar from .o files that were compiled with –non_shared. These archives must also be linked –non_shared. PIC archives are the default in IRIX 5.0, built using ar from .o files compiled with –KPIC (a default option); they can be linked with other PIC files. DSOs are built from PIC .o files by using ld –shared; see Chapter 3 for details.

---

When compiling multilanguage programs, be sure to specify any required run-time libraries using the –llibname option. For a list of the libraries that a language uses, see the corresponding compiler driver reference page.

If the linker tells you that a reference to a certain function is unresolved, check that function's reference page to find out which library the function is in. If it isn't in one of the standard libraries (which ld links in by default), you may need to specify the appropriate library on the command line. For an alternative method of finding out where a function is defined, see "Finding a Symbol in an Unknown Library."

---

Note: Simply including the header file associated with a library routine is not enough; you also must specify the library itself when linking (unless it's a standard library). There is no magical connection between header files and libraries; header files only give prototypes for library routines, not the library code itself.

---

cc foo.c -lm

cc foogl.c -lgl -lX11

This section describes how to link your source files with previously built DSOs; for more information about how to build your own DSOs, see Chapter 3, "Dynamic Shared Objects."

---

Note: DSOs replace the older static shared libraries, which were named with the extension _s.a. The _s.a libraries are no longer shipped with IRIX; however, the run-time versions of those libraries, named with _s at the end (and no .a), are still present under IRIX 5.0 for backward compatibility with older executables that used static shared libraries.

---

To build an executable that uses a DSO, call a compiler driver just as you would for a non-shared library. For instance,

cc needle.c -lthread

links the resulting object file (needle.o) with the previously built DSO libthread.so (and the standard C DSO, libc.so.1), if available. If no libthread.so exists, but a PIC archive named libthread.a exists, that archive is used with libc.so.1, and you still get dynamic (run-time) linking. Note that even .a libraries now contain position-independent code by default, though it is also possible to build non-shared .a libraries that do not contain PIC.

When the source language of the main program differs from that of a subprogram, use the following steps to link (refer to Figure 2-1):

The compiler drivers supply the default set of libraries necessary to produce an executable from the source of the associated language. However, when producing executables from source code in several languages, you may need to explicitly specify the default libraries for one or more of the languages used. For instructions on specifying libraries, see "Linking Libraries."

Figure 2-1. Compilation Control Flow for Multilanguage Programs

For specific details about compiling multilanguage programs, refer to the programming guides for the appropriate languages.

You can use ld to locate unresolved symbols. For example, suppose you're compiling a program, and ld tells you that you're using an unresolved symbol. However, you don't know where the unresolved symbol is referenced.

To find the unresolved symbol, enter:

ld -ysymbol file1... filen

The output lists the source file that references symbol.

The dis tool disassembles object files into machine instructions. You can disassemble an object, archive library, or executable file.

dis options filename1 [filename2... filenamen]

The elfdump tool lists headers, tables, and other selected parts of an ELF-format object file or archive file.

elfdump options filename1 [filename2... filenamen]

The file tool lists the properties of program source, text, object, and other files. This tool attempts to identify the contents of files using various heuristics. It is not exact and is occasionally fooled. For example, it often erroneously recognizes command files as C programs. For more information, see the file(1) reference page.

file filename1 [filename2... filenamen]

file test.o a.out /lib/libc.so.1test.o:        ELF 32-bit MSB relocatable MIPS - version 1 
a.out:         ELF 32-bit MSB dynamic executable (not stripped) MIPS - version 1
/lib/libc.so.1:   ELF 32-bit MSB dynamic lib MIPS - version 1

The nm tool lists symbol table information for object files and archive files.

nm options filename1 [filename2... filenamen]

#include <stdio.h>
#include <math.h>
#define LIMIT 12
int unused_item = 14;
double mydata[LIMIT];

main()
{
    int i;
    for(i = 0; i < LIMIT; i++) {
        mydata[i] = sqrt((double)i);
    }
    return 0;
}

cc -c tnm.c

nm -B tnm.o 

0000000000 T main
0000000000 B mydata
0000000000 U sqrt
0000000000 D unused_item
00000000 N _bufendtab

nm tnm.o 
Symbols from tnm.o:

[Index] Value  Size  Class    Type       Section    Name

[0]     |      0|    |File    |ref=4     |Text     | tnm.c
[1]     |      0|    |Proc    |end=3 int |Text     | main
[2]     |    116|    |End     |ref=1     |Text     | main
[3]     |      0|    |End     |ref=0     |Text     | tnm.c
[4]     |      0|    |File    |ref=6     |Text     | /usr/include/math.h
[5]     |      0|    |End     |ref=4     |Text     | /usr/include/math.h
[6]     |      0|    |Global  |          |Data     | unused_item
[7]     |      0|    |Global  |          |Bss      | mydata
[8]     |      0|    |Proc    |ref=1     |Text     | main
[9]     |      0|    |Proc    |          |Undefined| sqrt
[10]    |      0|    |Global  |          |Undefined| _gp_disp

cc prog.c -lgl 
ld:
Unresolved:
XGetPixel

nm -Bo /usr/lib/lib*.so* | grep XGetPixel | grep T/usr/lib/libX11.so.1: 0f790ff8 T XGetPixel

cc prog.c -lgl -lX11

The odump tool lists headers, tables, and other selected parts of a COFF-format object or archive file. It is provided with this release of IRIX for compatibility; use elfdump for ELF-format files.

odump options filename1 [filename2... filenamen]

The size tool prints information about the sections (such as text, rdata, and sbss) of the specified object or archive files. The a.out(4) reference page describes the format of these sections.

size options [filename1 filename2... filenamen]

size -B -o test.o

       text  data bss   rdata sdata  sbss decimal hex
test.o 31250 2010 40470 550   210    50   31232   7a00

size -B -d test.o

       text  data bss   rdata sdata sbss decimal hex
test.o 12968 1032 16696 360   136   40   31232   7a00

The strip tool removes symbol table and relocation bits that are attached to the assembler and loader. Use strip to save space after you debug a program. The effect of strip is the same as that of using the -s option to ld.

strip options filename1 [filename2... filenamen]

The syntax for ar is:

ar options [posObject] libName [object1... objectn]

When running the archiver, specify exactly one of the options d, m, p, q, r, t, or x (listed in Table 2-12). In addition, you can optionally specify any of the modifiers in Table 2-13, as well as any of the archiver suboptions listed in Table 2-14.

---

Note: The a and b suboptions are only useful if the same symbol is defined in two or more of the object files in the archive (in which case, the symbol table shows the first definition listed in the archive). Under other circumstances, order of object files in an archive is irrelevant (and the a and b suboptions are useless), since ld uses the archive symbol table rather than searching linearly through the file.

---

Create a new library, libtest.a, and add object files to it by entering:

ar cq libtest.a mcount.o mon1.o string.o

The c option suppresses an archiver message during the creation process. The q option creates the library and puts mcount.o, mon1.o, and string.o into it.

An example of replacing an object file in an existing library:

ar r libtest.a mon1.o

The r option replaces mon1.o in the library libtest.a. If mon1.o does not already exist in the library libtest.a, it is added.

---

Note: If you specify the same file twice in an argument list of files to be added to an archive, that file appears twice in the archive.

---

To add a new file immediately before mcount.o in this library, enter:

ar rb mcount.o libtest.a new.o

The r option adds new.o to the library libtest.a. The b option followed by mcount.o as the posObject causes the archiver to place new.o immediately before mcount.o in the archive.