1 02/18/85  peruse_crossref, pcref
 2 
 3 Syntax as a command:  pcref {cref_path} search_names {-control_args}
 4 
 5 
 6 Syntax as an active function:  [pcref {cref_path} search_names]
 7 
 8 
 9 Function: prints or returns information extracted from the output file
10 generated by the cross_reference command.
11 
12 
13 Arguments:
14 cref_path
15    is the pathname of the crossref output file to search.  It can be a
16    multisegment file (MSF).  It must contain a > or < character to
17    distinguish it from a search_name.  If you supply no cref_path, the
18    total system cross-reference (>ldd>crossref>total.crossref) is used.
19    To specify a cross-reference in your working directory, use
20    -pathname.
21 search_names
22    are one or more names to search for references to in the crossref.
23    They can be either symbolic linker references or include file names
24    and can have any of the following forms:
25       segname
26       segname$entryname
27       XXX.incl.YYY
28 
29 
30    Any component of a search name can be a star name, except that
31    neither a segname nor an include file name can begin with a star
32    name character and the string ".incl" must appear in toto.  If you
33    specify no entryname with the segname, all references to any entry
34    points in the segment are listed.  XXX.incl is accepted as an
35    abbreviation for XXX.incl.*.  Don't use > and < in a search name.
36 
37 
38 Control arguments:
39 -brief, -bf
40    does not print any information for selected cross-reference items
41    that have no entries (callers).  (Default)
42 -brief_errors, -bfe
43    suppreses any error messages due to entrypoints or include files
44    that are not found in the crossref.
45 -long, -lg
46    print selected cross-reference items that have no entries.
47 -long_errors, -lge
48    prints an error message if one or more entrypoints or include files
49    given on the command line are not found in the crossref.  (Default)
50 -pathname crossref path, -pn crossref path
51    specifies crossref path as the crossref to search.
52 
53 
54 Notes: This command uses a binary search to locate the desired
55 information and thus is quite inexpensive, even when searching the
56 total system crossref.  Average cost for a single search of the system
57 crossref is about 45 page faults and 0.5 CPU seconds, or roughly 30
58 times cheaper and far more convenient than using an editor.
59 
60 No attempt is made to combine the results of the search names--if you
61 ask for something twice, it gets printed twice.
62 
63 This command does not perform any significant validation on the input
64 filen and is likely to either take faults or signal the logic_error
65 condition if asked to search something other than a crossref output
66 file.
67 
68 
69 There is no support for synonyms--a search name must be the primary
70 name of a segment and not a synonym established in a bindfile or the
71 hardcore header.
72 
73 There is no way to select specific types of things, such as all the
74 unresolvable references in the crossref.