MKSHLIB(1) INTERACTIVE UNIX System MKSHLIB(1)
NAME
mkshlib - create a shared library
SYNOPSIS
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(4)]. A
host shared library can be treated exactly like a non-shared
library and should be included on cc(1) command lines in the
usual way [see cc(1)]. 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(1), the assembler, as(1), and the link editor,
ld(1). Tools are invoked through the use of execvp [see
exec(2)], which searches directories in the user's PATH.
Also, prefixes to mkshlib are passed in the same manner as
prefixes to the cc(1) 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
Rev. C Software Development Set Page 1
MKSHLIB(1) INTERACTIVE UNIX System MKSHLIB(1)
necessary to build a shared library. Its con-
tents include the branch table specifications
for the target, the path name in which the tar-
get 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 specifica-
tion 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 specifica-
tion file are given by the directives listed below.
All directives that can be followed by multi-line specifica-
tions are valid until the next directive or the end of the
file.
#address sectname address
Specifies the start address, address, of section
Rev. C Software Development Set Page 2
MKSHLIB(1) INTERACTIVE UNIX System MKSHLIB(1)
sectname for the target. This directive typi-
cally 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. See the table
in the section "The Building Process" in the
"Shared Libraries" chapter of the UNIX System V
Programmer's Guide for standard addresses.
#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 speci-
fied exactly once per specification file.
#branch
Specifies the start of the branch table specifi-
cations. The lines following this directive are
taken to be branch table specification lines.
Branch table specification lines have the fol-
lowing 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.
Rev. C Software Development Set Page 3
MKSHLIB(1) INTERACTIVE UNIX System MKSHLIB(1)
#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(1) and
tsort(1).
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 unde-
fined 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 LLIB-
DIR. 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(1), find(1)], 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
Rev. C Software Development Set Page 4
MKSHLIB(1) INTERACTIVE UNIX System MKSHLIB(1)
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 specif-
ication lines.
Initialization specification lines have the fol-
lowing format:
ptr <white space> import
ptr is a pointer to the associated imported sym-
bol, import, and must be defined in the current
specified object file, object. The initializa-
tion 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(3S)].
Rev. C Software Development Set Page 5
MKSHLIB(1) INTERACTIVE UNIX System MKSHLIB(1)
LIBDIR usually /lib
LLIBDIR usually /usr/lib
SEE ALSO
ar(1), as(1), cc(1), chkshlib(1), ld(1), lorder(1),
tsort(1), a.out(4), ar(4).
"Shared Libraries" chapter in the UNIX System V Programmer's
Guide.
CAVEATS
The -n option cannot be used with the #objects noload direc-
tive.
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 out-
side user space, the library build may look successful, but
if you try to use it, it might not work.
Rev. C Software Development Set Page 6