1 \cfg{man-identity}{tweak}{1}{2004-11-05}{Simon Tatham}{Simon Tatham}
4 \C{tweak-manpage} Man page for \cw{tweak}
6 \H{tweak-manpage-name} NAME
8 \cw{tweak} - efficient hex editor
10 \H{tweak-manpage-synopsis} SYNOPSIS
12 \c tweak [-l | -f] [-e] [-w width] [-o offset] filename
13 \e bbbbb bb bb bb bb iiiii bb iiiiii iiiiiiii
15 \H{tweak-manpage-description} DESCRIPTION
17 \cw{tweak} is a hex editor. It allows you to edit a file at very low
18 level, letting you see the full and exact binary contents of the
19 file. It can be useful for modifying binary files such as
20 executables, editing disk or CD images, debugging programs that
21 generate binary file formats incorrectly, and many other things.
23 Unlike simpler hex editors, \cw{tweak} possesses a fully functional
24 insert mode. This is not useful when editing many of the types of
25 file described above, but can be useful in other situations. Also,
26 an insert mode makes it easy to use \cw{tweak} to construct new files
29 When you open a file in \cw{tweak}, you can expect to see the screen
30 contents looking something like this:
32 \c 00000000 7F 45 4C 46 01 01 01 00 .ELF....
33 \c 00000008 00 00 00 00 00 00 00 00 ........
34 \c 00000010 02 00 03 00 01 00 00 00 ........
35 \c 00000018 D0 8E 04 08 34 00 00 00 ....4...
36 \c 00000020 2C EF 01 00 00 00 00 00 ,.......
38 The central column shows you the hexadecimal value of each byte in
39 the file you are editing. The column on the right shows the ASCII
40 interpretation of those bytes, where applicable. In the example
41 above, the sequence \c{45 4C 46} on the first line translates into
42 the ASCII upper-case letters \q{ELF}, but the subsequent sequence
43 \c{01 01 01 00} does not have any printable ASCII representation and
44 so the right-hand column simply prints dots.
46 The column on the left shows the position within the file of the
49 In fact, when you start \cw{tweak}, you will usually see 16 bytes of
50 the file per row, not 8 as shown above. However, this is
51 configurable if your screen is narrower - or wider - than the usual
52 80 columns, or if the file you are editing consists of fixed-size
53 records of some other size.
55 By default, \cw{tweak} does not load its entire input file into
56 memory. Instead, it loads it \e{lazily}, reading from the file on
57 disk when you request a view of a part of the file it doesn't have
58 stored. When you modify the file, it stores your modifications in
59 memory, but continues to refer to the original disk file for the
60 parts you have not touched. This means you can edit extremely large
61 files (for example, entire CD images) without difficulty; opening
62 such a file is instantaneous, making modifications causes \cw{tweak}'s
63 memory usage to grow with the size of the changes rather than the
64 size of the whole file, and only when saving the altered version
65 will \cw{tweak} have to read through the entire input file to write
68 However, this mode of operation has a disadvantage, which is that if
69 the input file is modified by another program while \cw{tweak} is
70 running, \cw{tweak}'s internal data structures will not be sufficient
71 to keep track, and it is likely that the file written out will
72 contain a mixture of the old and new contents of the input file.
73 Therefore, you can disable this lazy loading if you need to; see the
76 \H{tweak-manpage-options} OPTIONS
78 This section lists the command-line options supported by \cw{tweak}.
82 \dd Runs \cw{tweak} in \q{fix} mode, i.e. with the insert function
83 entirely disabled. This might be useful if you are editing a file in
84 which the insert mode is of no use (executables, for example, tend
85 to have strong dependencies on precise file offsets which make it
86 almost impossible to insert data in one without rendering it
87 unusable) and you want to avoid turning it on by mistake.
91 \dd Runs \cw{tweak} in \q{look} mode. In this mode \cw{tweak} does not
92 allow you to modify the data at all; it becomes simply a tool for
93 examining a file in detail.
97 \dd Runs \cw{tweak} in \q{eager} mode. In this mode \cw{tweak} will read
98 its entire input file when starting up. This causes it to take up
99 more memory, but means that it has no dependency on the input file
100 remaining unmodified, and other programs can alter it if they need
101 to without causing trouble.
103 \dt \cw{-w} \e{width}
105 \dd Specifies the number of bytes \cw{tweak} will display per line.
106 The default is 16, which fits neatly in an 80-column screen.
108 \dt \cw{-o} \e{offset}
110 \dd If this option is specified, \cw{tweak} will ensure that the given
111 file offset occurs at the start of a line. For example, if you
112 loaded a file using the options \cw{-w 8 -o 0x13}, you might see a
113 display a bit like this:
117 \c 00000000 7F 45 4C .EL
118 \c 00000003 46 01 01 01 00 00 00 00 F.......
119 \c 0000000B 00 00 00 00 00 02 00 03 ........
120 \c 00000013 00 01 00 00 00 D0 8E 04 ........
121 \c 0000001B 08 34 00 00 00 2C EF 01 .4...,..
123 By putting only three bytes of the file on the very first line,
124 \cw{tweak} has arranged that the file offset 0x13 (19 in decimal)
125 appears at the beginning of the fourth line.
127 You might use this option if you knew you were editing a file in a
128 particular format. For example, if your file contained a 53-byte
129 header followed by a series of 22-byte records, you might find it
130 useful to specify the options \cw{-w 22 -o 53}. This would arrange
131 that after the header, each individual record of the file would
132 appear on precisely one line of \cw{tweak}'s display.
138 \dd If this option is specified, \cw{tweak} will not attempt to load
139 and edit a file at all, but will simply produce its default
140 \cw{.tweakrc} file on standard output. This is a useful way to give
141 yourself a starting point if you want to begin reconfiguring
142 \cw{tweak}'s keyboard layout.
144 \H{tweak-manpage-keys} KEYS
146 This section describes all the editing keys supported by \cw{tweak} by
147 default. The default key bindings for \cw{tweak} are basically
150 \S{tweak-manpage-keys-movement} Movement keys
152 The Emacs cursor movement keys should all work, and their
153 counterparts in ordinary function keys ought to work too:
155 \b \cw{^P} and \cw{^N} go to the previous and next lines; Up and
156 Down should do the same.
158 \b \cw{^B} and \cw{^F} go back and forward one character; Left and
159 Right should do the same.
161 \b \cw{M-v} and \cw{^V} go up and down one screenful at a time; Page
162 Up and Page Down should do the same.
164 \b \cw{^A} and \cw{^E} go to the beginning and end of the line; Home
165 and End should do the same.
167 Press \cw{M-<} and \cw{M->} go to the beginning and end of the file.
169 Press \cw{^X g} to go to a particular byte position in the file; you
170 will be asked to type in the position you want. You can enter it in
171 decimal, or as a hex number with \cq{0x} before it.
173 \S{tweak-manpage-keys-editing} Editing keys
175 Press Return to move the cursor between the hex section of the
176 screen and the ASCII section.
178 When in the hex section, you can enter hexadecimal digits to alter
179 data; when in the ASCII section, you can directly type ASCII text.
181 In ASCII mode, you can also press \cw{^Q} to literally quote the
182 next input character; for example, if you want to insert a
183 Control-V, you can press \cw{^Q^V} and \cw{tweak} will automatically
184 insert the byte value 0x16.
186 Press \cw{^X^I}, or the Insert key if you have one, to toggle
187 between overwrite mode and insert mode. In insert mode, typing hex
188 or ASCII input will insert new bytes containing the values you
189 provide. Also, you can then press Backspace to delete the byte to
190 the left of the cursor, or \cw{^D} or Delete to delete the byte
193 \S{tweak-manpage-keys-cnp} Cut and paste
195 Press \cw{^@} (this character may be generated by the key
196 combination Control-@, or Control-2, or Control-Space) to mark the
197 end of a selection region. After you do this, the bytes between that
198 mark and the cursor will be highlighted. Press \cw{^@} again to
199 abandon the selection.
201 Press \cw{M-w} while a selection is active to copy the selected
202 region into \cw{tweak}'s cut buffer.
204 In insert mode, you also have the option of pressing \cw{^W} to
205 \e{cut} the selected region completely out of the file and place it
208 Finally, press \cw{^Y} to paste the cut buffer contents back into
209 the file (this will overwrite or insert depending on the current
212 \S{tweak-manpage-keys-search} Searching
214 Press \cw{^S} to search for a byte sequence. You will be asked to
215 enter some text to search for on the bottom line of the screen. You
216 can type this text in ASCII, or as a sequence of hex byte values
217 prefixed with backslashes (\cw{\\}). For example, if you wanted to
218 search for the byte value 5 followed by the word \q{hello}, you
219 might enter \cw{\\05hello}. If you want to specify a literal
220 backslash character, you can either enter it in hex (as \cw{\\5C}),
221 or simply double it on input (\cw{\\\\}).
223 Since \cw{tweak} deals in pure binary data, searches are always
226 \S{tweak-manpage-keys-display} Controlling the display
228 If you press \cw{^X w}, you will be asked to enter a new display
229 width. This has the same effect as passing the \cw{-w} option on the
230 command line. Similarly, pressing \cw{^X o} allows you to enter a
231 new display offset, equivalent to the \cw{-o} option.
233 By default, the current file position and file size are displayed on
234 \cw{tweak}'s status line in hex. If you prefer them in decimal, you
235 can press \cw{^X x} or \cw{^X h} to toggle them between hex and
238 \S{tweak-manpage-keys-misc} Miscellaneous
240 Press \cw{^L} to redraw the screen and recentre the cursor. Press
241 \cw{^Z} to suspend \cw{tweak} and return temporarily to the shell.
243 Press \cw{^X^S} to save the file you are editing.
245 Press \cw{^X^C} to exit \cw{tweak}. (If you do this with changes
246 unsaved, you will be asked whether you want to save them.)
248 \H{tweak-manpage-cfg} CONFIGURATION FILE
250 \cw{tweak}'s keyboard bindings are configurable. It will attempt to
251 read a file from your home directory called \cw{.tweakrc}, and if it
252 finds one it will use the keyboard bindings described in it. If it
253 does not find one, it will use its internal default bindings.
255 Most of the directives in \cw{.tweakrc} are of the form \cq{bind
256 command-name key}. For example, \cq{bind exit ^X^C}.
257 Additionally, there are two other directives, \cw{width} and
258 \cw{offset}, which give the default display parameters if no \cw{-w}
259 and \cw{-o} options are specified.
261 The easiest way to learn about the \cw{.tweakrc} file is to begin by
262 having \cw{tweak} output its internal default one:
264 \c tweak -D > $HOME/.tweakrc
266 Then you can read the default file, learn the \cw{tweak} internal
267 command names, and edit the file to do what you want.
269 \H{tweak-manpage-bugs} BUGS
271 Currently, \cw{tweak} cannot handle files larger than 2 gigabytes.
273 There is no reverse search function.
275 This man page probably ought to contain an explicit list of internal
276 command names, rather than simply referring you to the default