04/03/84 cross_reference, cref Syntax: cref library_descriptions {-control_args} Function: creates a cross-reference listing of any number of object programs. The listing contains information about each object module encountered, including the location of each program, its entry points and definitions, any synonyms, and which other modules encountered reference each entry point or definition. It also optionally supplies a cross-reference listing of include files used by the modules encountered. Arguments: library_descriptions can be chosen from the following: paths are the pathnames of segments to be examined and cross-referenced. The star convention is allowed. -library library_name {-all} paths, -lb library_name {-a} paths specifies that all modules represented by paths are treated by the cross-referencer as if they were in a common library of that name. The library_name argument can be any identifier you choose. If -all (-a) is specified, all the module names encountered are considered external (see "Resolving references.") This control argument is generally used only for cross-references of the Multics hardcore libraries. Control arguments: -brief, -bf suppresses nonfatal error messages. It does not affect the reporting of error messages to the output file. -first specifies, with -input_file, that once any instance of a particular module has been located, the cross-referencer need not search the remaining directories for other instances of modules with the same name. If omitted, the cross-referencer searches all libraries in the search list for each module name supplied. -include_files, -icf cross-references include files used by all modules examined. -input_file path, -if path uses a control file describing the modules to be cross-referenced instead of the library descriptions. If the crl suffix is not part of the supplied filename, it is assumed. If -input_file is given, no library descriptions are allowed. -line_length N, -ll N formats lines in the output file to the given line length. The default is 132. -output_file path, -of path creates the cross-reference list in a segment of the specified name. If the cross-reference suffix is not part of the supplied filename, it is assumed. If -output_file is not selected, but -input_file is, the output file takes its name from the input file, with the suffix ".crossref" replacing the suffix ".crl"; otherwise, the output file is named "crossref.crossref". -short, -sh does not include in the output referenced modules that are not included in the scope of any library_descriptions. With -short, the output reflects only the interrelationships among the modules in the libraries specified. Notes on module examination: Module examination is performed in two passes--the first defines all the segment names, synonyms, and definitions; the second examines external references and attempts to resolve them with existing definitions. Segments encountered fall into four classes--nonobject, bound segments, stand-alone modules, and archives. When a nonobject segment is encountered, a warning message is printed and the segment is included in the results of the cross-reference. When a bound segment is found, a warning message is printed and the segment is ignored. Bound segments are useless to the cross-referencer, since information necessary to determine which components use which external reference links is no longer available due to the binding process. Use instead the object archive from which it was bound. When a stand-alone segment is met, it is analyzed for entry points, definitions, and external references. All additional names on the segment are entered as synonyms for the module. This information is then included in the results of the cross-reference. When an archive is encountered, each component is analyzed for entry points, definitions, and external references. If a bindfile exists, synonyms for each component are derived from "synonym" statements in the bindfile, when they exist. This information is then included in the results of the cross-reference. Modules are also identified by the segment in which they are found (either themselves, for a stand-alone segment, or the containing archive, for an archive) and by the library_name of the directory in which they are found. If the directory is given without a library_name, the pathname of the directory is used as the library_name. This allows having multiple occurrences of segments with the same name, as long as they differ by at least one of these identification criteria. Notes on resolving references: When a module is examined by the cross-referencer, its name and synonyms are classified as "internal" or "external" by the following criteria-- 1. If the module is stand alone, its name and synonyms are external. 2. If the module is archived and the library description contained -all , its name and all its synonyms are considered external. 3. If the module is archived and the library description did not contain -all, its name and each of its synonyms are external only if they appear in the "Addname:" statement of the bindfile. If no bindfile exists, the name and synonyms are considered internal. The cross-referencer tries to resolve external references on a best-match basis by using the following criteria: 1. If the reference can be satisfied by a definition in the same module, that definition is used. 2. If the referencing module is part of a bound segment and can be satisfied by a definition in the same bound segment, that definition is used. 3. If the reference can be satisfied by an external definition in the same library_name, that definition is used. 4. Otherwise, the first external definition found that satisfies the reference is used. If more than one such definition exists, a warning message is printed. Notes on format of a driving file: If -input_file is given, the cross-referencer takes its input from a special file. The first lines of the file must contain the names of one or more directories to be searched. They are specified in the following manner: -library: (OR -library -all:) pathname_1 library_name_a pathname_2 library_name_b .... .... pathname_N library_name_z; Each pathname_i specifies a directory to be searched. When present, a library name (which can contain spaces) is used to describe the preceding directory name. (See "Module examination" above.) The tokens "-wd" or semicolon ends the search list. The next information in the file is a list of the segments to be examined. They must appear one to a line. If you wish to define explicitly synonyms for any modules that would not otherwise be generated (e.g., a nonapparent reference name by which a segment is sometimes initiated), they can be included in this section with one or more lines of the form modulename syn1 syn2 ... synN These lines do not by themselves cause the cross-referencer to search for the module "modulename", since it may not be a freestanding segment. Any synonyms defined in this manner are considered external. Notes on special cases: Segments with unique names and with single-digit last components are ignored, since these are conventions used by the system library tools to denote segments to be deleted shortly. Archives whose names are identical with the exception of a different numeric next-to-last component are considered the same archive. Definitions or entry points in archive components that masquerade as segment names by an added name on the bound segment, without being defined as a synonym for their containing component, are not cross-referenced satisfactorily. Notes on include files: The cross-reference listing of include files, when requested, is appended to the regular output of the cross-referencer. Each include file met is classified by its entryname and its date/time modified. This ensures that modules that use different versions of the same include file are apparent. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved