usr.bin/hexdump/hexdump.1

   1 .\" Copyright (c) 1989, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)hexdump.1   8.2 (Berkeley) 4/18/94
  29 .\"
  30 .Dd June 29, 2020
  31 .Dt HEXDUMP 1
  32 .Os
  33 .Sh NAME
  34 .Nm hexdump , hd
  35 .Nd ASCII, decimal, hexadecimal, octal dump
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl bcCdovx
  39 .Op Fl e Ar format_string
  40 .Op Fl f Ar format_file
  41 .Op Fl n Ar length
  42 .Bk -words
  43 .Op Fl s Ar offset
  44 .Ek
  45 .Ar
  46 .Nm hd
  47 .Op Fl bcdovx
  48 .Op Fl e Ar format_string
  49 .Op Fl f Ar format_file
  50 .Op Fl n Ar length
  51 .Bk -words
  52 .Op Fl s Ar offset
  53 .Ek
  54 .Ar
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 utility is a filter which displays the specified files, or
  59 the standard input, if no files are specified, in a user specified
  60 format.
  61 .Pp
  62 The options are as follows:
  63 .Bl -tag -width indent
  64 .It Fl b
  65 .Em One-byte octal display .
  66 Display the input offset in hexadecimal, followed by sixteen
  67 space-separated, three column, zero-filled, bytes of input data,
  68 in octal, per line.
  69 .It Fl c
  70 .Em One-byte character display .
  71 Display the input offset in hexadecimal, followed by sixteen
  72 space-separated, three column, space-filled, characters of input
  73 data per line.
  74 .It Fl C
  75 .Em Canonical hex+ASCII display .
  76 Display the input offset in hexadecimal, followed by sixteen
  77 space-separated, two column, hexadecimal bytes, followed by the
  78 same sixteen bytes in %_p format enclosed in ``|'' characters.
  79 .Pp
  80 Calling the command
  81 .Nm hd
  82 implies this option.
  83 .It Fl d
  84 .Em Two-byte decimal display .
  85 Display the input offset in hexadecimal, followed by eight
  86 space-separated, five column, zero-filled, two-byte units
  87 of input data, in unsigned decimal, per line.
  88 .It Fl e Ar format_string
  89 Specify a format string to be used for displaying data.
  90 .It Fl f Ar format_file
  91 Specify a file that contains one or more newline separated format strings.
  92 Empty lines and lines whose first non-blank character is a hash mark
  93 .Pf ( Cm \&# )
  94 are ignored.
  95 .It Fl n Ar length
  96 Interpret only
  97 .Ar length
  98 bytes of input.
  99 .It Fl o
 100 .Em Two-byte octal display .
 101 Display the input offset in hexadecimal, followed by eight
 102 space-separated, six column, zero-filled, two byte quantities of
 103 input data, in octal, per line.
 104 .It Fl s Ar offset
 105 Skip
 106 .Ar offset
 107 bytes from the beginning of the input.
 108 By default,
 109 .Ar offset
 110 is interpreted as a decimal number.
 111 With a leading
 112 .Cm 0x
 113 or
 114 .Cm 0X ,
 115 .Ar offset
 116 is interpreted as a hexadecimal number,
 117 otherwise, with a leading
 118 .Cm 0 ,
 119 .Ar offset
 120 is interpreted as an octal number.
 121 Appending the character
 122 .Cm b ,
 123 .Cm k ,
 124 or
 125 .Cm m
 126 to
 127 .Ar offset
 128 causes it to be interpreted as a multiple of
 129 .Li 512 ,
 130 .Li 1024 ,
 131 or
 132 .Li 1048576 ,
 133 respectively.
 134 .It Fl v
 135 Cause
 136 .Nm
 137 to display all input data.
 138 Without the
 139 .Fl v
 140 option, any number of groups of output lines, which would be
 141 identical to the immediately preceding group of output lines (except
 142 for the input offsets), are replaced with a line comprised of a
 143 single asterisk.
 144 .It Fl x
 145 .Em Two-byte hexadecimal display .
 146 Display the input offset in hexadecimal, followed by eight, space
 147 separated, four column, zero-filled, two-byte quantities of input
 148 data, in hexadecimal, per line.
 149 .El
 150 .Pp
 151 For each input file,
 152 .Nm
 153 sequentially copies the input to standard output, transforming the
 154 data according to the format strings specified by the
 155 .Fl e
 156 and
 157 .Fl f
 158 options, in the order that they were specified.
 159 .Ss Formats
 160 A format string contains any number of format units, separated by
 161 whitespace.
 162 A format unit contains up to three items: an iteration count, a byte
 163 count, and a format.
 164 .Pp
 165 The iteration count is an optional positive integer, which defaults to
 166 one.
 167 Each format is applied iteration count times.
 168 .Pp
 169 The byte count is an optional positive integer.
 170 If specified it defines the number of bytes to be interpreted by
 171 each iteration of the format.
 172 .Pp
 173 If an iteration count and/or a byte count is specified, a single slash
 174 must be placed after the iteration count and/or before the byte count
 175 to disambiguate them.
 176 Any whitespace before or after the slash is ignored.
 177 .Pp
 178 The format is required and must be surrounded by double quote
 179 (" ") marks.
 180 It is interpreted as a fprintf-style format string (see
 181 .Xr fprintf 3 ) ,
 182 with the
 183 following exceptions:
 184 .Bl -bullet -offset indent
 185 .It
 186 An asterisk (*) may not be used as a field width or precision.
 187 .It
 188 A byte count or field precision
 189 .Em is
 190 required for each ``s'' conversion
 191 character (unlike the
 192 .Xr fprintf 3
 193 default which prints the entire string if the precision is unspecified).
 194 .It
 195 The conversion characters ``h'', ``l'', ``n'', ``p'' and ``q'' are
 196 not supported.
 197 .It
 198 The single character escape sequences
 199 described in the C standard are supported:
 200 .Bd -ragged -offset indent -compact
 201 .Bl -column <alert_character>
 202 .It "NUL        \e0"
 203 .It "<alert character>  \ea"
 204 .It "<backspace>        \eb"
 205 .It "<form-feed>        \ef"
 206 .It "<newline>  \en"
 207 .It "<carriage return>  \er"
 208 .It "<tab>      \et"
 209 .It "<vertical tab>     \ev"
 210 .El
 211 .Ed
 212 .El
 213 .Pp
 214 The
 215 .Nm
 216 utility also supports the following additional conversion strings:
 217 .Bl -tag -width Fl
 218 .It Cm \&_a Ns Op Cm dox
 219 Display the input offset, cumulative across input files, of the
 220 next byte to be displayed.
 221 The appended characters
 222 .Cm d ,
 223 .Cm o ,
 224 and
 225 .Cm x
 226 specify the display base
 227 as decimal, octal or hexadecimal respectively.
 228 .It Cm \&_A Ns Op Cm dox
 229 Identical to the
 230 .Cm \&_a
 231 conversion string except that it is only performed
 232 once, when all of the input data has been processed.
 233 .It Cm \&_c
 234 Output characters in the default character set.
 235 Nonprinting characters are displayed in three character, zero-padded
 236 octal, except for those representable by standard escape notation
 237 (see above),
 238 which are displayed as two character strings.
 239 .It Cm _p
 240 Output characters in the default character set.
 241 Nonprinting characters are displayed as a single
 242 .Dq Cm \&. .
 243 .It Cm _u
 244 Output US ASCII
 245 characters, with the exception that control characters are
 246 displayed using the following, lower-case, names.
 247 Characters greater than 0xff, hexadecimal, are displayed as hexadecimal
 248 strings.
 249 .Bl -column 000_nu 001_so 002_st 003_et 004_eo
 250 .It "000 NUL" Ta "001 SOH" Ta "002 STX" Ta "003 ETX" Ta "004 EOT" Ta "005 ENQ"
 251 .It "006 ACK" Ta "007 BEL" Ta "008 BS" Ta "009 HT" Ta "00A LF" Ta "00B VT"
 252 .It "00C FF" Ta "00D CR" Ta "00E\ SO" Ta "00F SI" Ta "010 DLE" Ta "011 DC1"
 253 .It "012 DC2" Ta "013 DC3" Ta "014 DC4" Ta "015\ NAK" Ta "016 SYN" Ta "017 ETB"
 254 .It "018 CAN" Ta "019 EM" Ta "01A SUB" Ta "01B ESC" Ta "01C FS" Ta "01D GS"
 255 .It "01E RS" Ta "01F US" Ta "07F DEL" Ta \& Ta \& Ta \&
 256 .El
 257 .El
 258 .Pp
 259 The default and supported byte counts for the conversion characters
 260 are as follows:
 261 .Bl -tag -width  "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
 262 .It Li \&%_c , \&%_p , \&%_u , \&%c
 263 One byte counts only.
 264 .It Xo
 265 .Li \&%d , \&%i , \&%o ,
 266 .Li \&%u , \&%X , \&%x
 267 .Xc
 268 Four byte default, one, two and four byte counts supported.
 269 .It Xo
 270 .Li \&%E , \&%e , \&%f ,
 271 .Li \&%G , \&%g
 272 .Xc
 273 Eight byte default, four and twelve byte counts supported.
 274 .El
 275 .Pp
 276 The amount of data interpreted by each format string is the sum of the
 277 data required by each format unit, which is the iteration count times the
 278 byte count, or the iteration count times the number of bytes required by
 279 the format if the byte count is not specified.
 280 .Pp
 281 The input is manipulated in ``blocks'', where a block is defined as the
 282 largest amount of data specified by any format string.
 283 Format strings interpreting less than an input block's worth of data,
 284 whose last format unit both interprets some number of bytes and does
 285 not have a specified iteration count, have the iteration count
 286 incremented until the entire input block has been processed or there
 287 is not enough data remaining in the block to satisfy the format string.
 288 .Pp
 289 If, either as a result of user specification or
 290 .Nm
 291 modifying
 292 the iteration count as described above, an iteration count is
 293 greater than one, no trailing whitespace characters are output
 294 during the last iteration.
 295 .Pp
 296 It is an error to specify a byte count as well as multiple conversion
 297 characters or strings unless all but one of the conversion characters
 298 or strings is
 299 .Cm \&_a
 300 or
 301 .Cm \&_A .
 302 .Pp
 303 If, as a result of the specification of the
 304 .Fl n
 305 option or end-of-file being reached, input data only partially
 306 satisfies a format string, the input block is zero-padded sufficiently
 307 to display all available data (i.e., any format units overlapping the
 308 end of data will display some number of the zero bytes).
 309 .Pp
 310 Further output by such format strings is replaced by an equivalent
 311 number of spaces.
 312 An equivalent number of spaces is defined as the number of spaces
 313 output by an
 314 .Cm s
 315 conversion character with the same field width
 316 and precision as the original conversion character or conversion
 317 string but with any
 318 .Dq Li \&+ ,
 319 .Dq \&\ \& ,
 320 .Dq Li \&#
 321 conversion flag characters
 322 removed, and referencing a NULL string.
 323 .Pp
 324 If no format strings are specified, the default display is equivalent
 325 to specifying the
 326 .Fl x
 327 option.
 328 .Sh EXIT STATUS
 329 .Ex -std hexdump hd
 330 .Sh EXAMPLES
 331 Dump input in canonical (hex+ASCII) form:
 332 .Bd -literal -offset indent
 333 $ echo "FreeBSD: The power to serve" | hexdump -C
 334 00000000  46 72 65 65 42 53 44 3a  20 54 68 65 20 70 6f 77  |FreeBSD: The pow|
 335 00000010  65 72 20 74 6f 20 73 65  72 76 65 0a              |er to serve.|
 336 0000001c
 337 .Ed
 338 .Pp
 339 Same as above but skipping the first 4 bytes of stdin and interpreting only 3
 340 bytes of input:
 341 .Bd -literal -offset indent
 342 $ echo "FreeBSD: The power to serve" | hexdump -C -s 4 -n 3
 343 00000004  42 53 44                                          |BSD|
 344 00000007
 345 .Ed
 346 .Pp
 347 Assuming a format file named
 348 .Pa format.txt
 349 with the following contents that specify a perusal format:
 350 .Bd -literal -offset indent
 351 "%06.6_ao "  12/1 "%3_u "
 352 "\et\et" "%_p "
 353 "\en"
 354 .Ed
 355 .Pp
 356 Dump input in canonical form using the format in
 357 .Pa format.txt :
 358 .Bd -literal -offset indent
 359 $ echo "FreeBSD" | hexdump -f format.txt -C
 360 000000   F   r   e   e   B   S   D  lf                          F r e e B S D .
 361 00000000  46 72 65 65 42 53 44 0a                           |FreeBSD.|
 362 00000008
 363 .Ed
 364 .Pp
 365 Assuming a format file named
 366 .Pa format.txt
 367 with the following contents that simulate the
 368 .Fl x
 369 option:
 370 .Bd -literal -offset indent
 371 "%07.7_Ax\en"
 372 "%07.7_ax  " 8/2 "%04x " "\en"
 373 .Ed
 374 .Pp
 375 Dump input in canonical form using the format in
 376 .Pa format.txt :
 377 .Bd -literal -offset indent
 378 $ echo "FreeBSD: The power to serve" | hexdump -f format.txt -C
 379 0000000  7246 6565 5342 3a44 5420 6568 7020 776f
 380 00000000  46 72 65 65 42 53 44 3a  20 54 68 65 20 70 6f 77  |FreeBSD: The pow|
 381 0000010  7265 7420 206f 6573 7672 0a65
 382 00000010  65 72 20 74 6f 20 73 65  72 76 65 0a              |er to serve.|
 383 0000001c
 384 .Ed
 385 .Sh SEE ALSO
 386 .Xr od 1