mkshlib(1) mkshlib(1)NAME mkshlib - creates a shared library SYNOPSIS mkshlib -s specs [-n] -t target [-h host] ARGUMENTS -h host Specifies the name of the host shared library, host. If this option is not specified, then the command does not produce the host shared library. -n Does not generate a new target shared library. Use this option if you want to update the host shared library only. You still need to include the -t option and the target library name, because the system needs a version of the target shared library in order to build the host shared library. -s specs Specifies the name of the shared-library specification file, 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. This file includes initialization specifications for imported variables, if necessary. Imported variables are addresses external to the target shared library, such as the addresses of routines that the library can call upon. See the ``Description'' section for details on the shared-library specification file. -t target Specifies the name of the target shared library to be produced. The specification file includes the location at which the target library is to be installed. (See the description of the #target directive in ``Shared Library Specification File'' in the ``Description'' section.) DESCRIPTION mkshlib builds and maintains shared libraries. A shared library is similar in function to a normal, nonshared library. The primary differences become evident when the program is executed. More than one program can use the code in shared-library routines simultaneously. The executable code for a shared library is in Common Object File Format (COFF). The applications that call shared-library routines access the executable code by means of a special addressing January 1992 1
mkshlib(1) mkshlib(1)structure that is provided at link-edit time. (In contrast to the programs that use a shared library, each program that uses a nonshared library gets a private copy of any library routines required.) The shared library consists of two files (two sublibraries) containing source archives and executable object files. These files are referred to as the host shared library (host) and the target shared library (target), respectively. The host and target sublibraries can be on different systems. A host shared library is an archive that provides information used during link-edit (see ld(1) and ar(4)). The name of the host shared library is included on the cc command line, just as it is for a nonshared library (see cc(1)). All operations that can be performed on a nonshared library can be performed on a host shared library. The target shared library contains the executable code for all of the routines in the library and must be fully resolved. This library is brought into memory, if not already present there, during the execution of a program that calls it. The library attaches 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 the data. The user interface to mkshlib consists of command line arguments and a shared-library specification file (specs). The specification file provides information necessary to build the host and target shared libraries. To build both sublibraries, provide both the target and host arguments. To build only the target library, do not provide a host name. (However, a host library is required to access the target library by means of the link-edit process. Presumably, you either have a usable host library or will build one separately.) If you want mkshlib to build only a new host shared library and reuse an existing target shared library, use the -n option. You must supply the target argument, even if you are only building the host. 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). The shared-library specification file contains all the information necessary to build both the host and target shared libraries. The file contains directive names and associated specification information. Directive names must be at the beginning of the line. Some directives have specification information on the same line, and some 2 January 1992
mkshlib(1) mkshlib(1)directives introduce multiple specifications on subsequent 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 following list describes the six possible directive names and explains how to use them. The directives, except for #init, can be given in any order in the specification file. ## comment-text Specifies that the rest of the line is a comment. All comment text on that line is ignored. Comment lines may occur anywhere. Comments are recommended, but optional. #address section address Specifies the starting address in the virtual address space at which to bind the specified section of the target shared library. 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 starting address. #branch branch-table-specification... Interprets all lines following the #branch directive as branch-table specifications until it encounters another directive. A specification file can contain only one #branch directive. The branch table built from these specifications consists of jump instructions to the specified functions. Branch-table specification lines have this format: function position Give branch-table entries only to external functions. The position value is the relative location of the function name in the branch table. Each function can appear only once. The value of position for each function 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. Position values start with 1. Use each position value only once. You must account for all position values from 1 to the highest value. When adding functions to an existing library, provide January 1992 3
mkshlib(1) mkshlib(1)the new functions at higher positions than those they occupy in the existing branch table. Changing positions in an existing branch table renders that shared library unusable by previously linked applications. A position range can 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 function name. The remaining positions in the range can be used later for other functions. #init object initialization... Specifies object, using the name of an object file that requires initialization code (because it uses an imported variable). Each object file that requires initialization must be specified. (If the shared library being built is completely self-contained, that is, if it uses no imported variable, 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 initialization specification lines pertaining to the object file, object, named in the directive. Each line following the directive is interpreted as a specification line until another directive is encountered. To specify each line of initialization, use the following format: import importptr Replace import with an imported variable. Replace importptr with a pointer defined in the object file named in the #init directive preceding the initialization line. For each initialization line specified by this method, initialization code is generated in this form: importptr = &import; The system sets the value of importptr to the absolute address of import. #objects file... Specifies each entry of file, using the names of the object files that constitute the target shared library. 4 January 1992
mkshlib(1) mkshlib(1)This directive can be specified only once per shared library specification file. The system interprets the lines following the directive as specifications of file until another directive is encountered. #target pathname Specifies the absolute pathname for the location of the target shared library on the target system. This pathname, copied into a.out files, tells the operating system where to find the target shared library when executing a file that uses it. The maximum length of pathname is 64 characters. FILES /lib/*_s.a Host (archive) library file /shlib/*_s Target (executable) library file /tmp/pid-and-time Temporary directory /usr/bin/mkshlib Executable file SEE ALSO ar(1), as(1), cc(1), ld(1) a.out(4), ar(4) in A/UX Programmer's Reference ``Shared Libraries'' in A/UX Programming Languages and Tools, Volume I January 1992 5