MKSHLIB
Section: User Commands (1)
Updated: April 2 (Release 4.0)
Index
Return to Main Contents
NAME
mkshlib - create a shared library
SYNOPSIS
mkshlib -s
specfile
-t
target
-h
host
[
options
] ...
DESCRIPTION
The
mkshlib
command 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. Programs that link with a non-shared library will get
their own copies 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(5)
). A host shared library can
be treated exactly like a non-shared library and should be included on
compiler (see
cc(1))
command lines in the usual way. Furthermore,
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 attached to the
user's process 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
mkshilib
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 assembler,
as(1),
and the link editor,
ld(1).
These tools
are invoked through the use of
execvp(3),
which searches directories
in the user's PATH.
FAT FILE SUPPORT
Mkshlib,
like the link editor, accepts ``fat'' files on input but always creates a
``thin'' host and target shared libraries for only one architecture. Because of this
mkshlib(1)
only allows one architecture flag,
-arch arch_type
specified at a time. If no
-arch arch_type
is specified and the first object file listed in the
#object
directive is a
``thin'' (standard Mach-O) file then the output shared library architecture
will be that of the first object file. If the first object is a ``fat'' file
then an
-arch arch_type
must be specified. The command
lipo(1)
must be run explicitly on the results of multiple
mkshlib(1)
executions.
This is unlike the creation of fat executables where the compiler driver
cc(1)
directly runs
lipo(1)
on multiple executions of
ld(1)
to create ``fat'' shared libraries
The following command line arguments are recognized by
mkshlib:
- -arch arch_type
-
Specifies the architecture,
arch_type,
selected from the "fat" input files for the output target and host
shared libraries. This option must be used when
the first object file listed in the #object directive is a fat file.
Only one
-arch arch_type
can be specified. See
arch(3)
for the currently know
arch_types).
- -s specfile
-
Specifies the shared library specification file,
specfile.
This file contains the information necessary to build a shared library. Its
contents include the branch table specifications for the target,
the pathname 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 name,
target,
of the target shared library
produced on the host machine. When
target
is moved to the target machine, it
should be installed at the location given in
the specification file (see the
#target
directive below).
- -h host
-
Specifies the name of the host shared library,
host.
- -v
-
Sets the verbose option. This option prints the command lines it executes.
- -d
-
Sets the debugging option. This option creates a directory ./hostdir and
leaves all the temporary files it creates in there and does not remove them.
- -f
-
Prevents creation of the host library.
- -minor_version num
-
Set the minor version number of the library. This or the directive
#minor_version num
can be used (see below).
- -image_version num
-
Set the minor version number of the target shared library to the
num
specified regardless of the value of the minor version.
- -sectcreate segname sectname file
-
Creates the section named,
sectname
in the segment named
segname
from the contents of the file,
file.
This section name cannot be the same as a section name in an input object file
in the same segment. The previous option
-segcreate
will continue to be recognized. This option is passed to the link editor.
- -segaddr name addr
-
Specifies the starting address of the segment named
name
to be
addr
where
addr
is a hexadecimal number and must be a multiple of the segment alignment.
- -segprot name max init
-
Specifies the maximum and initial virtual memory protection of the segment
named
name,
to be
max
and
init,
respectively. The values for
max
and
init
are any combination of the characters `r' (for read), `w' (for write),
`x' (for execute) and '-' (no access). This option is passed to the link
editor.
- -seglinkedit
-
Passes this flag to the link editor so that the __SEGLINKEDIT segment is
produced in the target shared library.
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 following directives:
- #address segname address
-
Specifies the start address,
address,
of the segment
segname
for the target. Use this directive to specify the start addresses of
the __TEXT and __DATA segments. Since the headers are part of the
text segment of a target shared library they are put on their own page.
The real text starts on the next page from where the text segment is specified
with this directive.
- #target pathname
-
Specifies the absolute pathname,
pathname,
of the target shared library on the target machine. This pathname is copied to
a.out
files and is the location where the operating system will look for
the shared library when executing a file that uses it.
- #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 [old_name <old_funcname>]
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 zero, the same position cannot be specified
more than once, and every position from one to the highest
given position must be accounted for. The special
funcname
.empty_slot
allocates branch tables slot(s) but put no function in them. These branch
table slots have an instruction in them that causes an exception. For the m68k
architecture the instruction is a ``trapl #0xfeadface'', for the m88k
architecture the instruction is an ``illop1'', for the m98k architecture the
instruction is a ``.long 0'', and for the i386 architecture the
instruction is a ``hlt'' instruction.
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.
When a
funcname
changes names from the previous version but otherwise remains compatible, the
branch table slot specification may optionally contain:
old_name old_funcname
where
old_funcname
was the old name. The program
cmpshlib(1)
uses this information when it checks branch table slots for compatibility.
cmpshlib(1)
would first check for
funcname
matching and then for
old_funcname
matching to see if the branch table slot is compatible.
Finally, only functions should be given branch table entries, and
those functions must be external.
This directive can be specified only once per shared library specification file.
- #objects
-
Specifies the names of the object files constituting the
target shared library. 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 file name followed by white space. This list is also used to
determine the input object files for the host shared library.
This directive can be specified only once per shared library
specification file.
- #filelist listfile [dirname]
-
This is an alternate way of specifing the names of the object files constituting
the target shared library. The
listfile
contains names of object files one to a line separated by newlines (all other
white space is considers part of the object file name). Optionally, the
directory name,
dirname,
is prepended to each object file name (with an added '/' if
dirname
does not end in a '/').
If the object file name in the listfile has previously been specified
in the specification file, it is ignored.
This directive can be specified more than once but only when the
#objects
directive is in effect.
- #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:
pimport <white space> import
pimport
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 can be thought of an
assignment statement of the form:
pimport = &import;
where
pimport
is the absolute address of
import.
The
import
may no longer be any legal assembly language expression with no white space (for
example _foo+4 is no longer legal after the 1.0 release).
- #minor_version num
-
Specifies the decimal number,
num,
as the minor version of the library.
This directive (or the command line option
-minor_version
) must be specified and
num
must be greater than zero. The operating system only allows executables to
execute with minor versions that are equal or less than the shared library
on the system.
- #private_externs
-
Specifies a list of external symbols in the library that are not to be included
in the host library. The lines following this directive are taken to be the
symbol names. This prevents the user of a library from using these symbols.
- #nobranch_text
-
Specifies a list of external text symbols in the library that are not symbol
names of routines but rather
const
data.
This prevents
mkshlib
from printing a warning, complaining that there are no
branch table entries for these text symbols.
- #undefineds
-
Specifies a list of symbols in the library that are expected to be undefined.
Other symbols that are undefined will cause an error message and the library
will not be built.
- #alias
-
Specifies a list of pairs of symbols to ``alias'' to each other using the
ld(1)
-idefinition:indirect
option, automatically causing
definition
to be a private extern.
Each of the following lines contains a pair of symbol names on the
same line separated by white space. The first symbol name on the line is the
definition
symbol name and the second is the
indirect
symbol name the symbol will become after it is link edited.
- ##
-
Specifies a comment. All information on a line following
this directive is ignored.
All directives that may be followed by multi-line specifications are
valid until the next directive or the end of the file.
FILES
mkshlib_* temporary files
SEE ALSO
ar(1), as(1), cc(1), ld(1), Mach-O(5), ar(5), ranlib(1), otool(1), arch(3)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- FAT FILE SUPPORT
-
- FILES
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 04:27:07 GMT, April 24, 2025