mkshlib(CP)

Syntax

Description

A shared library is similar in function to a normal, non-shared library, except that programs that link with a shared library share the library code during execution, whereas programs that link with a non-shared library get their own copy of each library routine used.

The host shared library is an archive that is used to link-edit user programs with the shared library (see ar(FP)). A host shared library can be treated exactly like a non-shared library and should be included on cc command lines in the usual way (see cc(CP)). Further, all operations that can be done on an archive can also be done on the host shared library.

The target shared library is an executable module that is bound into the user's address space during execution of a program using the shared library. The target shared library contains the code for all the routines in the library and must be fully resolved. The target is brought into memory during execution of a program using the shared library, and subsequent processes that use the shared library share the copy of code already in memory. The text of the target is always shared, but each process gets its own copy of the data.

The user interface to mkshlib consists of command line options and a shared library specification file. The shared library specification file describes the contents of the shared library.

The mkshlib command invokes other tools such as the archiver, ar(CP), the assembler, as(CP), and the link editor, ld(CP). Tools are invoked through the use of execvp( ) (see exec(S)), which searches directories in the user's PATH. Also, prefixes to mkshlib are passed in the same way as prefixes to the cc(CP) command, and invoked tools are given the prefix, where appropriate. For example, i386mkshlib invokes i386ld.

mkshlib recognizes the following command line options:

-s specfil

Specifies the shared library specification file, specfil. This file contains the information necessary to build a shared library. Its contents include the branch table specifications for the target, the path name in which the target should be installed, the start addresses of text and data for the target, the initialization specifications for the host, and the list of object files to be included in the shared library (see details below).

-t target

Specifies the output filename of the target shared library being created. We assume that this file is installed on the target machine at the location given in the specification file (see the #target directive below). If the -n option is used, then a new target shared library is not generated.

-h host

Specifies the output filename of the host shared library being created. If this option is not given, then the host shared library is not produced.

-n

Do not generate a new target shared library. This option is useful when producing only a new host shared library. The -t option must still be supplied since a version of the target shared library is needed to build the host shared library.

-L dir ...

Change the algorithm of searching for the host shared libraries specified with the #objects noload directive to look in dir before looking in the default directories. The -L option can be specified multiple times on the command line in which case the directories given with the -L options are searched in the order given on the command line before the default directories.

-q

Quiet warning messages. This option is useful when warning messages are expected but not desired.

The shared library specification file contains all the information necessary to build both the host and target shared libraries. The contents and format of the specification file are given by the directives listed below.

All directives that can be followed by multi-line specifications are valid until the next directive or the end of the file.

#address sectname address

Specifies the start address, address, of section sectname for the target. This directive typically is used to specify the start addresses of the .text and .data sections. One #address per section name is valid. A #address directive must be given exactly once for the .text section and once for the .data section.

#target pathname

Specifies the absolute path name, pathname, where the target shared library will be installed on the target machine. The operating system uses this path name to locate the shared library when executing a.out files that use this shared library. This directive must be specified exactly once per specification file.

#branch

Specifies the start of the branch table specifications. The lines following this directive are taken to be branch table specification lines.

Branch table specification lines have the following format:

funcname <white space> position

where funcname is the name of the symbol given a branch table entry and position specifies the position of funcname's branch table entry. position can be a single integer or a range of integers of the form position1-position2. Each position must be greater than or equal to one, the same position can not be specified more than once, and every position, from one to the highest given position, must be accounted for.

If a symbol is given more than one branch table entry by associating a range of positions with the symbol or by specifying the same symbol on more than one branch table specification line, then the symbol is defined to have the address of the highest associated branch table entry. All other branch table entries for the symbol are ``empty'' slots and can be replaced by new entries in future versions of the shared library. Only functions should be given branch table entries, and those functions must be external symbols.

This directive must be specified exactly once per shared library specification file.

#objects

The lines following this directive are taken to be the list of input object files in the order they are to be loaded into the target. The list simply consists of each path name followed by a newline character. This list is also used to determine the input object files for the host shared library, but the order for the host is given by running the list through lorder(CP) and tsort(CP).

This directive must be specified exactly once per shared library specification file.

#objects noload

The #objects noload is followed by a list of host shared libraries. These libraries are searched in the order listed to resolve undefined symbols from the library being built. During the search it is considered an error if a non-shared version of a symbol is found before a shared version of the symbol.

Each name given is assumed to be a path name to a host or an argument of the form -lX, where libX.a is the name of a file in LIBDIR or LLIBDIR. This behavior is identical to that of ld, and the -L option can be used on the command line to specify other directories in which to locate these archives.

If a host shared library is specified using #objects noload, any cc command that links to the shared library being built needs to specify that host also.

#hide linker [*]

This directive changes symbols that are normally external into static symbols, local to the library being created. A regular expression can be given (see sh(C), find(C)), in which case all external symbols matching the regular expression are hidden; the #export directive (see below) can be used to counter this effect for specified symbols.

The optional * is equivalent to the directive

   	#hide linker
   	    *

and causes all external symbols to be made into static symbols.

All symbols specified in #init and #branch directives are assumed to be external symbols, and cannot be changed into static symbols using the #hide directive.

#export linker [*]

Symbols given in the #export directive are external symbols (global among files) that, because of a regular expression in a #hide directive, would otherwise have been made static. For example, the following causes all symbols except one, two, and those used in #branch and #init entries to be tagged as static.

   	#hide linker *
   	#export linker
   	   one
   	   two

#init object

Specifies that the object file, object, requires initialization code. The lines following this directive are taken to be initialization specification lines.

Initialization specification lines have the following format:

ptr  <white space> import

ptr is a pointer to the associated imported symbol, import, and must be defined in the current specified object file, object. The initialization code generated for each such line is of the form:

ptr = &import ;

All initializations for a particular object file must be given once and multiple specifications of the same object file are not allowed.

#ident string

Specifies a string, string, to be included in the .comment section of the target shared library.

##

Specifies a comment. All information on a line beginning with ## is ignored.

Exit values

Warning

If mkshlib is asked to create a host library and a host of that name already exists, mkshlib updates the host using ar -ru. Therefore, always remove the host before rebuilding whenever an object file previously included in the library is removed or renamed.

If the address specified with the #address directive is outside user space, the library build may look successful, but if you try to use it, it might not work.

Files

TEMPDIR/*

Temporary files. TEMPDIR is usually /usr/tmp but can be re-defined by setting the environment variable TMPDIR (see tempnam(S) in tmpnam(S)).

LIBDIR

Usually /lib.

LLIBDIR

Usually /usr/lib.

See also

``Shared libraries'' in the Programming Tools Guide

Standards conformance