Increase the size of the 'message' buffer, which is currently

[sgt/tweak] / manpage.but

\cfg{man-identity}{tweak}{1}{2004-11-05}{Simon Tatham}{Simon Tatham}
\cfg{man-mindepth}{1}

\C{tweak-manpage} Man page for \cw{tweak}

\H{tweak-manpage-name} NAME

\cw{tweak} - efficient hex editor

\H{tweak-manpage-synopsis} SYNOPSIS

\c tweak [-l | -f] [-e] [-w width] [-o offset] filename
\e bbbbb  bb   bb   bb   bb iiiii   bb iiiiii  iiiiiiii

\H{tweak-manpage-description} DESCRIPTION

\cw{tweak} is a hex editor. It allows you to edit a file at very low
level, letting you see the full and exact binary contents of the
file. It can be useful for modifying binary files such as
executables, editing disk or CD images, debugging programs that
generate binary file formats incorrectly, and many other things.

Unlike simpler hex editors, \cw{tweak} possesses a fully functional
insert mode. This is not useful when editing many of the types of
file described above, but can be useful in other situations. Also,
an insert mode makes it easy to use \cw{tweak} to construct new files
from scratch.

When you open a file in \cw{tweak}, you can expect to see the screen
contents looking something like this:

\c 00000000   7F 45 4C 46 01 01 01 00   .ELF....
\c 00000008   00 00 00 00 00 00 00 00   ........
\c 00000010   02 00 03 00 01 00 00 00   ........
\c 00000018   D0 8E 04 08 34 00 00 00   ....4...
\c 00000020   2C EF 01 00 00 00 00 00   ,.......

The central column shows you the hexadecimal value of each byte in
the file you are editing. The column on the right shows the ASCII
interpretation of those bytes, where applicable. In the example
above, the sequence \c{45 4C 46} on the first line translates into
the ASCII upper-case letters \q{ELF}, but the subsequent sequence
\c{01 01 01 00} does not have any printable ASCII representation and
so the right-hand column simply prints dots.

The column on the left shows the position within the file of the
start of each row.

In fact, when you start \cw{tweak}, you will usually see 16 bytes of
the file per row, not 8 as shown above. However, this is
configurable if your screen is narrower - or wider - than the usual
80 columns, or if the file you are editing consists of fixed-size
records of some other size.

By default, \cw{tweak} does not load its entire input file into
memory. Instead, it loads it \e{lazily}, reading from the file on
disk when you request a view of a part of the file it doesn't have
stored. When you modify the file, it stores your modifications in
memory, but continues to refer to the original disk file for the
parts you have not touched. This means you can edit extremely large
files (for example, entire CD images) without difficulty; opening
such a file is instantaneous, making modifications causes \cw{tweak}'s
memory usage to grow with the size of the changes rather than the
size of the whole file, and only when saving the altered version
will \cw{tweak} have to read through the entire input file to write
the output.

However, this mode of operation has a disadvantage, which is that if
the input file is modified by another program while \cw{tweak} is
running, \cw{tweak}'s internal data structures will not be sufficient
to keep track, and it is likely that the file written out will
contain a mixture of the old and new contents of the input file.
Therefore, you can disable this lazy loading if you need to; see the
\cw{-e} option below.

\H{tweak-manpage-options} OPTIONS

This section lists the command-line options supported by \cw{tweak}.

\dt \cw{-f}

\dd Runs \cw{tweak} in \q{fix} mode, i.e. with the insert function
entirely disabled. This might be useful if you are editing a file in
which the insert mode is of no use (executables, for example, tend
to have strong dependencies on precise file offsets which make it
almost impossible to insert data in one without rendering it
unusable) and you want to avoid turning it on by mistake.

\dt \cw{-l}

\dd Runs \cw{tweak} in \q{look} mode. In this mode \cw{tweak} does not
allow you to modify the data at all; it becomes simply a tool for
examining a file in detail.

\dt \cw{-e}

\dd Runs \cw{tweak} in \q{eager} mode. In this mode \cw{tweak} will read
its entire input file when starting up. This causes it to take up
more memory, but means that it has no dependency on the input file
remaining unmodified, and other programs can alter it if they need
to without causing trouble.

\dt \cw{-w} \e{width}

\dd Specifies the number of bytes \cw{tweak} will display per line.
The default is 16, which fits neatly in an 80-column screen.

\dt \cw{-o} \e{offset}

\dd If this option is specified, \cw{tweak} will ensure that the given
file offset occurs at the start of a line. For example, if you
loaded a file using the options \cw{-w 8 -o 0x13}, you might see a
display a bit like this:

\lcont{

\c 00000000                  7F 45 4C        .EL
\c 00000003   46 01 01 01 00 00 00 00   F.......
\c 0000000B   00 00 00 00 00 02 00 03   ........
\c 00000013   00 01 00 00 00 D0 8E 04   ........
\c 0000001B   08 34 00 00 00 2C EF 01   .4...,..

By putting only three bytes of the file on the very first line,
\cw{tweak} has arranged that the file offset 0x13 (19 in decimal)
appears at the beginning of the fourth line.

You might use this option if you knew you were editing a file in a
particular format. For example, if your file contained a 53-byte
header followed by a series of 22-byte records, you might find it
useful to specify the options \cw{-w 22 -o 53}. This would arrange
that after the header, each individual record of the file would
appear on precisely one line of \cw{tweak}'s display.

}

