text-utils/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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     from: @(#)hexdump.1     8.2 (Berkeley) 4/18/94
  33 .\"
  34 .Dd April 18, 1994
  35 .Dt HEXDUMP 1
  36 .Os
  37 .Sh NAME
  38 .Nm hexdump
  39 .Nd ascii, decimal, hexadecimal, octal dump
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl bcCdovx
  43 .Bk -words
  44 .Op Fl e Ar format_string
  45 .Ek
  46 .Bk -words
  47 .Op Fl f Ar format_file
  48 .Ek
  49 .Bk -words
  50 .Op Fl n Ar length
  51 .Ek
  52 .Bk -words
  53 .Op Fl s Ar skip
  54 .Ek
  55 .Ar file ...
  56 .Sh DESCRIPTION
  57 The hexdump utility is a filter which displays the specified files, or
  58 the standard input, if no files are specified, in a user specified
  59 format.
  60 .Pp
  61 The options are as follows:
  62 .Bl -tag -width Fl
  63 .It Fl b
  64 .Em One-byte octal display .
  65 Display the input offset in hexadecimal, followed by sixteen
  66 space-separated, three column, zero-filled, bytes of input data,
  67 in octal, per line.
  68 .It Fl c
  69 .Em One-byte character display .
  70 Display the input offset in hexadecimal, followed by sixteen
  71 space-separated, three column, space-filled, characters of input
  72 data per line.
  73 .It Fl C
  74 .Em Canonical hex+ASCII display .
  75 Display the input offset in hexadecimal, followed by sixteen
  76 space-separated, two column, hexadecimal bytes, followed by the
  77 same sixteen bytes in %_p format enclosed in ``|'' characters.
  78 .It Fl d
  79 .Em Two-byte decimal display .
  80 Display the input offset in hexadecimal, followed by eight
  81 space-separated, five column, zero-filled, two-byte units
  82 of input data, in unsigned decimal, per line.
  83 .It Fl e Ar format_string
  84 Specify a format string to be used for displaying data.
  85 .It Fl f Ar format_file
  86 Specify a file that contains one or more newline separated format strings.
  87 Empty lines and lines whose first non-blank character is a hash mark
  88 .Pf ( Cm \&# )
  89 are ignored.
  90 .It Fl n Ar length
  91 Interpret only
  92 .Ar length
  93 bytes of input.
  94 .It Fl o
  95 .Em Two-byte octal display .
  96 Display the input offset in hexadecimal, followed by eight
  97 space-separated, six column, zero-filled, two byte quantities of
  98 input data, in octal, per line.
  99 .It Fl s Ar offset
 100 Skip
 101 .Ar offset
 102 bytes from the beginning of the input.
 103 By default,
 104 .Ar offset
 105 is interpreted as a decimal number.
 106 With a leading
 107 .Cm 0x
 108 or
 109 .Cm 0X ,
 110 .Ar offset
 111 is interpreted as a hexadecimal number,
 112 otherwise, with a leading
 113 .Cm 0 ,
 114 .Ar offset
 115 is interpreted as an octal number.
 116 Appending the character
 117 .Cm b ,
 118 .Cm k ,
 119 or
 120 .Cm m
 121 to
 122 .Ar offset
 123 causes it to be interpreted as a multiple of
 124 .Li 512 ,
 125 .Li 1024 ,
 126 or
 127 .Li 1048576 ,
 128 respectively.
 129 .It Fl v
 130 The
 131 .Fl v
 132 option causes hexdump to display all input data.
 133 Without the
 134 .Fl v
 135 option, any number of groups of output lines, which would be
 136 identical to the immediately preceding group of output lines (except
 137 for the input offsets), are replaced with a line comprised of a
 138 single asterisk.
 139 .It Fl x
 140 .Em Two-byte hexadecimal display .
 141 Display the input offset in hexadecimal, followed by eight, space
 142 separated, four column, zero-filled, two-byte quantities of input
 143 data, in hexadecimal, per line.
 144 .El
 145 .Pp
 146 For each input file,
 147 .Nm
 148 sequentially copies the input to standard output, transforming the
 149 data according to the format strings specified by the
 150 .Fl e
 151 and
 152 .Fl f
 153 options, in the order that they were specified.
 154 .Ss Formats
 155 A format string contains any number of format units, separated by
 156 whitespace.
 157 A format unit contains up to three items: an iteration count, a byte
 158 count, and a format.
 159 .Pp
 160 The iteration count is an optional positive integer, which defaults to
 161 one.
 162 Each format is applied iteration count times.
 163 .Pp
 164 The byte count is an optional positive integer.
 165 If specified it defines the number of bytes to be interpreted by
 166 each iteration of the format.
 167 .Pp
 168 If an iteration count and/or a byte count is specified, a single slash
 169 must be placed after the iteration count and/or before the byte count
 170 to disambiguate them.
 171 Any whitespace before or after the slash is ignored.
 172 .Pp
 173 The format is required and must be surrounded by double quote
 174 (" ") marks.
 175 It is interpreted as a fprintf-style format string (see
 176 .Xr fprintf 3 ) ,
 177 with the
 178 following exceptions:
 179 .Bl -bullet -offset indent
 180 .It
 181 An asterisk (*) may not be used as a field width or precision.
 182 .It
 183 A byte count or field precision
 184 .Em is
 185 required for each ``s'' conversion
 186 character (unlike the
 187 .Xr fprintf 3
 188 default which prints the entire string if the precision is unspecified).
 189 .It
 190 The conversion characters ``h'', ``l'', ``n'', ``p'' and ``q'' are
 191 not supported.
 192 .It
 193 The single character escape sequences
 194 described in the C standard are supported:
 195 .Bd -ragged -offset indent -compact
 196 .Bl -column <alert_character>
 197 .It NUL \e0
 198 .It <alert character>   \ea
 199 .It <backspace> \eb
 200 .It <form-feed> \ef
 201 .It <newline>   \en
 202 .It <carriage return>   \er
 203 .It <tab>       \et
 204 .It <vertical tab>      \ev
 205 .El
 206 .Ed
 207 .El
 208 .Pp
 209 Hexdump also supports the following additional conversion strings:
 210 .Bl -tag -width Fl
 211 .It Cm \&_a Ns Op Cm dox
 212 Display the input offset, cumulative across input files, of the
 213 next byte to be displayed.
 214 The appended characters
 215 .Cm d ,
 216 .Cm o ,
 217 and
 218 .Cm x
 219 specify the display base
 220 as decimal, octal or hexadecimal respectively.
 221 .It Cm \&_A Ns Op Cm dox
 222 Identical to the
 223 .Cm \&_a
 224 conversion string except that it is only performed
 225 once, when all of the input data has been processed.
 226 .It Cm \&_c
 227 Output characters in the default character set.
 228 Nonprinting characters are displayed in three character, zero-padded
 229 octal, except for those representable by standard escape notation
 230 (see above),
 231 which are displayed as two character strings.
 232 .It Cm _p
 233 Output characters in the default character set.
 234 Nonprinting characters are displayed as a single
 235 .Dq Cm \&. .
 236 .It Cm _u
 237 Output US ASCII characters, with the exception that control characters are
 238 displayed using the following, lower-case, names.
 239 Characters greater than 0xff, hexadecimal, are displayed as hexadecimal
 240 strings.
 241 .Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
 242 .It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
 243 .It \&006\ ack\t007\ bel\t008\ bs\t009\ ht\t00A\ lf\t00B\ vt
 244 .It \&00C\ ff\t00D\ cr\t00E\ so\t00F\ si\t010\ dle\t011\ dc1
 245 .It \&012\ dc2\t013\ dc3\t014\ dc4\t015\ nak\t016\ syn\t017\ etb
 246 .It \&018\ can\t019\ em\t01A\ sub\t01B\ esc\t01C\ fs\t01D\ gs
 247 .It \&01E\ rs\t01F\ us\t0FF\ del
 248 .El
 249 .El
 250 .Pp
 251 The default and supported byte counts for the conversion characters
 252 are as follows:
 253 .Bl -tag -width  "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
 254 .It Li \&%_c , \&%_p , \&%_u , \&%c
 255 One byte counts only.
 256 .It Xo
 257 .Li \&%d , \&%i , \&%o ,
 258 .Li \&%u , \&%X , \&%x
 259 .Xc
 260 Four byte default, one, two and four byte counts supported.
 261 .It Xo
 262 .Li \&%E , \&%e , \&%f ,
 263 .Li \&%G , \&%g
 264 .Xc
 265 Eight byte default, four byte counts supported.
 266 .El
 267 .Pp
 268 The amount of data interpreted by each format string is the sum of the
 269 data required by each format unit, which is the iteration count times the
 270 byte count, or the iteration count times the number of bytes required by
 271 the format if the byte count is not specified.
 272 .Pp
 273 The input is manipulated in ``blocks'', where a block is defined as the
 274 largest amount of data specified by any format string.
 275 Format strings interpreting less than an input block's worth of data,
 276 whose last format unit both interprets some number of bytes and does
 277 not have a specified iteration count, have the iteration count
 278 incremented until the entire input block has been processed or there
 279 is not enough data remaining in the block to satisfy the format string.
 280 .Pp
 281 If, either as a result of user specification or hexdump modifying
 282 the iteration count as described above, an iteration count is
 283 greater than one, no trailing whitespace characters are output
 284 during the last iteration.
 285 .Pp
 286 It is an error to specify a byte count as well as multiple conversion
 287 characters or strings unless all but one of the conversion characters
 288 or strings is
 289 .Cm \&_a
 290 or
 291 .Cm \&_A .
 292 .Pp
 293 If, as a result of the specification of the
 294 .Fl n
 295 option or end-of-file being reached, input data only partially
 296 satisfies a format string, the input block is zero-padded sufficiently
 297 to display all available data (i.e. any format units overlapping the
 298 end of data will display some number of the zero bytes).
 299 .Pp
 300 Further output by such format strings is replaced by an equivalent
 301 number of spaces.
 302 An equivalent number of spaces is defined as the number of spaces
 303 output by an
 304 .Cm s
 305 conversion character with the same field width
 306 and precision as the original conversion character or conversion
 307 string but with any
 308 .Dq Li \&+ ,
 309 .Dq \&\ \& ,
 310 .Dq Li \&#
 311 conversion flag characters
 312 removed, and referencing a NULL string.
 313 .Pp
 314 If no format strings are specified, the default display is equivalent
 315 to specifying the
 316 .Fl x
 317 option.
 318 .Pp
 319 .Nm
 320 exits 0 on success and >0 if an error occurred.
 321 .Sh EXAMPLES
 322 Display the input in perusal format:
 323 .Bd -literal -offset indent
 324 "%06.6_ao "  12/1 "%3_u "
 325 "\et\et" "%_p "
 326 "\en"
 327 .Ed
 328 .Pp
 329 Implement the \-x option:
 330 .Bd -literal -offset indent
 331 "%07.7_Ax\en"
 332 "%07.7_ax  " 8/2 "%04x " "\en"
 333 .Ed
 334 .Sh STANDARDS
 335 The
 336 .Nm
 337 utility is expected to be
 338 .St -p1003.2
 339 compatible.
 340 .Sh AVAILABILITY
 341 The hexdump command is part of the util-linux-ng package and is available from
 342 ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.