doc/hed.1

   1 .\" Process this file with groff -man -Tascii hed.1
   2 .TH HED 1 "Apr, 2011"
   3 .SH NAME
   4 hed \- a visual hexadecimal editor
   5 .SH SYNOPSIS
   6 .B hed
   7 .I "[OPTION]... FILE"
   8 .SH DESCRIPTION
   9 .B hed
  10 is a terminal hexadecimal editor with \f2vim\f1-like controls which can
  11 edit arbitrarily large files.
  12 .PP
  13
  14 .SH OPTIONS
  15
  16 .TP
  17 \f3--normal\f1
  18 Start in the N(ormal) mode (default, ASCII input is not taken as the data
  19 to be written but as controls, \f2vi\f1-like).
  20
  21 .TP
  22 \f3-i\f1, \f3--insert\f1
  23 Start in the I(insert) mode instead of the default N(ormal) mode - ASCII
  24 input is taken as the data to be written, and are inserted in front of
  25 the already present data.
  26
  27 .TP
  28 \f3-r\f1, \f3--replace\f1
  29 Start in the R(eplace) mode instead of the default N(ormal) mode - ASCII
  30 input is taken as the data to be written, and are overwriting the already
  31 present data.
  32
  33 .TP
  34 \f3-s\f1, \f3--spread\f1
  35 Spread the file content viewport to fully fit the terminal width. The
  36 default style is to keep the line width a multiple of 0x10.
  37
  38 .TP
  39 \f3--play\f1
  40 Replay the argument value as hed keyboard input, taken verbatim. If you
  41 won't make hed quit by the input fed to it, it will be available for user
  42 control after replaying the queued keypresses.
  43
  44 .TP
  45 \f3-h\f1, \f3--help\f1
  46 Show a short usage information.
  47
  48 .TP
  49 \f3-V\f1, \f3--version\f1
  50 Show the program version and basic licence information.
  51
  52 .SH CONTROLS
  53
  54 .TP
  55 \f3R\f1, \f3e\f1
  56 Switch to the R(eplace) mode.
  57
  58 .TP
  59 \f3i\f1
  60 Switch to the I(nsert) mode.
  61
  62 .TP
  63 \f3Ins\f1
  64 Switch to the I(nsert) mode, or to the R(eplace) mode if already there.
  65
  66 .TP
  67 \f3Esc\f1
  68 Switch to the N(ormal) mode.
  69
  70 .TP
  71 \f3Tab\f1
  72 Switch between the hexadecimal and ASCII column.
  73
  74 .TP
  75 \f3h\f1, \f3j\f1, \f3k\f1, \f3l\f1
  76 Move cursor left, down, up or right respectively.
  77
  78 .TP
  79 \f3Arrow keys\f1
  80 Move cursor appropriately.
  81
  82 .TP
  83 \f3Home\f1, \f3gg\f1
  84 Move cursor to the start of the file.
  85
  86 .TP
  87 \f3End\f1, \f3G\f1
  88 Move cursor to the end of the file.
  89
  90 .TP
  91 \f3^\f1
  92 Move cursor to the start of the line.
  93
  94 .TP
  95 \f3$\f1
  96 Move cursor to the end of the line.
  97
  98 .TP
  99 \f3PageUp\f1, \f3Ctrl-B\f1
 100 Move cursor one page up.
 101
 102 .TP
 103 \f3PageDown\f1, \f3Ctrl-F\f1
 104 Move cursor one page down.
 105
 106 .TP
 107 \f3:\f1
 108 Exmode (see below).
 109
 110 .TP
 111 \f3#\f1
 112 Jump to the specified offset with the cursor. The offset is an expression
 113 (see below; for starters, just type the decimal, octal or hexadecimal number).
 114
 115 .TP
 116 \f3/\f1
 117 Forward search the specified expression in the file (see below about
 118 expressions; for starters, try 'STRING' or xHEXBYTESEQ). Register ". contains
 119 the byte sequence currently being matched. This can be used for smart searches;
 120 /'asdf'".'hjkl' will match strings 'asdf' and 'hjkl' with a single byte inbetween
 121 (that can be anything). /xf0f0f0&". will match a sequence of three bytes with
 122 high nibbles not set.
 123
 124 .TP
 125 \f3?\f1
 126 Backwards search the specified expression in the file (see below about
 127 expressions; for starters, try 'STRING' or xHEXBYTESEQ).
 128
 129 .TP
 130 \f3n\f1
 131 Next search match.
 132
 133 .TP
 134 \f3N\f1
 135 Previous search match.
 136
 137 .TP
 138 \f3"x\f1
 139 Select register x (letter, digit, ").
 140
 141 .TP
 142 \f3y\f1
 143 Yank visual region to selected register.
 144
 145 .TP
 146 \f3d\f1
 147 Delete visual region and save it to selected register.
 148
 149 .TP
 150 \f3p\f1
 151 Put selected register after cursor. If a visual region is selected,
 152 its contents is exchanged with the register.
 153
 154 .TP
 155 \f3P\f1
 156 Put selected register before cursor. If a visual region is selected,
 157 its contents is exchanged with the register.
 158
 159 .TP
 160 \f3o\f1
 161 Overwrite buffer portion at the cursor by contents of selected register;
 162 the buffer portion is either as big as the register was, or bounded
 163 by selected region if in visual mode.
 164
 165 .TP
 166 \f3mx\f1
 167 Put a mark x at the current cursor position.
 168
 169 .TP
 170 \f3\'x\f1
 171 Jump at mark x.
 172
 173 .TP
 174 \f3Ctrl-Y\f1
 175 Move the viewport one line up.
 176
 177 .TP
 178 \f3Ctrl-E\f1
 179 Move the viewport one line down.
 180
 181 .TP
 182 \f3r\f1
 183 Replace the character under the cursor with the character specified
 184 next (pressed key in the ASCII column, typed hexadecimal digit in
 185 the hex column).
 186
 187 .TP
 188 \f3x\f1, \f3Del\f1
 189 Delete the byte on the cursor, moving the rest of the file
 190 left by a single byte.
 191
 192 .TP
 193 \f3X\f1, \f3Backspace\f1
 194 Delete the byte before the cursor, moving the rest of the file
 195 left by a single byte.
 196
 197 .TP
 198 \f3F2\f1, \f3W\f1
 199 Invoke :w.
 200
 201 .TP
 202 \f3F10\f1, \f3Z\f1
 203 Invoke :x.
 204
 205 .TP
 206 \f3Q\f1
 207 Invoke :q.
 208
 209
 210 .SH EXMODE
 211
 212 .TP
 213 \f3r\f1, \f3read\f1
 214 Read a file from disk and insert it at the cursor position.
 215 If a region is selected, replace the region with the file.
 216
 217 .TP
 218 \f3w\f1, \f3write\f1
 219 Save the file to disk. If a region is selected, save the region
 220 to a separate file (you will be prompted for the name).
 221
 222 .TP
 223 \f3!\f1, \f3pipe\f1
 224 Pipe the selected region through a given command
 225 (you will be prompted for the name).
 226
 227 .TP
 228 \f3q\f1, \f3quit\f1
 229 Quit without saving the file.
 230
 231 .TP
 232 \f3x\f1, \f3exit\f1
 233 Save the file if modified, and then quit.
 234
 235 .TP
 236 \f3swp\f1
 237 Save a swap file to disk. It is a dump containing only unsaved
 238 blocks thus it is efficient even for very large files (if you
 239 haven't made very large changes, obviously) and can be used
 240 to restore your work shall you have no chance to save your file
 241 properly later.
 242
 243 .TP
 244 \f3s\f1, \f3substitute\f1
 245 Substitute given search expression by another expression at the
 246 first match. ". is empty in the other expression.
 247 (TODO: represent the seq being subst'd.)
 248
 249 .TP
 250 \f3S\f1, \f3substall\f1
 251 Substitute all matches of given search expression from cursor
 252 to the end of file by another expression. Otherwise same as \f3s\f1.
 253
 254 .TP
 255 \f3ie\f1, \f3ieval\f1
 256 Evaluate expression and insert result at the cursor position.
 257
 258 .TP
 259 \f3pe\f1, \f3peval\f1
 260 Evaluate expression and print it.
 261
 262
 263 .TP
 264 \f3re\f1, \f3reval\f1
 265 Evaluate expression and fill the selected region with the result.
 266 The original content being replaced is available through the ".
 267 register. So e.g. to set the highest bit of every other selected
 268 byte, use \f3".|0x8000\f1. To swap pairs of bytes, use
 269 \f3((".&xff00)>>8)|((".&x00ff)<<8)\f1.
 270
 271 .TP
 272 \f3width\f1
 273 Change number of bytes per line.
 274
 275 .TP
 276 \f3endian\f1
 277 Toggle between big-endian and little-endian values in the status
 278 line. The default when started is the native endianity of the
 279 machine.
 280
 281
 282 .SH EXPRESSIONS
 283
 284 .B hed
 285 employs powerful concept of "expressions" at various places
 286 (e.g. when searching). An expression can be arbitrarily long
 287 and is composed of atoms pasted together (whitespaces can appear
 288 anywhere between atoms; you might _need_ whitespaces to make
 289 sure the atom boundary is unambigous). Each atom can span
 290 arbitrary number of bytes and the result of the whole expression
 291 is a string of bytes produced by the atoms. Arithmetic operations
 292 work on signed integers. The sign bit is not part of the expression
 293 result (hence 255 occupies only 1 byte, not 2 bytes, for instance),
 294 but it is used during evaluation. All basic expressions (numbers,
 295 strings, etc.) are positive. A negative number may be produced
 296 either with a unary minus or by subtracting a larger number from
 297 a smaller one.
 298
 299 An atom can be either:
 300
 301 .TP
 302 \f3(atom)\f1
 303 Yes, you can use parentheses, isn't that cool?
 304
 305 .TP
 306 \f3atom{len}\f1
 307 Make sure the atom spans exactly this number of bytes.
 308 (Currently supported only for numerical atoms and strings.)
 309
 310 .TP
 311 \f3unop atom\f1
 312 You can apply an unary operation on an atom. Currently only
 313 \f3~\f1 (bit negation) and \f3-\f1 (arithmetic negation) is
 314 supported.
 315
 316 .TP
 317 \f3atom binop atom\f1
 318 You can produce an atom by performing a binary operation on
 319 two subatoms. If they don't have the same length, the missing
 320 bytes are sign-extended. Supported binary operators are
 321 \f3|\f1, \f3&\f1, \f3^\f1,
 322 \f3+\f1, \f3-\f1, \f3*\f1, \f3/\f1, \f3%\f1,
 323 \f3<<\f1 and \f3>>\f1.
 324 .B hed
 325 implements all these operations on number of arbitrary size.
 326 Currently no binary operation takes any special precedence, they are
 327 evaluated in the order you write them.
 328
 329 .TP
 330 \f3\'ASCII string\'\f1
 331 Just like that. Prefix any apostrophes and backslashes by a
 332 backslash.
 333
 334 .TP
 335 \f31234\f1
 336 Decimal number, takes the number of bytes necessary. Only
 337 decimal numbers of limited size are supported for now.
 338
 339 .TP
 340 \f30x123456789abcdef\f1
 341 Only hexadecimal numbers of limited size are supported for now.
 342 Note that this is a NUMBER meaning that it might be transformed
 343 for endianity.
 344
 345 .TP
 346 \f30644\f1
 347 Octal number, also with a size limitation.
 348
 349 .TP
 350 \f3x123456789abcdef\f1
 351 This is a BYTE SEQUENCE of arbitrary length. The difference from
 352 hexadecimal number is that it can be of any length and that it
 353 is not flipped for endianity.
 354
 355 .TP
 356 \f3"x\f1
 357 Register \f3x\f1 as a byte sequence. Through this, you can have access
 358 to any clipboard register and as a bonus, there are a few special registers:
 359 \f3,\f1 for content under the cursor, \f3.\f1 for currently matched content
 360 (e.g. when matching during a search; empty when doing standalone evaluation),
 361 and \f3_\f1 for content from the start of the file.
 362 Note that this byte sequence is fixed-size! It is actually auto-sized to fit
 363 the parent expression width for binary operations, and defaults to one byte.
 364
 365 .TP
 366 \f3@x\f1
 367 Mark \f3x\f1 as a sizeof(off_t) byte number. Does not work during search. Also
 368 adds one special mark \f3$\f1 for cursor offset.
 369
 370 .TP
 371 \f3"x[offset]\f1
 372 Contents of the register (see above) at given offset. The offset is
 373 a full-fledged expression, interpreted as a number.
 374
 375
 376 .SH CONFIGURATION
 377 .B hed
 378 reads it configuration file from
 379 .I /etc/hedrc
 380 and
 381 .I ~/.hedrc.
 382 The file is parsed for lines in the form "set option value". For
 383 boolean options, value 0 or false is recognized as false, any
 384 other value (including no value at all) is recognied as true.
 385 These are the supported options:
 386
 387 .TP
 388 \f3default_mode\f1
 389 Either normal, insert or replace.
 390
 391 .TP
 392 \f3bytes_per_line\f1
 393 Number of bytes to show per line, unless '-s' option was specified
 394 on the command line. If not set, computed based on screen width
 395 (to the nearest less multiply of 0x10).
 396
 397
 398 .SH LICENSE
 399 .B hed
 400 is free software; you can redistribute it and/or modify
 401 it under the terms of version 2 of the GNU General Public License
 402 as published by the Free Software Foundation.
 403
 404 .SH AUTHOR
 405 .I hed
 406 was written by
 407 .B Petr Baudis
 408 <pasky@ucw.cz>.
 409 See file
 410 .I AUTHORS
 411 for a list of people contributing to this project.
 412 .P
 413 The homepage of hed can be found at
 414 .BI http://www.tesarici.cz/dev/hed/
 415
 416 .SH "SEE ALSO"
 417 .BR hexedit (1),
 418 .BR hexdump (1),
 419 .BR od (1)