<tt>[-L directory] [-l library]</tt>

<tt>[-L directory] [-l library] [-R directory]</tt>

The system conceptually consists of a compiler and link editor.

The system conceptually consists of a compilation phase, encompassing Translation Phases 1 through 7 of the ISO C standard, and a linkage phase, for handling Phase 8 of the ISO C standard and extensions described here. In addition, the compilation phase can be split into a separate preprocessing operation, handling Translation Phases 1 through 4, and a processing operation, handling Phases 5 though 7. Whether a single utility or multiple utilities for handling phases separately is provided by an implementation is left unspecified.

The input files referenced by pathname operands and -l option-arguments shall be compiled and linked to produce an executable file. (It is unspecified whether the linking occurs entirely within the operation of c99; some implementations may produce objects that are not fully resolved until the file is executed.)

The input files referenced by pathname operands and -l option-arguments shall be compiled and linked to produce an executable file or, if the -G option is specified, a shared library file. It is unspecified whether the linking of an executable file occurs entirely within the operation of c99; when a pathname operand or -l option-argument names a shared library, an executable object may be produced that is not fully resolved until the file is executed.

If there are no options that prevent link editing (such as -c or -E), and all input files compile and link without error, the resulting executable file shall be written according to the -o outfile option (if present) or to the file a.out.

The executable file shall be created ...

If there are no options that prevent link editing (such as -c or -E), and all input files compile and link without error, the resulting executable file or shared library file shall be written according to the -o outfile option, if present. If -o outfile is not specified, a resulting executable file shall be written to the file a.out; if the file to be written is a shared library file, the behavior is unspecified.

Executable files shall be created ...

The order of specifying the -L and -l options, ...

The order of specifying the -L, -l and -R options, ...

-B mode

If mode is "dynamic", produce a dynamically linked executable file. If the -B option is present with -c, -E or -G, the result is unspecified.

-G

Create a shared library or create object files suitable for inclusion in such a shared library. Compilations shall be performed in a manner suitable for the creation of shared libraries (for example, by producing position-independent code).

If -c is also specified, create object files suitable for inclusion in a shared library.

If -c is not specified, create a shared library. In this case the application shall ensure that the file named by the -o outfile option-argument includes an element named "so" or an implementation-defined element denoting a shared library, where elements in the last component of outfile are separated by <period> characters, for example libx.so.1; if no -o option is included in the options or the file named by the -o outfile option does not contain an element named "so" or an implementation-defined element denoting a shared library, the result is unspecified. If a pathname operand or -l option-argument names a shared library and that shared library defines an object used by the library being created, it shall become a dependency of the created shared library.

If the -G option is present with -B or -E, the result is unspecified.

-R directory

If the object file format supports it, specify a directory to be searched for shared libraries when an executable file or shared library being created by c99 is subsequently executed, or loaded using dlopen(). If directory contains any <colon> or <dollar-sign> characters, the behavior is unspecified. If an implementation provides a means for setting a default load time search location or locations, the -R option shall take precedence.

The directory named by directory shall not be searched by a process performing dynamic loading if either of the following are true:

• the real and effective user IDs of that process are different and the directory has write permission for a user ID outside the set of the effective user ID of that process and any implementation-specific user IDs used for directories containing system libraries


• the real and effective group IDs of that process are different and the directory has write permission for group IDs other than the effective group ID of that process.

Directories named in -R options shall be searched in the order specified, before the default system library locations are searched.

If a directory specified by a -R option contains files with names starting with any of the strings "libc.", "libl.", "libpthread.", "libm.", "librt.", [OB]"libtrace.",[/OB] "libxnet.", or "liby.", the result is unspecified.

If the -R option is present with -c or -E, the result is unspecified.

Search the library named liblibrary.a. A library shall be searched when its name is encountered, so the placement of a -l option is significant. Several standard libraries can be specified in this manner, as described in the EXTENDED DESCRIPTION section. Implementations may recognize implementation-defined suffixes other than .a as denoting libraries.

Search for the library named liblibrary.a or liblibrary.so. When searching for a library, the linker shall look at each directory specified by -L options that appear on the command line before this -l option, in the order given, and then the system default libraries. If liblibrary.a and liblibrary.so both exist in a directory, c99 shall use liblibrary.so if either -B dynamic or -G is specified. Once a library has been found (shared or static) in a directory, later directories in the list shall not be considered. A library shall be searched when its name is encountered, so the placement of a -l option is significant. Several standard libraries can be specified in this manner, as described in the EXTENDED DESCRIPTION section. Implementations may recognize implementation-defined suffixes other than .a and .so as denoting libraries.

