manual/util-linux/original/man1/hexdump.1

   1 '\" t
   2 .\"     Title: hexdump
   3 .\"    Author: [see the "AUTHOR(S)" section]
   4 .\" Generator: Asciidoctor 2.0.15
   5 .\"      Date: 2022-02-17
   6 .\"    Manual: User Commands
   7 .\"    Source: util-linux 2.38
   8 .\"  Language: English
   9 .\"
  10 .TH "HEXDUMP" "1" "2022-02-17" "util\-linux 2.38" "User Commands"
  11 .ie \n(.g .ds Aq \(aq
  12 .el       .ds Aq '
  13 .ss \n[.ss] 0
  14 .nh
  15 .ad l
  16 .de URL
  17 \fI\\$2\fP <\\$1>\\$3
  18 ..
  19 .als MTO URL
  20 .if \n[.g] \{\
  21 .  mso www.tmac
  22 .  am URL
  23 .    ad l
  24 .  .
  25 .  am MTO
  26 .    ad l
  27 .  .
  28 .  LINKSTYLE blue R < >
  29 .\}
  30 .SH "NAME"
  31 hexdump \- display file contents in hexadecimal, decimal, octal, or ascii
  32 .sp
  33 \fBhexdump\fP \fIoptions file\fP ...
  34 .sp
  35 \fBhd\fP \fIoptions file\fP ...
  36 .SH "DESCRIPTION"
  37 .sp
  38 The \fBhexdump\fP utility is a filter which displays the specified files, or standard input if no files are specified, in a user\-specified format.
  39 .SH "OPTIONS"
  40 .sp
  41 Below, the \fIlength\fP and \fIoffset\fP arguments may be followed by the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g., "K" has the same meaning as "KiB"), or the suffixes KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
  42 .sp
  43 \fB\-b\fP, \fB\-\-one\-byte\-octal\fP
  44 .RS 4
  45 \fIOne\-byte octal display\fP. Display the input offset in hexadecimal, followed by sixteen space\-separated, three\-column, zero\-filled bytes of input data, in octal, per line.
  46 .RE
  47 .sp
  48 \fB\-c\fP, \fB\-\-one\-byte\-char\fP
  49 .RS 4
  50 \fIOne\-byte character display\fP. Display the input offset in hexadecimal, followed by sixteen space\-separated, three\-column, space\-filled characters of input data per line.
  51 .RE
  52 .sp
  53 \fB\-C\fP, \fB\-\-canonical\fP
  54 .RS 4
  55 \fICanonical hex+ASCII display\fP. Display the input offset in hexadecimal, followed by sixteen space\-separated, two\-column, hexadecimal bytes, followed by the same sixteen bytes in \fB%_p\fP format enclosed in \fB|\fP characters. Invoking the program as \fBhd\fP implies this option.
  56 .RE
  57 .sp
  58 \fB\-d\fP, \fB\-\-two\-bytes\-decimal\fP
  59 .RS 4
  60 \fITwo\-byte decimal display\fP. Display the input offset in hexadecimal, followed by eight space\-separated, five\-column, zero\-filled, two\-byte units of input data, in unsigned decimal, per line.
  61 .RE
  62 .sp
  63 \fB\-e\fP, \fB\-\-format\fP \fIformat_string\fP
  64 .RS 4
  65 Specify a format string to be used for displaying data.
  66 .RE
  67 .sp
  68 \fB\-f\fP, \fB\-\-format\-file\fP \fIfile\fP
  69 .RS 4
  70 Specify a file that contains one or more newline\-separated format strings. Empty lines and lines whose first non\-blank character is a hash mark (#) are ignored.
  71 .RE
  72 .sp
  73 \fB\-L\fP, \fB\-\-color\fP[=\fIwhen\fP]
  74 .RS 4
  75 Accept color units for the output. The optional argument \fIwhen\fP can be \fBauto\fP, \fBnever\fP or \fBalways\fP. If the \fIwhen\fP argument is omitted, it defaults to \fBauto\fP. The colors can be disabled; for the current built\-in default see the \fB\-\-help\fP output. See also the \fBColors\fP subsection and the \fBCOLORS\fP section below.
  76 .RE
  77 .sp
  78 \fB\-n\fP, \fB\-\-length\fP \fIlength\fP
  79 .RS 4
  80 Interpret only \fIlength\fP bytes of input.
  81 .RE
  82 .sp
  83 \fB\-o\fP, \fB\-\-two\-bytes\-octal\fP
  84 .RS 4
  85 \fITwo\-byte octal display\fP. Display the input offset in hexadecimal, followed by eight space\-separated, six\-column, zero\-filled, two\-byte quantities of input data, in octal, per line.
  86 .RE
  87 .sp
  88 \fB\-s\fP, \fB\-\-skip\fP \fIoffset\fP
  89 .RS 4
  90 Skip \fIoffset\fP bytes from the beginning of the input.
  91 .RE
  92 .sp
  93 \fB\-v\fP, \fB\-\-no\-squeezing\fP
  94 .RS 4
  95 The \fB\-v\fP option causes \fBhexdump\fP to display all input data. Without the \fB\-v\fP option, any number of groups of output lines which would be identical to the immediately preceding group of output lines (except for the input offsets), are replaced with a line comprised of a single asterisk.
  96 .RE
  97 .sp
  98 \fB\-x\fP, \fB\-\-two\-bytes\-hex\fP
  99 .RS 4
 100 \fITwo\-byte hexadecimal display\fP. Display the input offset in hexadecimal, followed by eight space\-separated, four\-column, zero\-filled, two\-byte quantities of input data, in hexadecimal, per line.
 101 .RE
 102 .sp
 103 \fB\-h\fP, \fB\-\-help\fP
 104 .RS 4
 105 Display help text and exit.
 106 .RE
 107 .sp
 108 \fB\-V\fP, \fB\-\-version\fP
 109 .RS 4
 110 Print version and exit.
 111 .RE
 112 .sp
 113 For each input file, \fBhexdump\fP sequentially copies the input to standard output, transforming the data according to the format strings specified by the \fB\-e\fP and \fB\-f\fP options, in the order that they were specified.
 114 .SH "FORMATS"
 115 .sp
 116 A format string contains any number of format units, separated by whitespace. A format unit contains up to three items: an iteration count, a byte count, and a format.
 117 .sp
 118 The iteration count is an optional positive integer, which defaults to one. Each format is applied iteration count times.
 119 .sp
 120 The byte count is an optional positive integer. If specified it defines the number of bytes to be interpreted by each iteration of the format.
 121 .sp
 122 If an iteration count and/or a byte count is specified, a single slash must be placed after the iteration count and/or before the byte count to disambiguate them. Any whitespace before or after the slash is ignored.
 123 .sp
 124 The format is required and must be surrounded by double quote (" ") marks. It is interpreted as a fprintf\-style format string (see \fBfprintf\fP(3)), with the following exceptions:
 125 .sp
 126 1.
 127 .RS 4
 128 An asterisk (*) may not be used as a field width or precision.
 129 .RE
 130 .sp
 131 2.
 132 .RS 4
 133 A byte count or field precision \fIis\fP required for each \fBs\fP conversion character (unlike the \fBfprintf\fP(3) default which prints the entire string if the precision is unspecified).
 134 .RE
 135 .sp
 136 3.
 137 .RS 4
 138 The conversion characters \fBh\fP, \fBl\fP, \fBn\fP, \fBp\fP, and \fBq\fP are not supported.
 139 .RE
 140 .sp
 141 4.
 142 .RS 4
 143 The single character escape sequences described in the C standard are supported:
 144 .RE
 145 .RS 3
 146 .ll -.6i
 147 .TS
 148 allbox tab(:);
 149 lt lt.
 150 T{
 151 .sp
 152 NULL
 153 T}:T{
 154 .sp
 155 \(rs0
 156 T}
 157 T{
 158 .sp
 159 <alert character>
 160 T}:T{
 161 .sp
 162 \(rsa
 163 T}
 164 T{
 165 .sp
 166 <backspace>
 167 T}:T{
 168 .sp
 169 \(rsb
 170 T}
 171 T{
 172 .sp
 173 <form\-feed>
 174 T}:T{
 175 .sp
 176 \(rsf
 177 T}
 178 T{
 179 .sp
 180 <newline>
 181 T}:T{
 182 .sp
 183 \(rsn
 184 T}
 185 T{
 186 .sp
 187 <carriage return>
 188 T}:T{
 189 .sp
 190 \(rsr
 191 T}
 192 T{
 193 .sp
 194 <tab>
 195 T}:T{
 196 .sp
 197 \(rst
 198 T}
 199 T{
 200 .sp
 201 <vertical tab>
 202 T}:T{
 203 .sp
 204 \(rsv
 205 T}
 206 .TE
 207 .sp
 208 .br
 209 .RE
 210 .ll
 211 .SS "Conversion strings"
 212 .sp
 213 The \fBhexdump\fP utility also supports the following additional conversion strings.
 214 .sp
 215 \fB_a[dox]\fP
 216 .RS 4
 217 Display the input offset, cumulative across input files, of the next byte to be displayed. The appended characters \fBd\fP, \fBo\fP, and \fBx\fP specify the display base as decimal, octal or hexadecimal respectively.
 218 .RE
 219 .sp
 220 \fB_A[dox]\fP
 221 .RS 4
 222 Almost identical to the \fB_a\fP conversion string except that it is only performed once, when all of the input data has been processed.
 223 .RE
 224 .sp
 225 \fB_c\fP
 226 .RS 4
 227 Output characters in the default character set. Non\-printing characters are displayed in three\-character, zero\-padded octal, except for those representable by standard escape notation (see above), which are displayed as two\-character strings.
 228 .RE
 229 .sp
 230 \fB_p\fP
 231 .RS 4
 232 Output characters in the default character set. Non\-printing characters are displayed as a single \(aq\fB.\fP\(aq.
 233 .RE
 234 .sp
 235 \fB_u\fP
 236 .RS 4
 237 Output US ASCII characters, with the exception that control characters are displayed using the following, lower\-case, names. Characters greater than 0xff, hexadecimal, are displayed as hexadecimal strings.
 238 .RE
 239 .RS 3
 240 .ll -.6i
 241 .TS
 242 allbox tab(:);
 243 lt lt lt lt lt lt.
 244 T{
 245 .sp
 246 000 nul
 247 T}:T{
 248 .sp
 249 001 soh
 250 T}:T{
 251 .sp
 252 002 stx
 253 T}:T{
 254 .sp
 255 003 etx
 256 T}:T{
 257 .sp
 258 004 eot
 259 T}:T{
 260 .sp
 261 005 enq
 262 T}
 263 T{
 264 .sp
 265 006 ack
 266 T}:T{
 267 .sp
 268 007 bel
 269 T}:T{
 270 .sp
 271 008 bs
 272 T}:T{
 273 .sp
 274 009 ht
 275 T}:T{
 276 .sp
 277 00A lf
 278 T}:T{
 279 .sp
 280 00B vt
 281 T}
 282 T{
 283 .sp
 284 00C ff
 285 T}:T{
 286 .sp
 287 00D cr
 288 T}:T{
 289 .sp
 290 00E so
 291 T}:T{
 292 .sp
 293 00F si
 294 T}:T{
 295 .sp
 296 010 dle
 297 T}:T{
 298 .sp
 299 011 dc1
 300 T}
 301 T{
 302 .sp
 303 012 dc2
 304 T}:T{
 305 .sp
 306 013 dc3
 307 T}:T{
 308 .sp
 309 014 dc4
 310 T}:T{
 311 .sp
 312 015 nak
 313 T}:T{
 314 .sp
 315 016 syn
 316 T}:T{
 317 .sp
 318 017 etb
 319 T}
 320 T{
 321 .sp
 322 018 can
 323 T}:T{
 324 .sp
 325 019 em
 326 T}:T{
 327 .sp
 328 01A sub
 329 T}:T{
 330 .sp
 331 01B esc
 332 T}:T{
 333 .sp
 334 01C fs
 335 T}:T{
 336 .sp
 337 01D gs
 338 T}
 339 T{
 340 .sp
 341 01E rs
 342 T}:T{
 343 .sp
 344 01F us
 345 T}:T{
 346 .sp
 347 0FF del
 348 T}:T{
 349 .sp
 350
 351 T}:T{
 352 .sp
 353
 354 T}:T{
 355 .sp
 356
 357 T}
 358 .TE
 359 .sp
 360 .br
 361 .RE
 362 .ll
 363 .SS "Colors"
 364 .sp
 365 When put at the end of a format specifier, \fBhexdump\fP highlights the respective string with the color specified. Conditions, if present, are evaluated prior to highlighting.
 366 .sp
 367 \fB_L[color_unit_1,color_unit_2,...,color_unit_n]\fP
 368 .sp
 369 The full syntax of a color unit is as follows:
 370 .sp
 371 \fB[!]COLOR[:VALUE][@OFFSET_START[\-END]]\fP
 372 .sp
 373 \fB!\fP
 374 .RS 4
 375 Negate the condition. Please note that it only makes sense to negate a unit if both a value/string and an offset are specified. In that case the respective output string will be highlighted if and only if the value/string does not match the one at the offset.
 376 .RE
 377 .sp
 378 \fBCOLOR\fP
 379 .RS 4
 380 One of the 8 basic shell colors.
 381 .RE
 382 .sp
 383 \fBVALUE\fP
 384 .RS 4
 385 A value to be matched specified in hexadecimal, or octal base, or as a string. Please note that the usual C escape sequences are not interpreted by \fBhexdump\fP inside the color_units.
 386 .RE
 387 .sp
 388 \fBOFFSET\fP
 389 .RS 4
 390 An offset or an offset range at which to check for a match. Please note that lone OFFSET_START uses the same value as END offset.
 391 .RE
 392 .SS "Counters"
 393 .sp
 394 The default and supported byte counts for the conversion characters are as follows:
 395 .sp
 396 \fB%_c\fP, \fB%_p\fP, \fB%_u\fP, \fB%c\fP
 397 .RS 4
 398 One byte counts only.
 399 .RE
 400 .sp
 401 \fB%d\fP, \fB%i\fP, \fB%o\fP, \fB%u\fP, \fB%X\fP, \fB%x\fP
 402 .RS 4
 403 Four byte default, one, two and four byte counts supported.
 404 .RE
 405 .sp
 406 \fB%E\fP, \fB%e\fP, \fB%f\fP, \fB%G\fP, \fB%g\fP
 407 .RS 4
 408 Eight byte default, four byte counts supported.
 409 .RE
 410 .sp
 411 The amount of data interpreted by each format string is the sum of the data required by each format unit, which is the iteration count times the byte count, or the iteration count times the number of bytes required by the format if the byte count is not specified.
 412 .sp
 413 The input is manipulated in \fIblocks\fP, where a block is defined as the largest amount of data specified by any format string. Format strings interpreting less than an input block\(cqs worth of data, whose last format unit both interprets some number of bytes and does not have a specified iteration count, have the iteration count incremented until the entire input block has been processed or there is not enough data remaining in the block to satisfy the format string.
 414 .sp
 415 If, either as a result of user specification or \fBhexdump\fP modifying the iteration count as described above, an iteration count is greater than one, no trailing whitespace characters are output during the last iteration.
 416 .sp
 417 It is an error to specify a byte count as well as multiple conversion characters or strings unless all but one of the conversion characters or strings is \fB_a\fP or \fB_A\fP.
 418 .sp
 419 If, as a result of the specification of the \fB\-n\fP option or end\-of\-file being reached, input data only partially satisfies a format string, the input block is zero\-padded sufficiently to display all available data (i.e., any format units overlapping the end of data will display some number of the zero bytes).
 420 .sp
 421 Further output by such format strings is replaced by an equivalent number of spaces. An equivalent number of spaces is defined as the number of spaces output by an \fBs\fP conversion character with the same field width and precision as the original conversion character or conversion string but with any \(aq\fB+\fP\(aq, \(aq \(aq, \(aq\fB#\fP\(aq conversion flag characters removed, and referencing a NULL string.
 422 .sp
 423 If no format strings are specified, the default display is very similar to the \fB\-x\fP output format (the \fB\-x\fP option causes more space to be used between format units than in the default output).
 424 .SH "EXIT STATUS"
 425 .sp
 426 \fBhexdump\fP exits 0 on success and > 0 if an error occurred.
 427 .SH "CONFORMING TO"
 428 .sp
 429 The \fBhexdump\fP utility is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
 430 .SH "EXAMPLES"
 431 .sp
 432 Display the input in perusal format:
 433 .sp
 434 .if n .RS 4
 435 .nf
 436 .fam C
 437    "%06.6_ao "  12/1 "%3_u "
 438    "\(rst" "%_p "
 439    "\(rsn"
 440 .fam
 441 .fi
 442 .if n .RE
 443 .sp
 444 Implement the \fB\-x\fP option:
 445 .sp
 446 .if n .RS 4
 447 .nf
 448 .fam C
 449    "%07.7_Ax\(rsn"
 450    "%07.7_ax  " 8/2 "%04x " "\(rsn"
 451 .fam
 452 .fi
 453 .if n .RE
 454 .sp
 455 MBR Boot Signature example: Highlight the addresses cyan and the bytes at offsets 510 and 511 green if their value is 0xAA55, red otherwise.
 456 .sp
 457 .if n .RS 4
 458 .nf
 459 .fam C
 460    "%07.7_Ax_L[cyan]\(rsn"
 461    "%07.7_ax_L[cyan]  " 8/2 "   %04x_L[green:0xAA55@510\-511,!red:0xAA55@510\-511] " "\(rsn"
 462 .fam
 463 .fi
 464 .if n .RE
 465 .SH "COLORS"
 466 .sp
 467 The output colorization is implemented by \fBterminal\-colors.d\fP(5) functionality.
 468 Implicit coloring can be disabled by an empty file
 469 .RS 3
 470 .ll -.6i
 471 .sp
 472 \fI/etc/terminal\-colors.d/hexdump.disable\fP
 473 .br
 474 .RE
 475 .ll
 476 .sp
 477 for the \fBhexdump\fP command or for all tools by
 478 .RS 3
 479 .ll -.6i
 480 .sp
 481 \fI/etc/terminal\-colors.d/disable\fP
 482 .br
 483 .RE
 484 .ll
 485 .sp
 486 The user\-specific \fI$XDG_CONFIG_HOME/terminal\-colors.d\fP
 487 or \fI$HOME/.config/terminal\-colors.d\fP overrides the global setting.
 488 .sp
 489 Note that the output colorization may be enabled by default, and in this case
 490 \fIterminal\-colors.d\fP directories do not have to exist yet.
 491 .SH "REPORTING BUGS"
 492 .sp
 493 For bug reports, use the issue tracker at \c
 494 .URL "https://github.com/util\-linux/util\-linux/issues" "" "."
 495 .SH "AVAILABILITY"
 496 .sp
 497 The \fBhexdump\fP command is part of the util\-linux package which can be downloaded from \c
 498 .URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."