1 02/10/86 library_map
2
3 Syntax as a command:
4 library_map search_names -control_args -output_args
5
6
7 Function: selects entries from a library and writes the status of
8 these entries into a map file suitable for printing. The entries in
9 the file are alphabetized by primary name.
10
11 A full range of status information can be included in the map items by
12 using one or more of the output arguments. Besides information
13 returned by the status command, the map items can include access
14 information, object segment attributes and other segment contents
15 information, quota information, etc.
16
17 This command uses library descriptor and library search procedures, as
18 described in "The Library Descriptor Commands" of the Multics Library
19 Maintenance AN80 manual. When no output arguments are given, the
20 information included by default in the map items is controlled by the
21 search program for the particular library being mapped. The default
22 map item includes the information most appropriate for a library map.
23
24
25 Arguments:
26 search_names
27 are entrynames that identify the library entries to be output. The
28 star convention can be used to identify a group of entries with a
29 single search name. Up to 100 search names can be given in the
30 command. If none are given, then any default search names specified
31 in the library descriptor are used.
32
33
34 Control arguments:
35 -chase
36 suppresses map items for any intermediate links that exist between a
37 library link and its eventual target.
38 -components, -comp
39 displays map items for all the components of a matching library
40 entry, in addition to the item for the matching entry. It also
41 displays map items for all components of a library entry containing
42 a matching entry. See "Notes" below.
43 -container, -cont
44 displays a map item for the library entry that contains each
45 matching entry, in addition to the item for the matching entry.
46 See "Notes" below. Default
47
48
49 -cross_reference, -cref
50 includes cross-reference map items in the output for the secondary
51 names on library entries that are output. See "Notes" below.
52 Default
53 -descriptor desc_name, -desc desc_name
54 gives a pathname or reference name that identifies the library
55 descriptor describing the libraries to be searched. If -descriptor
56 is not given, then the default library descriptor is used.
57 -entry, -et
58 includes map items in the output only for library entries matching
59 one of the search names.
60
61
62 -footer footing, -fo footing
63 gives a character string that is used in the footing line at the
64 bottom of each page to identify the libraries being mapped. If the
65 string contains blanks, then it must be enclosed in quotes. Only
66 the first 45 characters of the string are used. If -footer is not
67 given, then a default character string is used in the footing line.
68 See "Notes" below.
69 -header heading, -he heading
70 gives a character string that is used as a heading line on the first
71 page of the map to identify the libraries that have been mapped. If
72 the string contains blanks, then it must be enclosed in quotes.
73 Only the first 120 characters of the string are used. If -header is
74 not given, then a default heading line is used. See "Notes"
75 below.
76
77
78 -library library_name, -lb library_name
79 identifies a library that is to be searched for entries matching the
80 search names. The star convention can be used to identify a group
81 of libraries with a single library name. Up to 100 -library control
82 arguments can be given in each command. If none are given, then any
83 default library names specified in the library descriptor are used.
84 -no_chase
85 causes map items for the intermediate links. Default
86 -no_cross_reference, -ncref
87 suppresses cross-reference map items.
88 -omit
89 suppresses the map item for library entries awaiting deletion from
90 the libraries. Default
91
92
93 -output_file file, -of file
94 identifies the output file in which the library map is to be
95 generated. A relative or absolute pathname can be given for the
96 file. If it does not have a suffix of map, then one is assumed. If
97 -output_file is not given, then the map is generated in the
98 library.map file that is created in the user's working directory.
99 -retain, -ret
100 causes a map item for library entries awaiting deletion from the
101 libraries as determined by the library search program.
102 -search_name search_name
103 identifies a search name that begins with a minus - to distinguish
104 the search name from a control argument. There are no other
105 differences between the search names described above and those given
106 with the -search_name control argument. One or more -search_name
107 control arguments can be given in the command.
108
109
110 List of output arguments:
111 -access
112 displays all access control information, which includes: the user's
113 access mode to the library entry, its ring brackets, ACL, access
114 class, AIM attributes, safety switch setting, and for directory
115 entries the initial ACLs.
116 -all, -a
117 displays all available information.
118 -contents
119 displays information describing the contents of library entries,
120 which includes: compilation information, object attributes, and
121 segment printability information.
122
123
124 -default, -dft
125 displays default information in addition to the information
126 requested by other output arguments. This is the default when no
127 other output arguments are given.
128 -status, -st
129 displays all status information printed by the command "status
130 -all", except for access control information.
131
132
133 The following output arguments are available, but are probably not
134 of interest to every user. They provide more selective control over
135 which status information is included in the output.
136 -access_class, -acc
137 displays the access class if other than system low, the setting of
138 the security-out-of-service switch, the audit switch, and the
139 multiple access class switch if on.
140 -acl
141 displays the access control list.
142 -author, -at
143 displays the author and bit count author if different from the
144 author.
145 -bit_count, -bc
146 displays the bit count.
147
148
149 -compiler_name
150 displays the name of the compiler of an object segment.
151 -compiler_options
152 displays the compiler option information stored in an object
153 segment.
154 -compiler_version
155 displays the version information for the compiler of an object
156 segment.
157 -copy, -cp
158 displays the setting of the copy-on-write switch if on.
159 -current_length
160 displays the current length if different from records used.
161
162
163 -date, -dt
164 displays the date/time contents modified, date/time used, date/time
165 entry modified, date/time dumped, and date/time compiled.
166 -date_time_compiled, -dtc
167 displays the date/time compiled.
168 -date_time_contents_modified, -dtcm
169 displays the date/time modified.
170 -date_time_dumped, -dtd
171 displays the date/time dumped.
172 -date_time_entry_modified, -dtem
173 displays the date/time entry modified. For archive components, this
174 corresponds to the date/time component updated into the archive.
175 -date_time_used, -dtu
176 displays the date/time used.
177
178
179 -device, -dv
180 displays the name of the logical volume on which the entry resides
181 for nondirectory and non-MSF entries, the name of the son's logical
182 volume for directory and MSF entries, and the setting of the
183 transparent-to-paging device switch.
184 -error
185 displays messages that indicate the errors that occurred while
186 obtaining the status information.
187 -initial_acl, -iacl
188 displays the initial access control lists associated with library
189 directory entries.
190
191
192 -length, -ln
193 displays the records used, current length if different from the
194 records used, maximum length if different from
195 sys_info$max_seg_size, bit count, archive component offset, and
196 directory quota information.
197 -level, -lev
198 causes a level number to precede each output entry. This number
199 indicates the relationship between a library entry and its
200 components. Normally, this relationship is indicated only by
201 indenting the component names beneath those of the library entry.
202 -link_target
203 displays the pathname of the target of each library link.
204 -match
205 displays all names that match any of the search names.
206
207
208 -max_length, -ml
209 displays the maximum length if different from
210 sys_info$max_seg_size.
211 -mode, -md
212 displays the user's mode of access to the library entry.
213 -name, -nm
214 displays all names.
215 -new_line, -nl
216 causes a line to be skipped between each level-one entry in the
217 output. Normally, no lines are skipped between entries.
218 -non_ascii
219 displays an indication that a library entry contains non-ASCII
220 characters.
221
222
223 -object_info
224 displays information about format of an object segment and its entry
225 bound.
226 -offset, -ofs
227 displays the word offset of an archive component within its archive.
228 -pathname, -pn
229 displays the pathname of the parent of each library entry.
230 -primary, -pri
231 displays the primary name.
232
233
234 -quota
235 displays directory quota information for library directory entries,
236 which includes: quota set on the directory, quota used, terminal
237 quota switch setting if on, a count of inferior directories with
238 terminal quota if nonzero, the time/record product for the
239 directory, and the date-time/time-record product updated. If a
240 directory is a master directory, this information is also printed.
241 -records, -rec
242 displays the records used.
243 -ring_brackets, -rb
244 displays the ring brackets.
245 -safety
246 displays the setting of the safety switch if on.
247
248
249 -type, -tp
250 displays the type of each library entry, which includes: link,
251 segment, archive, archive component, multisegment file, multisegment
252 file component, and directory.
253 -unique_id, -uid
254 displays the unique identifier.
255
256
257 Notes: Any combination of output arguments can be used in a command,
258 since the use of several output arguments merely causes more
259 information to be included in each map entry. However, the following
260 groups of control arguments are mutually exclusive, and only one
261 argument from each group can be given in a command:
262
263 -cross_reference and -no_cross_reference
264 -chase and -no_chase
265 -retain and -omit.
266
267 The -container and -components control arguments are provided to
268 facilitate the mapping of library entries related to a given bound
269 segment. When only one component of a bound segment archive matches
270 one of the search names, -entry causes a map item for only the matching
271 library entry. The -container and -components control arguments, which
272 can be used singly or together but neither with -entry, cause map items
273 for entries related to a matching entry as well.
274
275
276 The -container and -components control arguments have the following
277 effects. If a search name is given that matches a component in a
278 source archive, giving -entry produces a map item for only that
279 component. Giving -container instead would produce a map item for the
280 source archive, as well as one for the matching component. Giving
281 -components produces map items for all of the components of the source
282 archive containing the matching component. Giving both -container and
283 -components produces map items for the source archive and all of its
284 components.
285
286 When -cross_reference is used, a cross-reference map item is included
287 in the map for each secondary name on a matching library entry. The
288 cross-reference item includes: the secondary name, the date/time
289 modified for the library entry, and its pathname. The pathname ends
290 with the primary name of the library entry, providing a reference to
291 the map item that includes complete information about the entry.
292
293
294 The library map is generated in an output file identified by
295 -output_file. If this control argument is not given, then a file
296 called library.map is created in the user's working directory. If the
297 output file already exists, it is truncated before the new map is
298 created. Thus, several library_map commands executed in the same
299 working directory in the same or different processes without
300 -output_file can produce unpredictable results. In such cases, this
301 control argument should be used to create a different map file in each
302 command.
303
304
305 If -header is given, then the heading line is centered on the first
306 page of the map beneath the lines:
307
308 Map of the nn Entries
309
310 of the
311
312 The heading line should be worded with this in mind. For example:
313
314 Map of the 35 Entries
315
316 of the
317
318 Standard Library Bind Listing Directory
319
320
321 If -header is not given, a default heading line is constructed by
322 concatenating the names of the libraries that were searched:
323
324 Map of the 350 Entries
325
326 of the
327
328 Libraries
329
330 standard_library.list, unbundled_library.list,
331 tools_library.list, user_library.list, network_library.list
332
333 If -footer is given, then the footing line placed at the bottom of each
334 page of the library map contains the footing character string given
335 with the control argument, along with a page number and the names of
336 the first and last map items that appear on the page; if not given,
337 then the concatenated library names used in the heading line are also
338 used in the footing line.