<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>RVM: Recoverable Virtual Memory, Release 1.3: rvmutl, the RVM Maintenance Utility</TITLE>
<LINK HREF="rvm_manual-9.html" REL=next>
<LINK HREF="rvm_manual-7.html" REL=previous>
<LINK HREF="rvm_manual.html#toc8" REL=contents>
</HEAD>
<BODY>
<A HREF="rvm_manual-9.html">Next</A>
<A HREF="rvm_manual-7.html">Previous</A>
<A HREF="rvm_manual.html#toc8">Contents</A>
<HR>
<H2><A NAME="rvmutl"></A> <A NAME="s8">8. rvmutl, the RVM Maintenance Utility</A></H2>
<P>
<P>rvmutl is the maintenance utility for RVM. Its principle
features are log creation and maintenance, but there are also status
and statistic display commands as well as printing commands for log
records.
A search facility for modifications to segments gains additional
functionality from the log by allowing its use as a debugging history.
<P>rvmutl is included in the <CODE>/bin</CODE> directory of the RVM
distribution directory. It can be invoked with a single, optional
parameter, which is interpreted as the name of a log file to be opened.
If the file doesnt exist, rvmutl will ask if you wish to create
and initialize a log with the specified name.
<P>rvmutl prompts for commands with a * prompt, after which commands
can be typed. Most commands have one or more parameters, which are
separated by one or more spaces.
In general, command names can be abbreviated, provided that sufficient
characters are typed to uniquely specify a command.
To allow typing short-cuts, some non-unique abbreviations have defined
interpretations.
These are specified with the command documentation
<P>As an example, the following sequence will initialize the file
log_file to have one megabyte of log record space:
<P>
<BLOCKQUOTE><CODE>
<PRE>
% rvmutl
* init_log log_file 1M
* quit
</PRE>
</CODE></BLOCKQUOTE>
<P>After this simple sequence, the log file is ready for use.
<P>The following pages describe the commands available in rvmutl.
<P><HR>
NAME
<H3></H3>
<P>rvmutl -- maintenance utility for RVM log
<P>
SYNOPSIS
<H3></H3>
<P><B>rvmutl</B> <EM>log</EM>
<P><B>rvmutl</B>
<P>
<P>
DESCRIPTION
<H3></H3>
<P> The program <CODE>rvmutl</CODE> is the maintenance
utility for RVM log. Its priniciple features are log creation and
maintenance, but there are also status and statistic display commands,
as well as printing commands for log records. There is also a search
facility for modifications to segments. You may find rvmutl a great
debugging tools.
<P>The are two ways to use <CODE>rvmutl</CODE>: You may supply the
name of the RVM log on the command line, or you do not supply the name
on command line but specify the log within <CODE>rvmutl</CODE> (see below).
<P><CODE>rvmutl</CODE> prompts for commands with a * (asterisk) prompt. Most
commands have one or more parameters, which are separated by one or
more spaces. Some commands have abbreviations, these will be
specified in the command section.
<P>For example, to examine the status of a RVM log (called logfile in the
example), you can do
<P>
<PRE>
> rvmutl
* open_log logfile
* status
Status of log: /home/clement/linuxobj8/rvm-src/tests/logfile
log created on: Tue Nov 4 1997 17:31:10.244793
log created with: RVM Interface Version 1.3 7 Mar 1994
(more display omitted ...)
* quit
</PRE>
<P>As another example, suppose you want to create a RVM log device on the
partition /dev/hdc7, of size 1 Megabyte, you can do
<P>
<PRE>
> rvmutl
* i /dev/hdc7 1M
* quit
</PRE>
<P>Note that in the preceding example, we use the abbreviation "i" for
the command "init_log", and we can use the unit "M" to stand for
Megabyte.
<P>
I/O REDIRECTION
<H3></H3>
<P>You can redirect input and output as in typical Unix shells. For
example, the following command will have all display redirected to the
file allrec:
<PRE>
* show all > allrec
*
</PRE>
<P>
COMMANDS
<H3></H3>
<P>In the following, I will detail all the available commands:
<DL>
<DT><B><B>all_spec</B> </B><DD><P>Show all special log records. Special log records
are those non-transaction records, such as wrap-around marker and
segment dictionary entry.
<P>
<DT><B><B>build_seg_dict</B> [<B>all</B>] [<B>clear</B>] </B><DD><P>
<DT><B><B>seg_dict</B> [<B>all</B>] [<B>clear</B>]</B><DD><P>
Build the segment dictionary by scanning
through the log. Segment dictionary is a in-memory structure that
maps segment code to segment file. Segment code is used in each
transaction range as a short hand of the segment file involved. If
the <B>all</B> option is specified, the whole log will be scanned,
otherwise the scanning will stop when one segment dictionary entry is
found. If the <B>clear</B> option is specified, the segment dictionary
will be cleared before starting the scanning process.
<P>
<DT><B><B>close_log</B></B><DD><P>Close the log file.
<DT><B><B>copy_log</B></B><DD><P>This provide a handy way to copy an existing log to another file or
partition. Since rvm logs start on different offset, depending on
whether they are files or partitions, using stock Unix commands such as
cp or dd sometimes is not as nice as using this command. Some meta
data (such as name of log) in the log status area in the destination
log will also be updated to reflect new meta data after log copying.
<P>
<DT><B><B>earliest</B></B><DD><P>Show the earliest transaction record in the log.
<P>
<DT><B><B>init_log</B> [<EM>log</EM> [<EM>length</EM>]]</B><DD><P>Initialize a log if it does not exist, or re-initialize it if it does
exist. The log will have the name <EM>log</EM> and the length of data
area will be <EM>length</EM>. The actual size of the log file or
partition will be slightly bigger because: 1. there is a log status
area (of size 3 sectors); and 2. for log used on raw partition, there
will be an offset (of 16 sectors) to jump off possible disklabel of
the partition.
<P>The <EM>length</EM> parameter is specified as an integer, optionally
followed by a single character size code. The following size codes
are defined: <B>K</B> or <B>k</B> for kilobytes, <B>M</B> or <B>m</B> for
megabytes, <B>S</B> or <B>s</B> for sectors (512 bytes), <B>P</B> or <B>p</B>
for pages (which have system dependent sizes) and <B>B</B> or <B>b</B> for
bytes (default).
<P>If either parameter is not specified, <B>init_log</B> will prompt for
the missing information.
<P>RVM maintains the log continuously after creation. If you are going
to re-initialize an existing log, make sure the log is empty before the
re-initialization, otherwise, the transaction records in the log would
be lost (i.e., they would not be applied to the data segment). You
can apply all transaction records to the data segments and empty the
log (also known as truncate in this manual) by the <B>recover</B>
command. You can use the command <B>status</B> to check whether a log
is empty.
<DT><B><B>find_earliest</B></B><DD><P>Print the offset of the earliest transaction record in the log.
<P>
<DT><B><B>find_tail</B></B><DD><P>Print the offset of the tail of the log.
<P>
<DT><B><B>head</B></B><DD><P>Print the transaction record at the head of log. (Note that there
could be even earlier than the head record -- smaller record number
and smaller time stamp. They are considered truncated from the log
and can be overwritten upon them freely. They are still on the log
just because it happens that rvm has not yet overwritten on them, and
they may be useful for debugging. The command
<B>earliest</B> prints the earliest record.)
<P>
<DT><B><B>log</B> [<EM>log</EM>] [<B>no_tail</B>] [<B>no_update</B> | <B>update</B>] </B><DD><P>
<DT><B><B>open_log</B> [<EM>log</EM>] [<B>no_tail</B>] [<B>no_update</B> | <B>update</B>] </B><DD><P>Open the rvm log named <EM>log</EM>. You must open a log before you can
use most of the rest commands. The optional <B>no_tail</B> switch turns
of the search of tail of the log (for example, when the log tail is
corrupted). The optional <B>no_update</B> and <B>update</B> switch
controls whether update will be made on the log and segment (they turn
on the rvm internal global variable <CODE>rvm_no_update</CODE>).
<P>
<DT><B><B>n</B> [<EM>num</EM>] </B><DD><P>
<DT><B><B>next</B> [<EM>num</EM>] </B><DD><P>Print the next <EM>num</EM> records. If the optional argument <EM>num</EM> is
not specified, then the next one record will be printed.
<P>
<DT><B><B>ns</B> [<EM>num</EM>] </B><DD><P>
<DT><B><B>next_sub_rec</B> [<EM>num</EM>] </B><DD><P>Print the next <EM>num</EM> sub-records. Sub-records are the individual
ranges of a transaction. If the optional argument <EM>num</EM> is
not specified, then the next one sub-record will be printed.
<P>
<DT><B><B>p</B> </B><DD><P>
<DT><B><B>peek</B> [<EM>file</EM>] <EM>offset</EM> / [<EM>csf</EM>]
Peek on (or dump) the content of <EM>file</EM>. You must specify the
argument <EM>file</EM> when you first peek or poke on a file, afterward you can
omit the argument and rvmutl will continue using the current file.
The argument <EM>offset</EM> determines from where
the dump should start. The argument <EM>csf</EM> determines how the dump
should be done, it comprises of three components: <EM>c</EM>, <EM>s</EM> and
<EM>f</EM>; each of them represents the count, size, and format
respectively. <EM>c</EM> is an integer and determines how many units, with
size specified by <EM>s</EM>, should be dumped, and <EM>f</EM> specifies what
is the dump format.</B><DD><P>In the following two examples, the first command dumps, from offset 0,
eight bytes in hexadecimal format; the second command dumps two
long integers in decimal format. Note that how the same file
content can be dumped into different format.
<PRE>
* peek 0 / 8xb
00000000000: 0x18 0000 0000 0000 0x23 0x17 0x14 0x63
* peek 0 / 2dl
00000000000: 24 1662261027
</PRE>
<P>There are seven different possible sizes: <B>b</B> for byte, <B>l</B> for
long, <B>s</B> for short, <B>O</B> for offset (two long integers
representing the high and low order bits respectively), <B>f</B> for
float, <B>D</B> for double and <B>t</B> for time value.
<P>There are nine different possible formats: <B>c</B> for character,
<B>d</B> for decimal, <B>o</B> for octal, <B>x</B> for hexidecimal, <B>u</B>
for unsigned, <B>f</B> for float, <B>D</B> for double, <B>O</B> for offset
(two long integers representing the high and low order bits
respectively) and <B>t</B> for time value.
<P>You may omit the arguments <EM>c</EM>, <EM>s</EM> and <EM>f</EM>, and
rvmutl will use the defaults, which are 1, d (decimal) and l (long)
respectively, for the three arguments respectively.
<P>
<DT><B><B>poke</B> [<EM>file</EM>] <EM>offset</EM> ÷ <EM>cs</EM> = <EM>val</EM> [<EM>val</EM> ... ]</B><DD><P>Poke on (modify) the content of <EM>file</EM>. You must specify the
argument <EM>file</EM> when you first peek or poke on a file, afterward
you can omit the argument and rvmutl will continue using the current
file. The argument <EM>offset</EM> determines from where the modification
should start. The argument <EM>cs</EM> determines how the modifications should be
done, it comprises of two components: <EM>c</EM> and <EM>s</EM>;
each of them represents the count and size respectively.
<EM>c</EM> is an integer and determines how many units, as specified by
<EM>s</EM>, should be modified.
<P>Examples:
<PRE>
* poke 512 / 4db = 25
* peek 512 / 8db
512: 25 25 25 25 0 0 0 0
* poke 512 / 2xl = 25
* peek 512 / 8db
512: 25 0 0 0 25 0 0 0
* poke 512 / 2b = 0x26 0x27
* peek 512 / 8db
512: 38 39 38 39 25 0 0 0
* poke 512 / b = "abcde"
* peek 512 / 8db
512: 97 98 99 100 101 0 0 0
</PRE>
Note that in the second example, the character <B>x</B>, which indicates
hexidecimal format in peek, is sliently ignored. To enter a
hexidecimal number, you should us prefix '0x' as in the third
example. Note also that how a pattern is repeated by using the
argument <EM>c</EM> in first and third example.
<P>There are seven different possible sizes: <B>b</B> for byte, <B>l</B> for
long, <B>s</B> for short, <B>O</B> for offset (two long integers
representing the high and low order bits respectively), <B>f</B> for
float, <B>D</B> for double and <B>t</B> for time value.
<P>You can also enter string by using the double-quote mark ("), as in
the last example.
<P>
<DT><B><B>pr</B> [<EM>num</EM>] </B><DD><P>
<DT><B><B>prev</B> [<EM>num</EM>] </B><DD><P>Print the previous <EM>num</EM> records. If the optional argument<EM>num</EM>
is not specified, then the previous one record will be printed.
<P>
<DT><B><B>ps</B> [<EM>num</EM>] </B><DD><P>
<DT><B><B>prev_sub_rec</B> [<EM>num</EM>] </B><DD><P>Print the previous <EM>num</EM> sub-records. Sub-records are the individual
ranges of a transaction. If the optional argument <EM>num</EM> is
not specified, then the previous one sub-record will be printed.
<P>
<DT><B><B>quit</B></B><DD><P>Quit rvmutl.
<P>
<DT><B><B>read_status</B></B><DD><P>Re-read the log status from on-disk log device (file or partition) to
in-memory structure (<CODE>status</CODE>). Note that the command <B>status</B>
show the content of the in-memory structure, but not the on-disk
device. If you have made changes to the on-disk device, you may want
to re-read them into the memory.
<P>
<DT><B><B>monitor</B> [<B>clear</B>] [<B>no_update</B> | <B>update</B>]</B><DD><P>You can specify memory ranges to be monitored by this command. When a
memory range is monitored, there will be message printed out whenever
there are modification within the range (E.g. in <B>recover</B>). The
switch <B>clear</B> will clear all the monitor previous set. The switch
<B>no_update</B> and <B>update</B> carry the usual meaning
(c.f. <B>open_log</B>). You will be asked, interactively, for the
addresses and formats for the ranges you want to monitor, you should
use the syntax similar to <B>poke</B>. The following example shows
how to use <B>monitor</B>, <B>show monitor</B>, as well as how
<B>recover</B> prints out the modification.
<PRE>
* open_log log3
* monitor update
More ranges (y or n [n])? y
Enter list of addresses/format, terminate with null line
: 0x200d7550/1l
:
* show monitor
Range Address/format Length
1 0x200d7550/1dl 4
* recover
do_nv: data from log record 2101, range 52
monitored range 1, 0x200d7550, length 4 matched by
modified range 0x200d7550, length 4
0x200d7550: 537286660
change_tree_insert: inserting entire range
monitored range 1, 0x200d7550, length 4 matched by
modified range 0x200d7550, length 4
0x200d7550: 537286660
do_nv: data from log record 2101, range 51
monitored range 1, 0x200d7550, length 4 matched by
modified range 0x200ced40, length 8367
0x200d7550: 0
change_tree_insert: inserting entire range
monitored range 1, 0x200d7550, length 4 matched by
modified range 0x200ced40, length 8367
0x200d7550: 0
do_nv: data from log record 2101, range 50
monitored range 1, 0x200d7550, length 4 matched by
modified range 0x200cdcc4, length 16
0x200d7550: 0
change_tree_insert: inserting entire range
monitored range 1, 0x200d7550, length 4 matched by
modified range 0x200cdcc4, length 16
</PRE>
<P>
<P>
<DT><B><B>recover</B> [<B>clear</B>] [<B>file</B>] [<B>no_update</B> | <B>update</B>]</B><DD><P>Truncate the log. Truncation means applying the transaction records,
that were logged on the log, to the data segment, and then reclaiming the
space on the log used by those records.
<P>
<DT><B><B>set</B> [<B>seg_dict</B>] <EM>field</EM> | <EM>addr</EM> = <EM>val</EM></B><DD><P>Set <EM>field</EM> (or memeory locateion at <EM>addr</EM>) to <EM>val</EM>. There
are five fields that you can set: <B>head</B>, <B>tail</B>,
<B>prev_head</B>, <B>prev_tail</B> and <B>log_start</B>. (You can use
<B>prev head</B> and <B>prev tail</B> to represent <B>prev_head</B> and
<B>prev_tail</B> respectively.) Only the in-memory structure of the
field is changed by this command, you can use <B>write_status</B> to
write the in-memory structure (status area) to disk.
<P>
<DT><B><B>s</B> </B><DD><P>
<DT><B><B>show</B> </B><DD><P>
<P>
<DL>
<DT><B><B>all</B> all records</B><DD><P>
<DT><B><B>all_records</B> all records</B><DD><P>
<DT><B><B>earliest</B> earliest record</B><DD><P>
<DT><B><B>head</B> record at head of log</B><DD><P>
<DT><B><B>mods</B> <EM>of</EM> <B>÷</B> <EM>cs</EM> [= <EM>val</EM>] </B><DD><P>
<DT><B><B>modificationss</B> <EM>of</EM> <B>÷</B> <EM>cs</EM> [= <EM>val</EM>] </B><DD><P>E.g.
<PRE>
* show mods 0x2000005c / 8b
Record number: 40756 modifies specified range:
Modification range: 1 Log offset: 224664
VM address: 0x2000005c Length: 52
Segment code: 1 Offset: 4188
Record length: 108 Back link: 48
0x2000005c: 74 -107 0 0 0 0 0 0
* show mods 0x2000005c / 1b = 74
Record number: 40756 assigns specified values
Modification range: 1 Log offset: 224664
VM address: 0x2000005c Length: 52
Segment code: 1 Offset: 4188
Record length: 108 Back link: 48
0x2000005c: 74
* show mods 0x2000005c / 1b = 75
-- no more records
</PRE>
<DT><B><B>monitor</B> all the range being monitored. </B><DD><P>
<DT><B><B>next</B> next record </B><DD><P>
<DT><B><B>next_sub_rec</B> next subrecord </B><DD><P>
<DT><B><B>ns</B> next subrecord </B><DD><P>
<DT><B><EM>num</EM> by record number </B><DD><P>
<DT><B><B>prev</B> previous record </B><DD><P>
<DT><B><B>previous</B> previous record </B><DD><P>
<DT><B><B>ps</B> previous subrecord </B><DD><P>
<DT><B><B>prev_sub_rec</B> previous subrecord </B><DD><P>
<DT><B><B>rec_number</B> <EM>num</EM> by record number </B><DD><P>
<DT><B><B>remaining</B> all remaining records </B><DD><P>
<DT><B><B>seg_dict</B> segment dictionary </B><DD><P>
<DT><B><B>seg_dictionary</B> segment dictionary </B><DD><P>
<DT><B><B>statistics</B> statistics of rvm activities </B><DD><P>
<DT><B><B>status</B> status area of the log </B><DD><P>
<DT><B><B>log_status</B> status area of the log </B><DD><P>
<DT><B><B>sr</B> current subrecord </B><DD><P>
<DT><B><B>sub_rec</B> currect subrecord </B><DD><P>
<DT><B><B>tail</B> tail record </B><DD><P>
<DT><B><B>timestamp</B> by record timestamp (note: no effect)</B><DD><P>
<P>
</DL>
<P>
<DT><B><B>sizeof</B> <EM>struct</EM> | <B>all</B> </B><DD><P>Show the size of a the give structure <EM>struct</EM>, or size of all
structure. The unit is byte. The following structure can be shown:
<B>condition</B>, <B>device_t</B> (<B>dev</B>), <B>dev_region_t</B>,
<B>FLUSH_BUF_LEN</B>, <B>free_page_t</B>, <B>MAXPATHLEN</B>, <B>int</B>,
<B>list_entry_t</B>, <B>log_t</B> (<B>log</B>), <B>log_buf_t</B>,
<B>LOG_DEV_STATUS_SIZE</B>, <B>log_dev_status_t</B>, <B>log_seg_t</B>,
<B>LOG_SPECIAL_IOV_MAX</B>, <B>LOG_SPECIAL_SIZE</B>, <B>log_special_t</B>,
<B>log_status_t</B> (<B>status</B>), <B>log_wrap_t</B>, <B>long</B>,
<B>MAX_READ_LEN</B>, <B>mem_region_t</B>,
<B>MIN_NV_RANGE_SIZE</B>, <B>MIN_FLUSH_BUF_LEN</B>,
<B>MIN_RECOVERY_BUF_LEN</B>, <B>MIN_TRANS_SIZE</B>, <B>mutex</B>,
<B>NUM_CACHE_TYPES</B>, <B>NV_LOCAL_MAX</B>, <B>nv_range_t</B> (<B>nv</B>),
<B>NV_RANGE_OVERHEAD</B>, <B>page_size</B>, <B>range_t</B>, <B>rec_end_t</B>,
<B>rec_hdr_t</B>, <B>RECOVERY_BUF_LEN</B>, <B>region_t</B>,
<B>rvm_length_t</B>, <B>rvm_offset_t</B>, <B>rvm_options_t</B>,
<B>rvm_region_t</B>, <B>rvm_tid_t</B>, <B>rw_lock_t</B> (<B>rw_lock</B>),
<B>rw_lock_mode_t</B>, <B>seg_t</B>, <B>struct_id_t</B>, <B>int_tid_t</B>,
<B>timeval</B>, <B>trans_hdr_t</B>, <B>TRANS_SIZE</B>, <B>tree_links_t</B>,
<B>tree_node_t</B>, <B>TRUNCATE</B>, <B>ulong</B>, <B>unsigned</B>.
<P>
<DT><B><B>status</B> </B><DD><P>
<DT><B><B>log_status</B> </B><DD><P>Show the log status area, which is the meta data about the log
(include head offset, tail offset, space used by records, total log
size, first record number, last record number, log creation time, last
truncation time etc).
<P>
<DT><B><B>sr</B> </B><DD><P>
<DT><B><B>sub_rec</B> </B><DD><P>Show the current subrecord.
<P>
<DT><B><B>statistics</B> </B><DD><P>Show the statistics of rvm activities.
<P>
<DT><B><B>tail</B> </B><DD><P>Show the transaction record at the tail of log.
<P>
<DT><B><B>update</B> </B><DD><P>Turn on update (i.e. set to false the rvm-internal global variable
<CODE>rvm_no_update</CODE>.) Update will not be made on the
log and segment.
<P>
<DT><B><B>no_update</B> </B><DD><P>Turn off update (i.e. set to true the rvm-internal global variable
<CODE>rvm_no_update</CODE>.) Update will be made on the log and segment.
<P>
<DT><B><B>write_status</B> </B><DD><P>Write out the in-memory log status structure to the log status block
on disk.
</DL>
<P>
<P>
BUGS
<H3></H3>
<P>The command <B>find_hole</B> is not yet documented.
<P>Peeking using the format or size of time value (<B>t</B>) does not work.
<P>The way to poke an offset value is not yet documented.
<P><B>sizeof</B> of some structs (e.g. <B>condition</B>, <B>int</B>) wrongly
displays the page size rather than the size of the structure.
<P>The use of <B>no_update</B> does not quite work. Rvmutl easily crashes
when the switch is used.
<P>The exact semantic of <B>replay</B> command is not documented, and the
command itself crashes quite easily.
<P>The use of <B>seg_dict</B> in <B>set</B> is not yet documented.
<P>The command <B>show timestamp</B> has no effect.
<P>
AUTHOR
<H3></H3>
<P>Yui Wah LEE completely rewrote this man page (Nov. 1997)
<HR>
<A HREF="rvm_manual-9.html">Next</A>
<A HREF="rvm_manual-7.html">Previous</A>
<A HREF="rvm_manual.html#toc8">Contents</A>
</BODY>
</HTML>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
211238da6d926d1ca4390483bb29f586
>
files
>
74
