DSO(5)DSO(5) NAME DSO - Dynamic Shared Object (DSO) DESCRIPTION This man page describes Dynamic Shared Objects (DSOs). It is divided into the following 4 sections: * Overview * Linking and building DSOs * Performance considerations * Frequently asked questions OVERVIEW A DSO is an ELF format object file. It is very similar in structure to an executable program, but it has no main program. It has the following components: * A shared component, which consists of shared text and read-only data. * A private component, which consists of data and the Global Offset Table (GOT). * Several sections that hold information needed to load and link the object. * A liblist, which is the list of other DSOs referenced by this object. Most libraries supported on IRIX platforms are available as DSOs. Position Independent Code (PIC) A DSO is relocatable at runtime; it can be loaded at any virtual address. A consequence of this is that all references to external symbols must be resolved at runtime. References from a private region (that is, from private data) are resolved at load time. References from a shared region (that is, from shared text) go through the indirection table, which is also called the Global Offset Table (GOT), and incur a small performance penalty. The GOT helps facilitate Position Independent Code (PIC). PIC is code that satisfies references indirectly by using the GOT, which allows code to be relocated simply by updating the GOT. Each executable and each DSO has its own GOT. The GOT is a data table with the actual addresses of global data with appropriate code generation and linking support. The linker, ld(1), constructs the GOT. PIC satisfies references indirectly by using the GOT, which allows code to be relocated simply by updating the GOT. PIC can be shared by multiple users. Each program must have its own data space. Code sharing and independent data is arranged automatically by the compilation and run-time systems. Code compiled for use in a DSO is PIC. Non-PIC code is usually referred to as non-shared. Non-shared code and PIC cannot be mixed in the same object. What Happens at Runtime? The runtime events are as follows: 1. exec(2) loads the main program and then loads one of the following interpreters as specified in the main program: * /usr/lib/libc.so.1 is loaded for programs compiled with the -32 compiler option. * /usr/lib32/libc.so.1 is loaded for programs compiled with the -n32 compiler option. * /usr/lib64/libc.so.1 is loaded for programs compiled with the -64 compiler option. 2. The interpreter loads rld(5), the runtime linking loader, which finishes the exec(2) operation. Starting with the main program's liblist, rld(5) loads each DSO on the list that is not marked to be delay-loaded. rld(5) reads that object's liblist and repeats the operation until all DSOs have been loaded, in a breadth-first manner. The breadth first loading process, which ignores objects marked to be delay-loaded, results in defining a sequence of objects. 3. rld(5) allocates storage for COMMON block symbols and fixes up symbolic references in each loaded object. This is necessary because the location at which the object will be loaded is not known until runtime. To look up a given symbol in the process of fixing up symbolic references, rld(5) examines each object's dynamic symbol table. If rld(5) finds a strong symbol that satisfies the reference (that is, it has the name of the given symbol and is an external definition) it stops with that symbol. If it does not find a strong definition with that name, then the first weak symbol found is accepted as the definition. 4. Each object's -init code is executed. These routines are specified with the linker's init option (ld -init). For information about -init code, see ld(1). 5. Control transfers to __start in the main program. The sequence at which the -init code is run is important to applications and DSOs that have -init code. By default, objects are taken in reverse order of the sequence defined in loading. If -init code in one DSO calls a DSO with -init code that has not yet run, then the -init code in the called DSO is run before the called DSO routine is actually called. Thus, the default order is not followed. It is not an error for DSOs to mutually call one another, even indirectly, from within -init sections, but the resulting DSO ordering can be confusing and can vary depending on actions in the application -init code. The -init code in delay-loaded DSOs is not run until the DSO is actually loaded, and the delay-loaded DSO is loaded when some routine in the delay-loaded DSO is called. Do not include calls to sproc(2), nsproc(2), sprocsp(2), or any POSIX threads (pthreads) routines from within -init or -fini code. The following table describes the problem with -init and -fini code in pthreads and sproc(2) applications: -------------------------------------------------------------------- Threads? sigprocmask(2)Getting MaskBits sigprocmask(2)Setting MaskBits -------------------------------------------------------------------- sproc(2) threads Seesmoremaskedthan non-init. Settingslostonexit of-initand-fini. pthreads Seesmoremaskedthan non-init. Applicationsettings preserved. No threads Seestruesetting. Applicationsettings preserved. -------------------------------------------------------------------- The preceding table entries can be explained as follows: * In the Threads? column, An sproc(2) threads application is one that is using sproc(2), nsproc(2), or sprocsp(2). A pthreads application is one that has libpthread.so linked in. A No threads application is any other application. * Sees more masked than non-init means that -init and -fini code do not get the true mask bits. Instead, nearly all signals are marked as masked. * Settings lost on exit of -init and -fini means that on exit of the nested set of -init or -fini functions, the set of mask bits set on entry to the functions is restored. Any setting done by the -init or -fini code is lost. * Application settings preserved means that the sigprocmask(2) bit settings that are made by the -init or -fini code are preserved on exit of the -init or -fini function set. * Sees true setting means that the mask bits that sigprocmask(2) returns to -init and -fini code are the true application mask bits. As the preceding table shows, the complexities with signal masks inhibit successful sigprocmask(2) operation in -init or -fini code. Generally, the results are not going to be what is desired. Also ignored, in theory, are symbols in any DSO that is loaded at runtime because it is on the liblist of a DSO opened by dlopen(3C) or sgidlopen_version(3C). rld(5) makes the liblist DSO symbols visible, but no application should count on this visibility. However, if a DSO's symbols are visible for any reason (for example, because it was in the main program's liblist), that DSO is not hidden just because it is also on the library list of a DSO opened with dlopen(3C) or sgidlopen_version(3C). When execution terminates, the -fini code of each DSO and the base a.out file is run in the opposite order the actual -init code was run (or would have been run, in the case of DSOs with -fini code but no -init code). -fini code and -init code consist of code specified as an argument to the ld(1) For more information on -fini code and -init code, see the rest of this man page and see ld(1). Other factors can affect the general load process, too. For more information, see the information on Quickstart and delayed loads on this man page and see the sgidladd(3C), sgidlopen_version(3C), and dlopen(3C) man pages. -init Code Runtime Ordering The general order in which the base executable DSO's -init code is run is specified by the MIPS Application Binary Interface (API). For more information on this ABI, see the URLs mentioned in the SEE ALSO section. Before an -init in object A is run, you can assume that all -init sections in DSOs that A depends on have been run. However, if -init code calls a DSO with -init code that has not yet run, the -init code of the called DSO is run first. The physical ordering starts with the last DSO in rld(5)'s list and works toward the executable file. This is a depth-first postorder call of -init code. This is a particular choice of ordering within the conceptual framework. The physical ordering is not specified by the MIPS ABI. The run order of delay-loaded DSOs and DSOs that have been opened by dlopen(3C) is recorded so that -fini operations occur in reverse order. Any DSO that is delay-loaded during the execution of -init code changes the order in which -init sections are run. The actual manner of the changes is difficult to predict. At the time of the delay-load, the -init code scan is restarted anew (new due to the new DSO) at the end of rld(5)'s list. -fini Code Runtime Ordering The -fini code of the DSOs in the base executable is run choosing DSOs in the opposite order the actual -init code was run (or would have been run, in the case of DSOs with -fini code but no -init code). Limitations on -init and -fini Code In most versions of rld(5), -init and -fini code could not successfully perform delay-load operations, such as dlopen(3C), sgidladd(3C), dlsym(3C), dlclose(3C), or implicit delay-load operations, if the application used sproc(2), sprocsp(2), or pthreads (nsproc is no longer a public function). Threaded applications hung if such operations were included in -init or -fini code or were nested codes outside of -init or -fini code. The current release of rld(5), however, supports nested delay-load operations, but it is unwise to depend too much on this support. For example, it is unwise to use delay-loading with C++ global initialization code because much about the interaction of name resolution (name binding and symbol binding) with nested delay-load operations is unspecified. For example, calling a delay-load routine or calling delay-loaded functions in different orders depending on startup conditions means that the ordering of DSOs on rld(5)'s list of DSOs may vary. If the order varies and there are multiple definitions of an external (different functions with the same name), exactly what is executed from run to run may differ. Considering that is it difficult, in C++, to control the sequence in which different compilation units -init code is executed, and potentially, you have serious application problems. It is also difficult to debug such code as debuggers often have difficulting intercepting calls in -init sections. In multithreaded programs, -init and -fini code should avoid attempts to acquire (by using pthread_mutex_lock(3P), for example) resources owned by other threads, unless it can be guaranteed that the other thread can release the resource without performing a delay-load operation or lazy text resolution. Should the thread owning the resource make a call into rld(5), the threads deadlock. It is difficult to predict whether execution of a given section of code requires lazy text resolution. A DSO's GOT can be reset to point at function stubs when it fails to Quickstart or after delay-load operations that might affect resolution of its symbols. See the section on Quickstart in the PERFORMANCE CONSIDERATIONS section of this man page for more information on function resolution. The C++ runtime system uses the -init and -fini mechanism to construct and destroy static objects. Therefore, constructors and destructors for such objects should avoid blocking calls if DSOs using them are to be manipulated by dlopen(3C) or dlclose(3C) or are to be delay-loaded within a multithreaded program. LINKING AND BUILDING DSOs Assume that your library is in an archive libfoo.a of object files, all of which have been compiled with the ld(1) command's -shared option. The library references symbols found in libc.so.1, libgl.so, libX11.so, and libnetls.so, but most programs never use the path that requires libnetls.so. It is recommended that you build your DSO, libfoo.so, in the following way: ld -elf -shared -no_unresolved -rdata_shared -soname libfoo.so -o libfoo.so -all libfoo.a -lX11 -delay_load -lnetls -lc -lgl This builds a DSO called libfoo.so that directs rld(5) to load libc.so.1, libX11.so, and libgl.so whenever libfoo.so is loaded. This command line also loads libnetls.so if it is ever referenced. NOTE: If you have any C++ object files among the objects making up your DSO, you must replace ld in the previous example command with CC. That is, your command line should be as follows: CC -elf -shared ... -o libfoo.so -all libfoo.a ... However, you do not have to do anything special at all to use such C++ DSOs when linking other programs against these DSOs. You can link C++ DSOs into C, C++, or Fortran programs using your usual link commands or link other DSOs against these C++ DSOs without taking any special action. For example, the following command line links the preceding C++ DSO libfoo.so properly: f77 fortran_prog.o -lfoo Controlling Symbols Exported by a DSO One benefit from using DSOs is the ability to release new versions of an object and be assured that objects linked against the old version will work with the new version. This is impossible to guarantee, however, if the set of symbols exported by an object cannot easily be understood by the object's creator. ld(1) provides several options to help you control the symbols that are exported by a DSO. By default, ld(1) does not export symbols that are supplied by a linked-in archive or DSO. The developer is probably only a consumer of the linked-in object, not an exporter. In a subsequent release, the developer may not require the linked-in object, and if the symbols provided by the linked-in object had been exported by the developer's object, the new object would no longer be upwardly compatible with the original version. This behavior can be overridden by using the -exports option on the ld(1) command. This default symbol hiding behavior, with respect to archives, is also overridden when building a DSO from an archive using the -all option. You can control the list of symbols that are exported by using the following ld(1) options: -exported_symbol, -exports_file, -exports, -hides, -hidden_symbol, and -hides_file. The first two options let you specifically list the symbols to be exported by the DSO. The exported_symbol option is followed by a comma-sepatated list of names. The exports_file option accepts a file name that contains a space-separated (including newlines) list of names. If any symbols are specifically exported, only those symbols are exported. All other symbols are automatically hidden. The last two options specify a list of symbols that are not to be exported by the DSO. For more information on the ld(1) options, see the ld(1) man page. There are two consequences of hiding symbols. First, those symbols do not provide resolution to any undefined symbols in an object that links in the DSO. Second, any references to those symbols within the DSO are resolved internally to the hidden symbol. Rules of Thumb The following list contains things to remember when using the ld(1) command: * Use the -no_unresolved option to find unresolved symbols. It is not always possible to supply all the DSOs that will be referenced by libfoo.so on the link line, but in general, libraries should be self-contained. This is especially true for subsequent releases of a DSO. If a DSO has any unresolved references, they must be resolved by some other loaded object. Having unresolved symbols invites disaster because there is no guarantee that the symbols will be resolved. Thus, the application may not run. * Link against the minimum set of .so files needed. Loading a DSO carries a cost. Linking against unneeded DSOs causes them to be loaded even if they are never referenced. ld(1) issues a message when you have linked against a DSO that resolves no symbols. * When building a C++ DSO, specify the -exports option for any DSO that provides the definitions of classes from which classes in the object being created are derived. Specifying -exports in this case ensures that consumers of the object being created can create subclasses of classes provided by that object without having to know the complete set of DSOs that need to be loaded. Using the -exports option in this case may bring in unwanted symbols. Use the -exported_symbol, -exports_file, -hidden_symbol, or -hides_file options where appropriate. * Use the -rdata_shared option to move all read-only data into the shared segment. Unfortunately, many programs write to supposedly read-only data. The -rdata_shared option is disabled by default for this reason. The -use_readonly_const compiler option is enabled by default. * Always use thesoname option to provide a specific soname for the DSO. If you don't, the name is taken (with path if present on the link line) from the o option and in many cases this is not what you want. The following example ends up with an soname of tmp and the runtime linker will not be able to find libmy.so. cc -shared t.o -o tmp mv tmp libmy.so Use elfdump -L foo/libmy.so |grep SONAME to see the soname of libmy.so. cc -shared t.o -soname libmy.so -o tmp mv tmp libmy.so This is the way the above can be made to work properly. It is crucial that the soname and the final path element of the file (and and any symlinks pointing to the DSO) agree precisely (though if there are trailing SGI version numbers in the file name, such are not required or desired in the soname). Example: libany.so has soname of libany.so and no version string. This is the norm for most DSOs you will build (in most cases you are not worrying about DSO compatibility: you will simply rebuild everything when things change). Example: libmy.so.1 has soname of libmy.so and version of sgi1.0. This is a standard approach on IRIX as used for libc and other system DSOs. See the versioning info in the FAQ below. Example: libyours-1.3-special.so must have an soname of libyours- 1.3-special.so and a file name of something/libyours-1.3-special.so and any symlinks pointing directly to this DSO should have path/libyours-1.3-special.so as the name. This is a standard sort of DSO versioning/naming with Linux-derived DSOs for example. The soname/filename matching requirement is IRIX specific. If the names mismatch the error will not be noticed until rld tries to find the DSO. Adding .1 or the like according to SGI versioning (as described in the previous example and in more detail below in the FAQ area) is possible but not normally done with this version-embedded-in-name aproach. If the DSO is not one you build, you must be sure any file names and symlinks you set up naming the DSO match the built-in soname, as the soname is what will be used by the static linker (ld) to notify the run-time-linker (rld) what file-name to use to find the DSO. dlopen is more forgiving and sonames are not crucial. But nonetheless it is important you use -soname and file names as if you were using linking, not dlopen to access the DSO, as if you do change your mind the inability to run against a dso with an improper soname will seem mysterious and will involve a waste of your time tracking the problem down. * If you reference one of the graphics libraries, either libgl.so or libGL.so, put the library last in the link line. Often libgl.so cannot be Quickstarted. Putting it last allows all prior objects to be Quickstarted. You can also choose to delay-load the graphics libraries. This allows your application to Quickstart. For information on Quickstart, see the PERFORMANCE CONSIDERATIONS section of this man page. * Anytime a referenced object changes, you should either relink, in order to Quickstart, or you should run the reQuickstart tool rqs(1) on the object. * Try to minimize inter-DSO data references. * Try to minimize the use of global data. In DSOs, it is generally more efficient to allocate space when needed, using malloc(3C) or malloc(3F), rather than to use a large static data structure. * Try to pack data together that is likely to be unmodified. This allows the kernel to make more of the data pages shared, copy-on-write. * Use the -delay_load option on any DSO on the link line that is not often used. This incurs a small performance penalty for the references to it, but this can save time and memory for those programs that don't use it. In addition, using this option on programs that have -init or -fini code also incurs a performance penalty. * Do not call any of the following from code that may be executed during processing by the -init or -fini options: dlclose(3C), dlerror(3C), dlopen(3C), dlsym(3C), nsproc(2), sproc(2), sprocsp(2), sgidladd(3C), and sgidlopen_version(3C). * Avoid having weak and strong versions of a symbol that are loaded into memory at different times (by a -delay-load option or by sgidladd(3C) or dlopen(3C) calls). * Avoid performing a dlclose(3C) on an object that has been opened by sgidladd(3C). * Try to avoid using -init code by not using the option and by avoiding definition of C++ global objects that require -init code for construction. PERFORMANCE CONSIDERATIONS The following subsections describe verious performance considerations. Quickstart When building a DSO or an executable, ld(1) assigns addresses to the object and attempts to resolve all references. At runtime, if rld(5) verifies that the same set of objects are loaded at the original addresses, then rld(5) can skip all the runtime relocation work and let the program run. This saves time because the relocations are not performed, and it saves memory because rld(5) does not have to read in the sections that hold the relocation information. At static link time, ld(1) resolves each unresolved function call. When an unresolved function is called at runtime, rld(5) performs the relocation needed for all future calls to the original function. In this way, more programs can Quickstart even if some of the function references are not resolved at static link time. Quickstart fails if the DSOs on a system do not match the objects used when linking either the application or the DSOs upon which the application depends. This can occur if a new version of a DSO is released. You can use the rqs(1) command to recalculate the Quickstart information associated with an application or a DSO. rqs(1) must be called in proper order so that DSOs on an object's liblist are reQuickstarted before the object is reQuickstarted. rqs(1) rewrites the object it is reQuickstarting back in place. You can use the ld(1) command's -no_rqs option to mark an object as non-reQuickstartable. Avoiding Gratuitous Shared Object Loads rld(5) does a considerable amount of work and can use up large amounts of real memory, so it is better not to link against DSOs that are not needed. Reducing the Number of Conflicts A conflict arises whenever more than one DSO (including the main program) needed by an executable defines and uses the same name for a symbol. The name for which multiple definitions exist is recorded in your program in the section named .conflict. The names of all conflicting symbols pertaining to a program can be obtained by using -Dc flag to elfdump(1). One example of a conflict is the malloc routine, which is defined both in libc.so.1 and in libmalloc.so. Conflicts represent extra work to be done at startup because the presence of a conflict means that the objects in the link may not have chosen a consistent instance of the symbol in question. This extra work is memory-intensive because even one conflict can mean that many pages of memory must be examined by rld(5). This intensive examination would otherwise not be needed for a Quickstarting program. The ld(1) command's -quickstart_info option causes ld(1) to issue a warning about every conflict it finds and to write the names of two of the objects in which it is defined. Of course, sometimes conflicts are a necessary design component of certain applications. Delayed Loads The overhead associated with objects that are referenced but seldom used can be mitigated by using dlopen(3C), sgidlopen_version(3C), sgidladd(3C), or delayed loads. Using any of these delays the loading of a DSO (and the objects on its liblist) until it is actually referenced. The -delay_load option on the ld(1) command is the easiest and most convenient to use. All three require that there be no references from any other object's data section to the delay-loaded DSO. FREQUENTLY ASKED QUESTIONS This section contains answers to frequently asked questions. The questions and their answers are as follows: 1. What is a DSO? DSO stands for Dynamic Shared Object. DSOs give applications the ability to share the text of heavily used libraries, which need not be included in the executable file. 2. How do I maintain binary compatibility between versions of DSOs? Binary compatibility is maintained as long as the DSOs maintain the same exported symbols, add new symbols without removing any or changing semantics, and don't change exported structures. The ordering of symbols, routines, and global data is irrelevant. 3. What object file format do DSOs use? DSOs use the ELF object file format as defined in the SVR4 ABI. 4. How do I install the tools so I can use DSOs on my system? To compile and build DSOs, you need to nstall the IRIX Development Foundation (IDF) and the IRIX Development Libraries (IDL); these were formerly known as the Developer's Option. In addition, you must have a compiler. 5. How do I build an executable file that uses a DSO? A command line like the following links myfile.c with libmine.so and with libc.so.1: cc myfile.c -lmine If libmine.so is not available, but libmine.a is available, libmine.a is used along with libc.so.1, and you get dynamic linking. To explicitly state that you want the DSO to be used, add the -call_shared option to the cc(1) line, as follows: cc -call_shared myfile.c -lmine 6. How do I build an executable file that does not use shared linking? Use the -non_shared option, as follows: cc -non_shared myfile.c -lmine Some libraries are not available as nonshared. The ones that are available are not installed by default, so you must request their installation. In general, the -non_shared option is outmoded. 7. How do I tell if an executable file will use dynamic linking? Entering the following command generates the ELF program header: elfdump -o executable This header contains all the information necessary for exec(2) and rld(5) to run the program or DSO. Only a.out files that use dynamic linking have a PHDR, INTERP, or DYNAMIC entry. An example and a more detailed description is as follows: % elfdump -o /bin/cat /bin/cat: ***** PROGRAM EXECUTION HEADER ***** Type Offset Vaddr Paddr Filesz Memsz Align Flags PT_PHDR 0x34 0x10000034 0x10000034 0xe0 0xe0 0x4 r--- PT_INTERP 0x114 0x10000114 0x10000114 0x15 0x15 0x1 r--- PT_MIPS_OPTIONS 0x130 0x10000130 0x10000130 0x80 0x80 0x8 r--- PT_MIPS_REGINFO 0x1b0 0x100001b0 0x100001b0 0x18 0x18 0x4 r--- PT_DYNAMIC 0x1c8 0x100001c8 0x100001c8 0x118 0x118 0x4 r--- PT_LOAD 0 0x10000000 0x10000000 0x3000 0x3000 0x4000 r-x- PT_LOAD 0x4000 0x10014000 0x10014000 0x1000 0x1414 0x4000 rw-- Each type is an entry in the program header and refers to a segment of the file, as follows: Type Segment PT_PHDR Points to the program header itself within the file. Only executable files that use dynamic linking have this field. PT_INTERP Points to the location of the name of the interpreter required for this program. For any old 32-bit ABI object, compiled with -32, this is /usr/lib/libc.so.1. For any new 32-bit ABI object, compiled with -n32, this is /usr/lib32/libc.so.1. For any 64-bit ABI object, compiled with -64, this is /usr/lib64/libc.so.1. PT_MIPS_REGINFO Points to the location of the register setup information. This information can be seen by entering the elfdump -reg command. For the old 32-bit ABI, obtained when compiling with -32, this consists of the correct global pointer (gp) value for this object. For the new 32-bit or 64-bit ABIs, obtained when compiling with -n32 or -64, this entry does not appear in this table; for these ABIs, the information is in .MIPS.options, which can be seen by entering the elfdump -reg or elfdump -op commands. PT_DYNAMIC Points to information in the file needed by rld(5). Includes the liblist (which can be seen by entering the elfdump -Dl command), a symbol table (which can be seen by entering the elfdump -Dt command), and other information. PT_LOAD Points to segments that are to be mapped into the memory image. PT_RWX Specifies the protections, read, write, or execute, for the segment. The columns give various information about each segment, as follows: Column Content Offset The offset in the file to the beginning of the segment. Vaddr The virtual address of the beginning of the segment in the memory image of the file, assuming that it was mapped as described in the LOAD entries. Paddr The same as Vaddr. Filesz The size of the segment in the file. Memsz The size of the segment in the memory image. When Memsz is greater than Filesz, the bytes after Filesz are zero-filled. Align The alignment required by this section. If a segment is to be mapped somewhere into memory other than at Vaddr, the new address must be congruent to Vaddr modulo the alignment. In the preceding example, both segments must always be loaded on a 64K (0x4000) byte boundary. Programs that are linked with the -non_shared option on the compiler command line do not have a PHDR, INTERP, or DYNAMIC section. Thus, the elfdump -o command is a convenient way to determine whether a program is linked as nonshared. For more information on this command, see the elfdump(1) man page. 8. How do I build a DSO? Perform the following steps: 1. Build a file.o or file.a that contains all the routines you want to have in your file.so (your DSO). This can be done with a compiler and ar(1). 2. Invoke ld(1) with the -shared option. Normally, the extension .so is used to designate DSOs. Example 1: cc -c myobj.c ld -shared myobj.o -o myobj.so Example 2: cc -c myobj.c cc -shared myobj.o -o myobj.so Example 3: <build libmine.a the usual way> ld -shared -all libmine.a -o libmine.so The -all option in the third example directs ld(1) to include all the routines in the library. This option is needed because there are not undefined references in the program, which is the usual way for ld(1) to determine whether to load files from an archive. 9. Where does the system look for DSOs at runtime? The search path for DSOs is acquired in the following order for programs compiled with the -32 compiler option: 1. The path of the DSO if given in the liblist 2. In any directories specified with the -rpath option when the executable file was built 3. In any directory specified by the LD_LIBRARY_PATH environment variable, if it is defined 4. In the directories in the default path, which is /usr/lib, /usr/lib/internal, /lib, /lib/cmplrs/cc, /usr/lib/cmplrs/cc, /opt/lib. If the _RLD_ROOT environment variable is defined, then its value is appended to the front of any path specified by the -rpath option and the default path. _RLD_ROOT itself is a colon (:) separated list. For programs compiled with the -n32 compiler option, the rules are similar, but the following differences exist: * The LD_LIBRARYN32_PATH is used if LD_LIBRARY_PATH is defined. * _RLDN32_ROOT is used for the list of paths * The default path directory list is /usr/lib32, /usr/lib32/internal, /lib32, /opt/lib32. For programs compiled with the -64 compiler option, the rules are similar, but the following differences exist: * The LD_LIBRARY64_PATH is used if LD_LIBRARY_PATH is defined. * _RLD64_ROOT is used for the list of paths. * The default path directory list is /usr/lib64, /usr/lib64/internal, /lib64, /opt/lib64. See the rld(5) man page for more details. 10. What is Quickstart? Quickstart is an optimization. Using an so_locations file, ld(1) prerelocates each DSO as if it had been loaded (or linked, which is the term often used) by ld(1)) at the address in the so_locations file. If no errors occur at startup, all DSOs map to their Quickstart addresses, and rld(5) does not need to perform a relocation pass. When new software is installed with inst(1M) or swmgr(1M), rqsall(1) changes many DSO virtual addresses, attempting to ensure that all registered applications (written to /var/inst/.rqsfiles) can be Quickstarted. At the same time, rqsall(1) updates so_locations. If more than one DSO attempts to map to the same address, the IRIX kernel moves one of them to an unused address range, and rld(5) performs a relocation pass to fix the address references. If one or more of the DSOs linked against at static link time has changed by the time the program executes, rld(5) performs extra work to ensure that symbols have been resolved to their proper value. 11. What is the /usr/lib/so_locations file? After you build a DSO, a file called so_locations is placed in the directory with the DSO. This file is a registry of DSOs. It maintains the default, or Quickstart, addresses of a group of DSOs that are guaranteed to never have their default locations overlap with one another. It is generated and updated by ld(1) each time it builds a DSO. If you make substantial library changes between one build of the library and another, you should remove the so_locations file before rebuilding the library. You do this because the information derived from the older build and put in the so_locations files can make the new library build unsuccessful. rqsall(1) and rqs(1) can rearrange a.out files and DSOs to restore Quickstartability, so the so_locations file is less important than it was before rqs(1) existed. For information on address ranges, see the following files: /usr/lib/so_locations, /usr/lib32/so_locations, and /usr/lib64/so_locations. /usr/lib/so_locations applies to programs compiled with the -32 compiler option. /usr/lib32/so_locations applies to programs compiled with the -n32 compiler option. /usr/lib64/so_locations applies to programs compiled with the -64 compiler option. These files represent the default layout for the system DSOs in the respective ABIs. Those who build DSOs may find it interesting to consult these files in order to avoid collisions between their DSOs and system DSOs. You do not need to consult this file if you merely run programs that use DSOs. If you build DSOs, three ld(1) command options may be useful to you: -create_registry, -check_registry and -update_registry. * create_registry registry_file creates a registry file for the DSO being linked. This will always overwrite registry_file if it exists and create it if it does not exist. This option instructs the linker not to reference any registry file for layout specifications. * update_registry registry_file reads registry_file for any layout specifications for the DSO being linked. Update registry_file with layout information for the DSO being linked. If egistry_file doesn't exist, it creates it. * check_registry registry_file reads registry_file for any layout specifications for the DSO being linked. It is an error if registry_file doesn't exist. This option will not alter registry_file. The default behavior without the any of the above options is to neither read nor write a registry file. 12. What directives can be put into a so_locations file? The following directives control the placement of new DSOs: * $start_address=addr: Specifies the beginning address for DSOs. * so_name[:st={.text|.data|$range]} base_addr,pad_size:]: This directive consists of the following elements: Element Composition so_name Full path name (or trailing component) of a DSO. st String that identifies the start of the segment description. .text or .data or $range Specify either a segment type, text or data, or a range. Specifying a range limits the range of addresses that can be used. Use the $range form not the .text or .data forms whenever you write or modify an so_locations file. base_addr Address at which the segment starts. pad_size Padded size of the segment. When building a DSO with the -check_registry or -update_registry linker option, the following fatal errors may occur: * .text or .data are specified, but those segments overlap due to segment size. * .text or .data are specified along with $range, but the segments of that DSO cannot fit within the specified range. * $range is specified, but the segments of that DSO cannot fit within the specified range. A comment line can be inserted at any point a directive can be inserted. A comment is a line beginning with the number sign (#) character. 13. If I don't have a valid so_locations file, can I generate one from all the .so files in /usr/lib? Not easily. It is an error if the so_locations is missing. Every so_locations file is different because rqsall(1) reQuickstarts everything. If /var/inst/.rqsfiles is present, you could get a set of so_locations files from a similar system and rerun rqsall(1) as inst(1M) and swmgr(1M) do. If you do this, make a back-up copy of .rqsfiles before starting rqsall(1). NOTE: If anything destroys or results in the loss of .rqsfiles, the only way to recreate .rqsfiles is to reinstall everything on the system. Make a back-up copy of .rqsfiles. 14. How expensive is it, at runtime, NOT to use the -update_registry option? If you use rqsall(1) or rqs(1) to reQuickstart an application and its DSOs, then there need not be any cost. rqs(1) can make the DSOs Quickstartable regardless how the DSO addresses were determined. If you do not use rqs(1), then the lack of an updated registry can impose startup costs. It is very difficult to say how much a particular executable will suffer because it depends on which DSOs the program uses and whether they have been Quickstarted for the same address. When there is a conflict between two objects, one will be moved, which means that all addresses referring to names in that object need to be relocated. 15. How and when will Quickstart be used? The linker uses Quickstart unless there are unresolved symbols at static link time. Every executable and every DSO contains a list of objects that were examined at static link time when the object was made. This list also contains timestamps and checksums for each of the objects. Various levels of extra work are required if the timestamp or checksum changed in the library at runtime. 16. What about runtime loading under user control? The library allows you to dynamically load your own DSOs as needed. The individual library calls are as follows: * dlopen(3C), which opens a DSO. * dlsym(3C), which finds the value of a name defined in an object. * dlclose(3C), which closes a DSO. * dlerror(3C), which reports errors. * sgidladd(3C), which functions much like dlopen(3C), but it exposes all symbols to the rest of the program. * sgidlopen_version(3C), which functions much like dlopen(3C), but it allows specifying a specific required version of the DSO. Consult the individual man pages for details. 17. What benefits will I get from DSOs? Executables linked with DSOs are smaller because the DSOs are not part of the executable file image. Executables that use a DSO need not be relinked if a DSO is changed. After the updated DSO is installed, the executable picks it up automatically. DSOs allow application designers to make more machine-independent software. System-dependent routines can be given a uniform interface, and a DSO that implements that interface can be built for each different platform. Actual applications can be shipped to various platforms and run on them all. DSOs give applications the ability to change the binding of symbols at runtime and under user control. 18. What costs are associated with DSOs? A DSO incurs two costs, both against performance. The first is a start-up cost incurred while rld(5) maps in the various objects, performs symbol resolution, etc. This cost is usually small compared to the time it takes to contact the X server, for example. The second is the cost incurred when using position-independent code. A DSO's text must be compiled with the -KPIC option in effect in order for the object file to be put into a DSO without further modification. Because this option is in effect by default, it is not necessary to specifiy it. By default, PIC is slower by 5% to 15%. With full optimization, however, the speed reduction can be near zero. PIC code seems to be worst on very small-leaf routines that access global data. Routines written in assembly language for non-PIC use (for example, routines written before PIC was available for IRIX) need to be modified before the -KPIC option can be used. For more information on modifying your code, see the MIPSpro Assembly Language Programmer's Guide. 19. Must main programs that want to use DSOs use -KPIC for compilation? Yes. DSOs use -KPIC so that PIC code is generated. Main programs are not generally position-independent, but they must still use the DSO calling convention when calling a routine that is defined in a DSO. In particular, this means that a main program must have a Global Offset Table (GOT) and the code that is generated must use it. Modules that will become part of main programs and modules that become part of DSOs must be compiled with the -KPIC option in effect, which is enabled by default. 20. What options do I have when building a DSO? If you specify the -B dynamic option while linking a DSO, symbols in the DSO are resolved in a nondefault manner. In particular, the runtime linker first tries to resolve symbols referenced in the object to symbols defined in the object instead of looking for definitions in objects in the order specified on the link line. The effect is that all symbols defined and used in such objects are non-preemptable. Ordinarily, symbol definitions could be preempted by a definition in an earlier DSO. When -B symbolic is specified, however, this is not the case. For more information on the -B dynamic and -B symbolic options, see the ld(1) man page. 21. What difficulties may be associated with DSOs? Behind most unexpected behavior is the fact that linking semantics are fundamentally different, but only in a subtle way. Assume that a program links with three libraries, libA, libB, and libC, in that order. Further assume that both libA and libC define symbol x but don't use it. Further, assume that libB contains a reference to x. Archive linking (the old way) would resolve libB's reference to x to the definition in libC, whereas DSO linking resolves libB's reference to x to the definition in libA. This is true because with archive linking, when libA is examined, there is no outstanding reference to x. The definition of x is not extracted from the archive. Later, when libC is examined, there is a reference to x, so it is loaded. With DSOs, all the constituent object files have been joined into one object, so all symbol definitions are always present. The resolution rule is simple: take the definition in the object listed first. Thus, the definition in libA is used. Another unexpected occurrence is a runtime dangling reference. These occur when you build and link an application with no errors or warnings but later receive a message from rld(5) stating that your program has unresolvable symbols. The problem here is that if you build a DSO as part of your program, the linker typically does not generate messages about undefined symbols during a link of a DSO. This is because undefined symbols are expected during such a build and are perfectly acceptable. If the main program does not use a symbol, however, it is not flagged as undefined during static linking. You can use the -no_unresolved option to the ld(1) command to avoid such unexpected behavior. If a particular object in an archive file (libl.a, for example) has an external reference to a data symbol, and the data symbol is expected to be defined in the main program, the linker does not try to resolve that external reference unless the object file in question was actually referenced by the main program. If that archive is turned into a DSO, the external data reference must be resolved whenever ANY function in the DSO is used, even if no function in the object file in question is ever called and no use is made of the external data symbol in question. This can lead to a scenario in which a link that worked with the archives builds a program that is terminated by the runtime linker (rld(5)). Do not assume that you can convert libraries that contain external data symbols into DSOs. One remedy is to split the archive into several DSOs and place them on the liblist of a master DSO. By default, rld(5) does not try to resolve data symbols until the first call is made to a particular object. You can, however, inhibit the linker's attempt to resolve an offending external data symbol until a call is made to the object in which it is referenced. For example, suppose that ext_data.o is an object that contains an undefined external reference. It resides in archive libxyz.a. Here is how to isolate that external data reference: 1. Make ext_data.o into a DSO all its own: % ar x libxyz.a has_ext_data.o % ld -shared ext_data.o -o ext_data.so 2. Make libxyz.so, excluding ext_data.o from being included directly. Instead, put it in the liblist of libxyz.so: % ld -shared -all -exclude ext_data.o libxyz.a ext_data.so -o libxyz.so In addition to the previously mentioned caveats, applications should not call dlopen(3C), sgidladd(3C), dlclose(3C), sgidlopen_version(3C), or dlerror(3C) from within a signal handler. This means that calling from within a signal handler calling a function that results in a DSO being delay-loaded is also wrong. Ensure that functions called (directly or indirectly) from signal handlers are already loaded before a signal handler is set up. Very few functions are safe to call from within a signal handler (POSIX specifies a few), and the delay-load functions (dlopen(3C), and so on) are not among them. 22. What should I do about Global Offset Table (GOT) overflow? GOT overflow has occured if you receive messages from the linker saying GP-relative sections overflow by 0x??? bytes, GOT overflow, or GOT unreachable. To fix this situation, perform one of more of the following steps: * Break the large input file.o into two or more smaller files. * Use the -m option on the ld(1) command to obtian a link map. This map indicates large objects that you can recompile with -G0 or some other small -G value. Data objects affected by the -Gnum option are numeric literals, addreses (including those generated by the compiler), all C/C++ static veriables, and, if the -static option is in effect, all Fortran local variables. For more information on the -Gnum option, see your compiler command line. 23. How are multiple versions of DSOs supported? You can associate DSOs and executables with a version number. This is intended to support interface changes. A version string consists of 3 parts and a period (.), as follows. The first part is the string sgi. The second part is a decimal number, which is the major number. The third part is the period (.). The fourth part is a decimal number, which is the minor number. Hence the format: sgimajor.minor. For a DSO to be versioned as sgi1.0, add the -set_version sgi1.0 option to the compiler or loader command line to build the DSO (cc - shared, ld -shared, and so on). Whenever you make a compatible change, update the minor version number (the one after the period) and add the latest version string to colon-separated list of version strings. For example: -set_version sgi1.0:sgi1.1:sgi1.3. Whenever you make an incompatible change, update the major version number. For example, use -set_version sgi2.0. Change the file name of the old DSO by adding a period followed by the previous major number to the file name of the DSO. Do not change the soname of the object. No change to the file contents are necessary or desirable. Simply rename the file. 24. How does versioning work? Note that in this answer, items marked SGI ONLY do not apply to MIPS ABI binaries; they apply only to binaries generated on IRIX systems using a means other than the abicc(1) or abild(1) commands. Versioning is available for NON-ABI executables only. The ABI does not require objects to have versioning, nor does it require systems to recognize versioning. It allows objects to contain version strings, but it does not require systems to do anything with this information. NON-ABI compliant executables have the RHF_SGI_ONLY bit turned on in the .dynamic section. This flag is reported by the elfdump(1) command when elfdump -long -L is entered. Only executables with this flag turned on receive the versioning treatment described in this answer. RHF_SGI_ONLY is turned on by default. When an executable is linked against a DSO, the last entry of the DSO's version string is recorded in the executable as part of the liblist. This can be examined by using the -Dl option to the elfdump(1) command. When an executable is linked, you may specify the -require_minor or -ignore_minor options for each DSO linked against. If -require_minor is specified, a bit will be set in the flags field of the liblist entry for the DSO in question. The default is -ignore_minor. When an executable (ABI or RHF_SGI_ONLY) is run, rld(5) searches for the proper file name in its usual search routine. (SGI_ONLY) If a file with the correct name is found, the version string in the liblist is compared to the list of version strings in the DSO. If the LL_REQUIRE_MINOR bit is set in the liblist entry and there is an exact match between the version string in the depender and one of the strings in the version list of the dependee, then that library is used. If the LL_REQUIRE_MINOR bit is clear and if there is a match of major versions, then that library is used. (SGI_ONLY) If no proper match is found, a new soname is built by taking the soname found in the executable's liblist and the major number found in the version string that corresponds to that liblist entry. They are put together as soname.major. This is searched for as described previously. Version strings are matched as described previously. (SGI ONLY) If, for example, B.so has a liblist entry with a version list for A.so and an A.so is loaded that has no version, the DSO is considered a match. If B.so has a liblist entry with no version list for A.so, then the first A.so found is considered a match, no matter what version A.so is. File A.so with no version can be created, for example, if ld(1)'s -set_version option was not used or if an empty string was provided as an argument to the -set_version option. (SGI ONLY) A version string with a missing major number is an error. rld(5) behavior is not defined for such cases. 25. Why are the global objects in my C++ DSO not being initialized? Did you link your DSO using the CC(1) command instead of using ld(1) directly? See the C++ information in the LINKING AND BUILDING SHARED OBJECTS section of this man page. 26. Why are some libraries only available as a DSO whereas other libraries are available as both a DSO and an archive? The ABI specifies the DSOs that must be on every system. The converse of that is that no one can assume that any other .so is on an ABI- conforming system. Libraries explicitly called out in the MIPS ABI are considered part of the system interface. Such libraries are shipped only in DSO form. Libraries that are not specified in the MIPS ABI must also be supplied in archive form to generate MIPS ABI compliant binaries using these libraries. For example, the libraries libX11.so and libc.so.1 are explicitly called out in the MIPS ABI. This makes the DSO version of Xlib and libc a system interface. Other examples are libsocket.so and libdl.so, which are also only supplied as DSOs. Archive versions of libXt.a, libXm.a, libm.a, libmalloc.a, and others are supplied because shared library versions of these libraries are not specified in the MIPS ABI. Therefore, they are not guaranteed to exist on all ABI conforming systems. 27. What are symbol binding problems? Symbol binding, also known as name resolution, is the process of determining the data or function to use for an external name reference. If you are developing executable files or DSOs, you need to address this topic, but if you are simply running predeveloped applications, you can assume that symbol binding has been resolved for you. All symbols for which there is only one definition are simple. The one and only definition is used. For global references, the general approach is to examine the set of DSOs on the list that rld(5) builds at run time and to use the first definition found. If there is a weak definition, then the first of those is taken if and only if there is no strong definition. If there is a strong definition, which might better be called a typical definition, the strong definition is used. In C and C++, #pragma weak is used to create a weak reference or definition. Typically, DSOs are added to rld(5)'s list in breadth-first order, generating the transitive closure of all DSOs on the executable liblist (as shown by the elfdump -Dl command). If the application calls sgidladd(3C) or has any delay-loaded DSOs, those DSOs are added to the end of rld(5)'s DSO list when they are actually loaded. If the loading is different with different data (that is, if the application calls functions that cause sgidladd(3C) or -delay-load operations in a different order at different times), the list of DSOs may be not have the same ordering. If there are multiple definitions, the first definition on rld(5)'s list of DSOs for the executable is be used. If all definitions are weak definitions, the resolution proceeds conceptually identically to the strong case. If there is at least one strong and one weak definition of a symbol things, resolution proceeds as follows: 1. If a strong definition is in a DSO loaded into memory, it supersedes any weak definitions loaded. 2. If a weak definition is loaded and no strong definition is loaded, the weak definition is used. If an sgidladd(3C) or -delay-load operation causes a strong definition to be loaded, the symbol may or may not be rebound to the new strong definition. To avoid this unpredictable behavior, you may need to relink or rewrite your program with the following aspects of symbol resolution in mind: * You may obtain unexpected results if a strong symbol definition is loaded after a weak definition. In these cases, some calls may refer to one version and some to another, possibly within the same execution. * The order in which your executable calls functions or performs sgidladd(3C) or delay-load operations can affect symbol resolution. * Symbols that remain undefined after linking can affect symbol resolution. 3. Weak symbols were defined to allow ISO/ANSI C program to, for example, implement their own write() operation while not affecting the operation of fwrite() and other ISO C calls and while still allowing another application to choose to call the libc write() routine. It was expected that the strong symbol would be visible at the same time as the weak symbol. If both are visible at the same time they work predictably. But, as explained previously, if the weak symbol is visible when the strong symbol is not, the program can exhibit unexpected and unpredictable behavior. 28. Are there negative aspects to using dlclose(3C)? Because of symbol definition order rules, do not perform a dlclose(3C) on a DSO that was initially opened by a call to sgidladd(3C). For more information on this, see NAMESPACE ISSUES on the dlopen(3C) man page. SEE ALSO cc(1), CC(1), elfdump(1), f90(1), f77(1), ld(1) exec(2), nsproc(2), sigprocmask(2), sproc(2), sprocsp(2) dlclose(3C), dlerror(3C), dlopen(3C), dlsym(3C), malloc(3C), malloc(3F), pthread_mutex_lock(3P), setlocale(3C), sgidladd(3C), sgidlopen_version(3C), sgigetdsoversion(3C) capabilities(4), capability(4) abi(5), gp_overflow(5), rld(5) MIPSpro N32/64 Compiling and Performance Tuning Guide MIPSpro 64-Bit Porting and Transition Guide MIPSpro Assembly Language Programmer's Guide