mkshlib(1) mkshlib(1)NAME mkshlib - create shared library SYNOPSIS mkshlib -s specs [-n] -t target [-h host] DESCRIPTION mkshlib builds and maintains shared libraries. A shared li- brary is similar in function to a normal, non-shared li- brary. The primary differences appear at run time. The code in shared library routines can be used by more than one pro- gram at the same time. The executable code for a shared li- brary, which is in the Common Object File Format (COFF), is accessed from the applications that call upon it by means of a special addressing structure provided within them during link edit. (In contrast to the shared library, each program that makes use of a nonshared library gets a private copy of any li- brary routines required.) The shared library consists of two files (two sublibraries) containing source archives and executable object files, re- ferred to as the host shared library and the target shared library, respectively. The host and target sublibraries may be on different systems. A host shared library is an ar- chive which provides information used during link-edit (see ld(1) and ar(4)). The name of the host shared library is included on the cc(1) command line in the same way as a non-shared library (see cc(1)). All operations that can be performed on a non-shared library can be performed on a host shared library. The target shared library contains the executable code for all the routines in the library and must be fully resolved. This library is brought into memory, if not already present, during execution of a program that calls upon it. The li- brary is attached to a user's process during execution. The text section of target objects is shared by all processes using that target library, but each process gets its own copy of data. The user interface to mkshlib consists of command line argu- ments and a shared-library specification file. The specifi- cation file provides information necessary to build the host and target shared libraries. To build both sublibraries, provide both names. To build only the target library, do not provide a host name. (How- ever, a host library is required to access the target li- brary via the link edit process. Presumably, you either have a usable host library or will build one separately.) April, 1990 1
mkshlib(1) mkshlib(1)The -n option may be used to have mkshlib build only a new host shared library and reuse an existing target shared li- brary. The name of the target library must be supplied, even if only the host is to be built. To build the host and target files, mkshlib invokes other tools such as the archiver, ar(1), the assembler, as(1), and the loader, ld(1). FLAG OPTIONS The following command-line arguments are recognized: -s specs Provide the name of the shared-library specification file, specs, which contains the information necessary to build the shared library. Its contents include a list of the object files to be included in the shared library, the branch-table specifications for the target library, the pathname directing where to install the target library, and the start addresses of text and data sections for the target library. Initialization specifications for imported variables are given in this file, if necessary. Imported variables are addresses external to the target shared library, such as the ad- dresses of routines that the library may call upon. Details on the shared-library specification file are given after the command line arguments. -t target Specify the name, target, of the target shared library to be produced. The location where the target library is to be installed is given in the specification file (see the #target directive below). -h host Specify the name of the host shared library, host. If not specified, then the host shared library is not pro- duced. -n Do not generate a new target shared library. This op- tion is used to update the host shared library only. The -t flag option and the target library name must still be supplied, because a version of the target shared library is needed to build the host shared li- brary. Shared Library Specification File The specification file contains all the information neces- sary to build both the host and target shared libraries. The file contains directive names and associated specifica- tion information. Directive names must be at the start of the line. Some directives have specification information on 2 April, 1990
mkshlib(1) mkshlib(1)the same line, and some directives introduce multiple specifications on following lines. Lines following such a directive are interpreted as specification lines for that directive, until another directive or the end of the file is encountered. The six possible directive names and their use are described below. Directives may be given in any order in the specifi- cation file, except for the #init directive. ## comment-text Specifies that the remainder of the line is a comment. All comment-text on that line is ignored. Comment lines may occur anywhere. Comments are optional, but recommended. #address section-name address Specify the start address in the virtual address space at which to bind section-name of the target shared- library executable. Typically, address directives are provided for the .text and .data sections of the target library. Addresses must be on a 256 kilobyte (KB) boundary. The .bss section is grouped with the .data section, and does not require a start address. #branch branch-table-specification branch-table-specification branch-table-specification . . . All lines following the #branch directive are inter- preted as branch-table specifications, until another directive is encountered. Only one #branch directive can be in a specification file. The branch table built from these specifications consists of jump instructions to the specified functions. Branch-table specification lines have the following format: function-name position Only functions should be given branch-table entries, and those functions must be external. The position value is the relative location of the function name in the branch table. Each function-name may appear only once. The value of position for each function-name April, 1990 3
mkshlib(1) mkshlib(1)given is the position (or position range) of the name in the branch table. The value of position is a single integer, or a range of integers of the form position1- position2. (The use of a position range is given later.) Position values start with 1, each position value may be used only once, and all position values from 1 to the highest value used must be accounted for. When adding functions to an existing library, provide the new functions at higher positions than in the ex- isting branch table. Changing positions in an existing branch table renders that shared library not usable by previously linked applications. A position range may also be used to reserve empty slots in the branch table for later use. Only the highest value of the range is associated with the func- tion name. The remaining positions in the range may be used later for other functions. #init object initialization initialization initialization . . . Specify object with the name of an object file that re- quires initialization code (because it uses an imported variable). Each object file that requires initializa- tion must be specified. (If the shared library being built is completely self-contained (uses no imported variable), then no #init directive is used, because no initialization code is necessary.) All #init directives must be placed after the #objects directive and its associated specifications in the specification file. An #init directive is followed by one or more initiali- zation specification lines pertaining to the object file, object, named in the directive. Each line fol- lowing the directive is interpreted as a specification line until another directive is encountered. Specify each line of initialization by using the following for- mat: import importptr The placeholder import refers to an imported variable, and importptr is a pointer defined within the object file named in the #init directive preceding the ini- 4 April, 1990
mkshlib(1) mkshlib(1)tialization line. For each initialization line so specified, initialization code is generated in the form: importptr = &import; in which the value of importptr is set to the absolute address of import. #objects file file file . . . Specify each entry of file with the names of the object files constituting the target shared library. This directive can be specified only once per shared library specification file. The lines following the directive are interpreted as specifications of file un- til another directive is encountered. #target pathname Specify the absolute pathname for the location of the target shared library on the target system. This path- name is copied into a.out files, and tells the operat- ing system where to find the target shared library when executing a file that uses it. The maximum length for pathname is 64 characters. FILES /usr/bin/mkshlib /lib/*_s.a Host (archive) library /shlib/*_s Target (executable) library /tmp/unique-name Temporary directory (name is PID and time) SEE ALSO ar(1), as(1), cc(1), ld(1), a.out(4), ar(4). ``Shared Libraries,'' in A/UX Programming Languages and Tools, Volume I. April, 1990 5