Use the pathname outfile, instead of the default a.out, for the executable file produced. If the -o option is present with -c or -E, the result is unspecified.

Name the output file to be produced. If the -o option is present with -c or -E, the result is unspecified.

When creating an executable file, use the pathname outfile, instead of the default a.out, for the executable file produced.

When creating a shared library, use the pathname outfile as the name of the shared library. If no -o outfile option is specified when creating a shared library, the result is unspecified.

Multiple instances of the -D, -I, -L, -l, and -U options can be specified.

Multiple instances of the -D, -I, -L, -l, -R, and -U options can be specified.

Each input file shall be one of the following: a text file containing a C-language source program, a text file containing the output of c99 -E, an object file in the format produced by c99 -c, or a library of object files, in the format produced by archiving zero or more object files, using ar. Implementations may supply additional utilities that produce files in these formats. Additional input file formats are implementation-defined.

Each input file shall be one of the following:

• A text file containing a C-language source program or the output from c99 -E


• An object file in the format produced by c99 -c


• A library of object files in the format produced by archiving zero or more object files using ar


• A shared library in the format produced by c99 -G

Implementations may supply additional utilities that produce files in these formats. Additional input file formats are implementation-defined.

A library of object files typically produced by the ar utility, and passed directly to the link editor. Implementations may recognize implementation-defined suffixes other than .a as denoting object file libraries.

A library of static object files typically produced by the ar utility, and referenced during the link-edit phase. Implementations may recognize implementation-defined suffixes other than .a as denoting static object file libraries.

A library of shared object files typically produced by the c99 utility with the -G option, and referenced during the link-edit phase. Implementations may recognize implementation-defined suffixes other than .so as denoting shared object file libraries.

It is unspecified whether the libraries libc.a, libl.a, libm.a, libpthread.a, librt.a, [OB]libtrace.a,[/OB] libxnet.a, or liby.a exist as regular files. The implementation may accept as -l option-arguments names of objects that do not exist as regular files.

The libraries c, l, m, pthread, rt, [OB]trace,[/OB] xnet, and y shall be found as shared libraries when specified as the option-argument to the -l option and may also be found as static libraries but, except for the shared library version of the c library, need not exist as regular files. The implementation may accept as -l option-arguments names of additional implementation-defined libraries that do not exist as regular files.

5. The following example shows how to create a shared library that does not depend on any other shared library:

c99 -G -c foo.c bar.c
c99 -G -o foobar.so foo.o bar.o

6. The following example shows how to create a dynamic executable that loads application specific shared libraries by searching a specified list of directories when it is executed:

c99 -G -c foo.c
c99 -G -o /path/to/dir1/foo.so foo.o
c99 -G -c bar.c
c99 -G -o /path/to/dir2/bar.so bar.o 
c99 -B dynamic -L /path/to/dir1 -L /path/to/dir2 -R /path/to/dir1 \
    -R /path/to/dir2 -o foobar foobar.c -l foo -l bar

The shared library version of the c library is required to exist as a regular file because the dynamic linker needs to be able to load at least one library at execution time. Other standard shared libraries need not exist in their own right if the interfaces the standard requires them to provide exist in the c library; all that is required is that they are "found" when specified as -l option-arguments. Static versions of the standard libraries need not exist as regular files, even if they are found as static libraries when specified as -l option-arguments.

When the -R option is not included when an executable file or shared library is being created, some implementations use the environment variables LD_RUN_PATH and LD_LIBRARY_PATH to determine the directories to be searched for shared libraries.

Some implementations permit placeholders preceded by a <dollar-sign> character ('$'), such as $ORIGIN, in the -R directory option-argument to be evaluated at load time. Some implementations accept a colon separated list of directories for the path to search for shared libraries, with the same effect as specifying the -R option multiple times. However, these features are not universal.

The name of a shared library usually contains an element named "so". Other implementation-defined elements are allowed for backwards compatibility with historical systems, and so that tools can be developed on conforming systems to create libraries for multiple environments. For example, Microsoft systems use the filename extension ".dll" (and do not allow following text) to denote a shared library. The standard allows additional characters to be used in the name of a library following an "so" element to permit shared library versioning information to be at the end of the library filename rather than requiring that any such strings appear before the final element of the library name.

The decision to standardize on "so" as a required element in a shared library name was intentional, as the alternative would have been standardizing things such as a new make macro $(SHLIB_EXT) that would otherwise be needed to write a portable makefile that can compile shared libraries despite not having a standardized element name.

If a combination of direct and indirect dependencies of a shared library would require different versions of another shared library, options that are not specified by the standard (such as -B direct) will probably need to be used when linking that shared library, so that at runtime the intended versions are found.