Name
mkshlib - create a shared library
Syntax
mkshlib -s specfil -t target [-h host] [-n] [-L dir ...]
[-q]
Description
mkshlib builds both the host and target shared libraries. A
shared library is similar in function to a normal, non-
shared library, except that programs that link with a shared
library will share the library code during execution,
whereas programs that link with a non-shared library will
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(F)). A
host shared library can be treated exactly like a non-shared
library and should be included on cc(CP) command lines in
the usual way (see cc(CP)). Further, all operations that
can be performed on an archive can also be performed 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 will be brought into
memory during execution of a program using the shared
library, and subsequent processes that use the shared
library will share the copy of code already in memory. The
text of the target is always shared, but each process will
get 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
manner as prefixes to the cc(CP) command, and invoked tools
are given the prefix, where appropriate. For example,
i386mkshlib will invoke i386ld.
The following command line options are recognized by
mkshlib:
-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. It is assumed
that this file will be 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 will not be 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 will not be
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, at
which 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 may 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
can be thought of as ``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.
Note that if a host shared library is specified
using #objects noload, any cc command that links
to the shared library being built will need 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 may
be given (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,
#hide linker *
#export linker
one
two
causes all symbols except one, two, and those
used in #branch and #init entries to be tagged
as static.
#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 the
line beginning with ## is ignored.
Files
TEMPDIR/* temporary files
TEMPDIR is usually /usr/tmp but can be
redefined by setting the environment variable
TMPDIR [see tempnam() in tmpnam(S)].
LIBDIR usually /lib
LLIBDIR usually /usr/lib
See Also
ar(CP), as(CP), cc(CP), chkshlib(CP), ld(CP), lorder(CP),
tsort(CP), a.out(F), ar(F)
Notes
The -n option cannot be used with the #objects noload
directive.
If mkshlib is asked to create a host library and a host of
that name already exists, mkshlib will update the host using
ar -ru. This means that you should 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.
(printed 6/18/89)