1rvmutl(1) General Commands Manual rvmutl(1)
2
3
4
6 rvmutl - maintenance utility for RVM log
7
9 rvmutl log
10
11 rvmutl
12
14 The program rvmutl is the maintenance utility for RVM log. Its
15 priniciple features are log creation and maintenance, but there are
16 also status and statistic display commands, as well as printing com‐
17 mands for log records. There is also a search facility for modifica‐
18 tions to segments. You may find rvmutl a great debugging tools.
19
20 The are two ways to use rvmutl: You may supply the name of the RVM log
21 on the command line, or you do not supply the name on command line but
22 specify the log within rvmutl (see below).
23
24 rvmutl prompts for commands with a * (asterisk) prompt. Most commands
25 have one or more parameters, which are separated by one or more spaces.
26 Some commands have abbreviations, these will be specified in the com‐
27 mand section.
28
29 For example, to examine the status of a RVM log (called logfile in the
30 example), you can do
31
32 > rvmutl
33 * open_log logfile
34 * status
35
36 Status of log: /home/clement/linuxobj8/rvm-src/tests/logfile
37
38 log created on: Tue Nov 4 1997 17:31:10.244793
39 log created with: RVM Interface Version 1.3 7 Mar 1994
40 (more display omitted ...)
41 * quit
42
43
44 As another example, suppose you want to create a RVM log device on the
45 partition /dev/hdc7, of size 1 Megabyte, you can do
46
47 > rvmutl
48 * i /dev/hdc7 1M
49 * quit
50
51
52 Note that in the preceding example, we use the abbreviation "i" for the
53 command "init_log", and we can use the unit "M" to stand for Megabyte.
54
56 You can redirect input and output as in typical Unix shells. For exam‐
57 ple, the following command will have all display redirected to the file
58 allrec:
59
60 * show all > allrec
61 *
62
63
65 In the following, I will detail all the available commands:
66
67 all_spec
68 Show all special log records. Special log records are those
69 non-transaction records, such as wrap-around marker and segment
70 dictionary entry.
71
72
73 build_seg_dict [all] [clear]
74
75
76 seg_dict [all] [clear]
77
78 Build the segment dictionary by scanning through the log. Seg‐
79 ment dictionary is a in-memory structure that maps segment code
80 to segment file. Segment code is used in each transaction range
81 as a short hand of the segment file involved. If the all option
82 is specified, the whole log will be scanned, otherwise the scan‐
83 ning will stop when one segment dictionary entry is found. If
84 the clear option is specified, the segment dictionary will be
85 cleared before starting the scanning process.
86
87
88 close_log
89 Close the log file.
90
91 copy_log
92 This provide a handy way to copy an existing log to another file
93 or partition. Since rvm logs start on different offset, depend‐
94 ing on whether they are files or partitions, using stock Unix
95 commands such as cp or dd sometimes is not as nice as using this
96 command. Some meta data (such as name of log) in the log status
97 area in the destination log will also be updated to reflect new
98 meta data after log copying.
99
100
101 earliest
102 Show the earliest transaction record in the log.
103
104
105 init_log [log [length]]
106 Initialize a log if it does not exist, or re-initialize it if it
107 does exist. The log will have the name log and the length of
108 data area will be length. The actual size of the log file or
109 partition will be slightly bigger because: 1. there is a log
110 status area (of size 3 sectors); and 2. for log used on raw
111 partition, there will be an offset (of 16 sectors) to jump off
112 possible disklabel of the partition.
113
114 The length parameter is specified as an integer, optionally fol‐
115 lowed by a single character size code. The following size codes
116 are defined: K or k for kilobytes, M or m for megabytes, S or s
117 for sectors (512 bytes), P or p for pages (which have system
118 dependent sizes) and B or b for bytes (default).
119
120 If either parameter is not specified, init_log will prompt for
121 the missing information.
122
123 RVM maintains the log continuously after creation. If you are
124 going to re-initialize an existing log, make sure the log is
125 empty before the re-initialization, otherwise, the transaction
126 records in the log would be lost (i.e., they would not be
127 applied to the data segment). You can apply all transaction
128 records to the data segments and empty the log (also known as
129 truncate in this manual) by the recover command. You can use
130 the command status to check whether a log is empty.
131
132 find_earliest
133 Print the offset of the earliest transaction record in the log.
134
135
136 find_tail
137 Print the offset of the tail of the log.
138
139
140 head Print the transaction record at the head of log. (Note that
141 there could be even earlier than the head record -- smaller
142 record number and smaller time stamp. They are considered trun‐
143 cated from the log and can be overwritten upon them freely.
144 They are still on the log just because it happens that rvm has
145 not yet overwritten on them, and they may be useful for debug‐
146 ging. The command earliest prints the earliest record.)
147
148
149 log [log] [no_tail] [no_update │ update]
150
151 open_log [log] [no_tail] [no_update │ update]
152 Open the rvm log named log. You must open a log before you can
153 use most of the rest commands. The optional no_tail switch
154 turns of the search of tail of the log (for example, when the
155 log tail is corrupted). The optional no_update and update
156 switch controls whether update will be made on the log and seg‐
157 ment (they turn on the rvm internal global variable
158 rvm_no_update).
159
160
161 n [num]
162
163 next [num]
164 Print the next num records. If the optional argument num is not
165 specified, then the next one record will be printed.
166
167
168 ns [num]
169
170 next_sub_rec [num]
171 Print the next num sub-records. Sub-records are the individual
172 ranges of a transaction. If the optional argument num is not
173 specified, then the next one sub-record will be printed.
174
175
176 p
177
178 peek [file] offset / [csf]
179 Peek on (or dump) the content of file. You must specify the
180 argument file when you first peek or poke on a file, afterward
181 you can omit the argument and rvmutl will continue using the
182 current file. The argument offset determines from where the
183 dump should start. The argument csf determines how the dump
184 should be done, it comprises of three components: c, s and f;
185 each of them represents the count, size, and format respec‐
186 tively. c is an integer and determines how many units, with size
187 specified by s, should be dumped, and f specifies what is the
188 dump format." In the following two examples, the first command
189 dumps, from offset 0, eight bytes in hexadecimal format; the
190 second command dumps two long integers in decimal format. Note
191 that how the same file content can be dumped into different for‐
192 mat.
193
194 * peek 0 / 8xb
195 00000000000: 0x18 0000 0000 0000 0x23 0x17 0x14 0x63
196 * peek 0 / 2dl
197 00000000000: 24 1662261027
198
199
200 There are seven different possible sizes: b for byte, l for
201 long, s for short, O for offset (two long integers representing
202 the high and low order bits respectively), f for float, D for
203 double and t for time value.
204
205 There are nine different possible formats: c for character, d
206 for decimal, o for octal, x for hexidecimal, u for unsigned, f
207 for float, D for double, O for offset (two long integers repre‐
208 senting the high and low order bits respectively) and t for time
209 value.
210
211 You may omit the arguments c, s and f, and rvmutl will use the
212 defaults, which are 1, d (decimal) and l (long) respectively,
213 for the three arguments respectively.
214
215
216 poke [file] offset / cs = val [val ... ]
217 Poke on (modify) the content of file. You must specify the
218 argument file when you first peek or poke on a file, afterward
219 you can omit the argument and rvmutl will continue using the
220 current file. The argument offset determines from where the
221 modification should start. The argument cs determines how the
222 modifications should be done, it comprises of two components: c
223 and s; each of them represents the count and size respectively.
224 c is an integer and determines how many units, as specified by
225 s, should be modified.
226
227 Examples:
228
229 * poke 512 / 4db = 25
230 * peek 512 / 8db
231 512: 25 25 25 25 0 0 0 0
232
233 * poke 512 / 2xl = 25
234 * peek 512 / 8db
235 512: 25 0 0 0 25 0 0 0
236
237 * poke 512 / 2b = 0x26 0x27
238 * peek 512 / 8db
239 512: 38 39 38 39 25 0 0 0
240
241 * poke 512 / b = "abcde"
242 * peek 512 / 8db
243 512: 97 98 99 100 101 0 0 0
244
245
246 Note that in the second example, the character x, which indi‐
247 cates hexidecimal format in peek, is sliently ignored. To enter
248 a hexidecimal number, you should us prefix '0x' as in the third
249 example. Note also that how a pattern is repeated by using the
250 argument c in first and third example.
251
252 There are seven different possible sizes: b for byte, l for
253 long, s for short, O for offset (two long integers representing
254 the high and low order bits respectively), f for float, D for
255 double and t for time value.
256
257 You can also enter string by using the double-quote mark (”), as
258 in the last example.
259
260
261 pr [num]
262
263 prev [num]
264 Print the previous num records. If the optional argumentnum is
265 not specified, then the previous one record will be printed.
266
267
268 ps [num]
269
270 prev_sub_rec [num]
271 Print the previous num sub-records. Sub-records are the indi‐
272 vidual ranges of a transaction. If the optional argument num is
273 not specified, then the previous one sub-record will be printed.
274
275
276 quit Quit rvmutl.
277
278
279 read_status
280 Re-read the log status from on-disk log device (file or parti‐
281 tion) to in-memory structure (status). Note that the command
282 status show the content of the in-memory structure, but not the
283 on-disk device. If you have made changes to the on-disk
284 device, you may want to re-read them into the memory.
285
286
287 monitor [clear] [no_update │ update]
288 You can specify memory ranges to be monitored by this command.
289 When a memory range is monitored, there will be message printed
290 out whenever there are modification within the range (E.g. in
291 recover). The switch clear will clear all the monitor previous
292 set. The switch no_update and update carry the usual meaning
293 (c.f. open_log). You will be asked, interactively, for the
294 addresses and formats for the ranges you want to monitor, you
295 should use the syntax similar to poke. The following example
296 shows how to use monitor, show monitor, as well as how recover
297 prints out the modification.
298
299 * open_log log3
300 * monitor update
301 More ranges (y or n [n])? y
302
303 Enter list of addresses/format, terminate with null line
304 : 0x200d7550/1l
305 :
306 * show monitor
307
308 Range Address/format Length
309 1 0x200d7550/1dl 4
310
311 * recover
312 do_nv: data from log record 2101, range 52
313 monitored range 1, 0x200d7550, length 4 matched by
314 modified range 0x200d7550, length 4
315 0x200d7550: 537286660
316
317 change_tree_insert: inserting entire range
318 monitored range 1, 0x200d7550, length 4 matched by
319 modified range 0x200d7550, length 4
320 0x200d7550: 537286660
321
322
323 do_nv: data from log record 2101, range 51
324 monitored range 1, 0x200d7550, length 4 matched by
325 modified range 0x200ced40, length 8367
326 0x200d7550: 0
327
328 change_tree_insert: inserting entire range
329 monitored range 1, 0x200d7550, length 4 matched by
330 modified range 0x200ced40, length 8367
331 0x200d7550: 0
332
333 do_nv: data from log record 2101, range 50
334 monitored range 1, 0x200d7550, length 4 matched by
335 modified range 0x200cdcc4, length 16
336 0x200d7550: 0
337
338 change_tree_insert: inserting entire range
339 monitored range 1, 0x200d7550, length 4 matched by
340 modified range 0x200cdcc4, length 16
341
342
343
344
345 recover [clear] [file] [no_update │ update]
346 Truncate the log. Truncation means applying the transaction
347 records, that were logged on the log, to the data segment, and
348 then reclaiming the space on the log used by those records.
349
350
351 set [seg_dict] field │ addr = val
352 Set field (or memeory locateion at addr) to val. There are five
353 fields that you can set: head, tail, prev_head, prev_tail and
354 log_start. (You can use prev head and prev tail to represent
355 prev_head and prev_tail respectively.) Only the in-memory
356 structure of the field is changed by this command, you can use
357 write_status to write the in-memory structure (status area) to
358 disk.
359
360
361 s
362
363 show
364
365
366 all all records
367
368 all_records all records
369
370 earliest earliest record
371
372 head record at head of log
373
374 mods of / cs [= val]
375
376 modificationss of / cs [= val]
377 E.g.
378
379 * show mods 0x2000005c / 8b
380
381 Record number: 40756 modifies specified range:
382
383 Modification range: 1 Log offset: 224664
384 VM address: 0x2000005c Length: 52
385 Segment code: 1 Offset: 4188
386 Record length: 108 Back link: 48
387
388 0x2000005c: 74 -107 0 0 0 0 0 0
389
390 * show mods 0x2000005c / 1b = 74
391
392 Record number: 40756 assigns specified values
393
394 Modification range: 1 Log offset: 224664
395 VM address: 0x2000005c Length: 52
396 Segment code: 1 Offset: 4188
397 Record length: 108 Back link: 48
398
399 0x2000005c: 74
400
401 * show mods 0x2000005c / 1b = 75
402 -- no more records
403
404
405 monitor all the range being monitored.
406
407 next next record
408
409 next_sub_rec next subrecord
410
411 ns next subrecord
412
413 num by record number
414
415 prev previous record
416
417 previous previous record
418
419 ps previous subrecord
420
421 prev_sub_rec previous subrecord
422
423 rec_number num by record number
424
425 remaining all remaining records
426
427 seg_dict segment dictionary
428
429 seg_dictionary segment dictionary
430
431 statistics statistics of rvm activities
432
433 status status area of the log
434
435 log_status status area of the log
436
437 sr current subrecord
438
439 sub_rec currect subrecord
440
441 tail tail record
442
443 timestamp by record timestamp (note: no effect)
444
445
446
447 sizeof struct │ all
448 Show the size of a the give structure struct, or size of all
449 structure. The unit is byte. The following structure can be
450 shown: condition, device_t (dev), dev_region_t, FLUSH_BUF_LEN,
451 free_page_t, MAXPATHLEN, int, list_entry_t, log_t (log),
452 log_buf_t, LOG_DEV_STATUS_SIZE, log_dev_status_t, log_seg_t,
453 LOG_SPECIAL_IOV_MAX, LOG_SPECIAL_SIZE, log_special_t, log_sta‐
454 tus_t (status), log_wrap_t, long, MAX_READ_LEN, mem_region_t,
455 MIN_NV_RANGE_SIZE, MIN_FLUSH_BUF_LEN, MIN_RECOVERY_BUF_LEN,
456 MIN_TRANS_SIZE, mutex, NUM_CACHE_TYPES, NV_LOCAL_MAX, nv_range_t
457 (nv), NV_RANGE_OVERHEAD, page_size, range_t, rec_end_t,
458 rec_hdr_t, RECOVERY_BUF_LEN, region_t, rvm_length_t, rvm_off‐
459 set_t, rvm_options_t, rvm_region_t, rvm_tid_t, rw_lock_t
460 (rw_lock), rw_lock_mode_t, seg_t, struct_id_t, int_tid_t,
461 timeval, trans_hdr_t, TRANS_SIZE, tree_links_t, tree_node_t,
462 TRUNCATE, ulong, unsigned.
463
464
465 status
466
467 log_status
468 Show the log status area, which is the meta data about the log
469 (include head offset, tail offset, space used by records, total
470 log size, first record number, last record number, log creation
471 time, last truncation time etc).
472
473
474 sr
475
476 sub_rec
477 Show the current subrecord.
478
479
480 statistics
481 Show the statistics of rvm activities.
482
483
484 tail Show the transaction record at the tail of log.
485
486
487 update Turn on update (i.e. set to false the rvm-internal global vari‐
488 able rvm_no_update.) Update will not be made on the log and seg‐
489 ment.
490
491
492 no_update
493 Turn off update (i.e. set to true the rvm-internal global vari‐
494 able rvm_no_update.) Update will be made on the log and seg‐
495 ment.
496
497
498 write_status
499 Write out the in-memory log status structure to the log status
500 block on disk.
501
503 The command find_hole is not yet documented.
504
505 Peeking using the format or size of time value (t) does not work.
506
507 The way to poke an offset value is not yet documented.
508
509 sizeof of some structs (e.g. condition, int) wrongly displays the page
510 size rather than the size of the structure.
511
512 The use of no_update does not quite work. Rvmutl easily crashes when
513 the switch is used.
514
515 The exact semantic of replay command is not documented, and the command
516 itself crashes quite easily.
517
518 The use of seg_dict in set is not yet documented.
519
520 The command show timestamp has no effect.
521
523 Yui Wah LEE completely rewrote this man page (Nov. 1997)
524
525
526
527 rvmutl(1)