mkshlib(1) CLIX mkshlib(1)
NAME
mkshlib - Creates a shared library
SYNOPSIS
mkshlib -s specfil -t target [-h host] [-c cpuid] [-n] [-L dir ... ] [-q]
[-v]
FLAGS
-s specfil Specifies the shared library specification file, specfil.
This file contains the information necessary to build a
shared library.
-t target Specifies the output filename of the target shared library.
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 flag is used, then a
new target shared library will not be generated.
-h host Specifies the output filename of the host shared library. If
this flag is not given, the host shared library will not be
created.
-c cpuid Specifies the CPU for which the shared library is targeted.
The -Atarg=cpuid assembler flag is added when the assembler
is invoked.
-n Does not generate a new target shared library. This flag is
useful when creating only a new host shared library. The -t
flag must still be supplied since a version of the target
shared library is needed to build the host shared library.
-L dir ... Changes 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 flag can be specified multiple times on the command line.
The directories specified with the -L flags are searched in
the order they appear on the command line before the default
directories.
-q Quiets warning messages. This flag is useful when warning
messages are expected but not desired.
-v Displays the command line arguments of the programs invoked
for the user.
DESCRIPTION
The mkshlib command builds a target shared library and optionally, a host
2/94 - Intergraph Corporation 1
mkshlib(1) CLIX mkshlib(1)
shared library. A shared library is similar in function to a normal,
nonshared library, except programs that link with a shared library will
share the library code with other programs during execution, whereas
programs that link with a nonshared library have a separate copy of the
library stored in their executable files.
The host shared library is an archive used to link-edit user programs with
the shared library (see ar(4)). A host shared library can be treated
exactly as a nonshared library and can be included on compiler command
lines in the usual way. 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 bound to a process's
address space during execution of a program using the shared library. The
target shared library contains the code for all 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 receive its
own copy of the data.
The mkshlib command invokes other tools such as the archiver, ar, the
assembler, as, and the link editor, ld. Tools are invoked through the use
of execvp (see exec(2)), which searches directories in the user's PATH.
Also, prefixes to mkshlib are parsed in the same manner as prefixes to the
cc command, and invoked tools receive the prefix where appropriate. For
example, pfxmkshlib will invoke pfxld.
The shared library specification file describes the contents of the shared
library. This specification file contains all 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 multiline 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. An #address directive must be given exactly
once for the .text section and once for the .data section.
#target pathname
Specifies the absolute pathname, pathname, at which the target
shared library will be installed on the target machine. The
operating system uses this pathname 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
2 Intergraph Corporation - 2/94
mkshlib(1) CLIX mkshlib(1)
Specifies the start of the branch table specifications. The lines
following this directive are interpreted as 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. The position may be a single integer or a range of integers
with the form position1-position2. Each position must be greater
than or equal to one; the same position cannot 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,
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 interpreted as the list of
input object files in the order they are to be loaded in the
target. The list consists of each pathname 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 the lorder and tsort commands.
This directive must be specified exactly once per shared library
specification file.
#objects noload
This directive 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,
a nonshared version of a symbol found before a shared version of
the symbol is an error.
Each name given is assumed to be a pathname 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 flag can be used on the command line to specify other
2/94 - Intergraph Corporation 3
mkshlib(1) CLIX mkshlib(1)
directories to search for these archives.
Note that if a host shared library is specified using #objects
noload, any compiler command that links to the shared library being
built will need to specify that host also.
#hide linker [*]
This directive changes normally external symbols to static symbols,
local to the library being created. A regular expression may be
given (see sh(1)). In this 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 asterisk (*) is equivalent to
#hide linker
*
and coverts all external symbols to static symbols.
All symbols specified in #init and #branch directives are assumed
to be external symbols and cannot be changed to 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
tags all symbols except one, two, and those used in #branch and
#init entries as static.
#init object
Specifies that the object file, object, requires initialization
code. The lines following this directive are interpreted as
initialization specification lines.
Initialization specification lines have the following format:
ptr <white space> import
The 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 has the form:
ptr = &import;
4 Intergraph Corporation - 2/94
mkshlib(1) CLIX mkshlib(1)
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.
EXAMPLES
This example generates the target shared library foo_s and the host shared
library foo_s.a from the specification file foo.spec.
mkshlib -s foo.spec -t foo_s -h foo_s.a
FILES
$TMPDIR/* Temporary files.
The $TMPDIR is usually /usr/tmp but can be redefined by
setting the environment variable TMPDIR (see the tempnam()
function in tmpnam(3)).
$LIBDIR Usually /lib.
$LLIBDIR Usually /usr/lib.
CAUTIONS
The -n flag cannot be used with the #objects noload directive.
If mkshlib is asked to create a host library and a host of that name
exists, mkshlib will update the host using the ar -ru command. This means
that the host should always be removed before rebuilding when 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 return successfully, but it might not work
when it is used.
EXIT VALUES
The exit values are not valid.
RELATED INFORMATION
Commands: as(1), ld(1), ar(1), chkshlib(1), lorder(1), tsort(1)
2/94 - Intergraph Corporation 5
mkshlib(1) CLIX mkshlib(1)
Files: ar(4)
AT&T UNIX System V Programmer's Guide.
6 Intergraph Corporation - 2/94