MKSHLIB

NAME

SYNOPSIS

DESCRIPTION

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

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

Index

NAME

SYNOPSIS

DESCRIPTION

FAT FILE SUPPORT

FILES

SEE ALSO