\dt \cw{-D}

\dd If this option is specified, \cw{tweak} will not attempt to load
and edit a file at all, but will simply produce its default
\cw{.tweakrc} file on standard output. This is a useful way to give
yourself a starting point if you want to begin reconfiguring
\cw{tweak}'s keyboard layout.

\H{tweak-manpage-keys} KEYS

This section describes all the editing keys supported by \cw{tweak} by
default. The default key bindings for \cw{tweak} are basically
Emacs-like.

\S{tweak-manpage-keys-movement} Movement keys

The Emacs cursor movement keys should all work, and their
counterparts in ordinary function keys ought to work too:

\b \cw{^P} and \cw{^N} go to the previous and next lines; Up and
Down should do the same.

\b \cw{^B} and \cw{^F} go back and forward one character; Left and
Right should do the same.

\b \cw{M-v} and \cw{^V} go up and down one screenful at a time; Page
Up and Page Down should do the same.

\b \cw{^A} and \cw{^E} go to the beginning and end of the line; Home
and End should do the same.

Press \cw{M-<} and \cw{M->} go to the beginning and end of the file.

Press \cw{^X g} to go to a particular byte position in the file; you
will be asked to type in the position you want. You can enter it in
decimal, or as a hex number with \cq{0x} before it.

\S{tweak-manpage-keys-editing} Editing keys

Press Return to move the cursor between the hex section of the
screen and the ASCII section.

When in the hex section, you can enter hexadecimal digits to alter
data; when in the ASCII section, you can directly type ASCII text.

In ASCII mode, you can also press \cw{^Q} to literally quote the
next input character; for example, if you want to insert a
Control-V, you can press \cw{^Q^V} and \cw{tweak} will automatically
insert the byte value 0x16.

Press \cw{^X^I}, or the Insert key if you have one, to toggle
between overwrite mode and insert mode. In insert mode, typing hex
or ASCII input will insert new bytes containing the values you
provide. Also, you can then press Backspace to delete the byte to
the left of the cursor, or \cw{^D} or Delete to delete the byte
under the cursor.

\S{tweak-manpage-keys-cnp} Cut and paste

Press \cw{^@} (this character may be generated by the key
combination Control-@, or Control-2, or Control-Space) to mark the
end of a selection region. After you do this, the bytes between that
mark and the cursor will be highlighted. Press \cw{^@} again to
abandon the selection.

Press \cw{M-w} while a selection is active to copy the selected
region into \cw{tweak}'s cut buffer.

In insert mode, you also have the option of pressing \cw{^W} to
\e{cut} the selected region completely out of the file and place it
in the cut buffer.

Finally, press \cw{^Y} to paste the cut buffer contents back into
the file (this will overwrite or insert depending on the current
mode).

\S{tweak-manpage-keys-search} Searching

Press \cw{^S} to search for a byte sequence. You will be asked to
enter some text to search for on the bottom line of the screen. You
can type this text in ASCII, or as a sequence of hex byte values
prefixed with backslashes (\cw{\\}). For example, if you wanted to
search for the byte value 5 followed by the word \q{hello}, you
might enter \cw{\\05hello}. If you want to specify a literal
backslash character, you can either enter it in hex (as \cw{\\5C}),
or simply double it on input (\cw{\\\\}).

Press \cw{^R} to search backwards instead of forwards from the
current cursor position.

Since \cw{tweak} deals in pure binary data, searches are always
case-sensitive.

\S{tweak-manpage-keys-display} Controlling the display

If you press \cw{^X w}, you will be asked to enter a new display
width. This has the same effect as passing the \cw{-w} option on the
command line. Similarly, pressing \cw{^X o} allows you to enter a
new display offset, equivalent to the \cw{-o} option.

By default, the current file position and file size are displayed on
\cw{tweak}'s status line in hex. If you prefer them in decimal, you
can press \cw{^X x} or \cw{^X h} to toggle them between hex and
decimal.

\S{tweak-manpage-keys-misc} Miscellaneous

Press \cw{^L} to redraw the screen and recentre the cursor. Press
\cw{^Z} to suspend \cw{tweak} and return temporarily to the shell.

Press \cw{^X^S} to save the file you are editing.

Press \cw{^X^C} to exit \cw{tweak}. (If you do this with changes
unsaved, you will be asked whether you want to save them.)

\H{tweak-manpage-cfg} CONFIGURATION FILE

\cw{tweak}'s keyboard bindings are configurable. It will attempt to
read a file from your home directory called \cw{.tweakrc}, and if it
finds one it will use the keyboard bindings described in it. If it
does not find one, it will use its internal default bindings.

Most of the directives in \cw{.tweakrc} are of the form \cq{bind
command-name key}. For example, \cq{bind exit ^X^C}.
Additionally, there are two other directives, \cw{width} and
\cw{offset}, which give the default display parameters if no \cw{-w}
and \cw{-o} options are specified.

The easiest way to learn about the \cw{.tweakrc} file is to begin by
having \cw{tweak} output its internal default one:

\c tweak -D > $HOME/.tweakrc

Then you can read the default file, learn the \cw{tweak} internal
command names, and edit the file to do what you want.

\H{tweak-manpage-bugs} BUGS

This man page probably ought to contain an explicit list of internal
command names, rather than simply referring you to the default
\cw{.tweakrc}.