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 .TH HEXDUMP "1" "September 2011" "util-linux" "User Commands"
  35 .SH NAME
  36 hexdump \- display file contents in ascii, decimal, hexadecimal, or octal
  37 .SH SYNOPSIS
  38 .B hexdump
  39 [options] file [...]
  40 .SH DESCRIPTION
  41 The
  42 .B hexdump
  43 utility is a filter which displays the specified files, or
  44 standard input if no files are specified, in a user-specified
  45 format.
  46 .SH OPTIONS
  47 .TP
  48 .B \-b
  49 \fIOne-byte octal display\fR.  Display the input offset in hexadecimal,
  50 followed by sixteen space-separated, three-column, zero-filled bytes of input
  51 data, in octal, per line.
  52 .TP
  53 .B \-c
  54 \fIOne-byte character display\fR.  Display the input offset in hexadecimal,
  55 followed by sixteen space-separated, three-column, space-filled characters of
  56 input data per line.
  57 .TP
  58 .B \-C
  59 \fICanonical hex+ASCII display\fR.  Display the input offset in hexadecimal,
  60 followed by sixteen space-separated, two-column, hexadecimal bytes, followed
  61 by the same sixteen bytes in
  62 .B %_p
  63 format enclosed in
  64 .RB ' | '
  65 characters.
  66 .TP
  67 .B \-d
  68 \fITwo-byte decimal display\fR.  Display the input offset in hexadecimal,
  69 followed by eight space-separated, five-column, zero-filled, two-byte units
  70 of input data, in unsigned decimal, per line.
  71 .TP
  72 .BI \-e \ format_string
  73 Specify a format string to be used for displaying data.
  74 .TP
  75 .BI \-f \ format_file
  76 Specify a file that contains one or more newline separated format strings.
  77 Empty lines and lines whose first non-blank character is a hash mark (\&#)
  78 are ignored.
  79 .TP
  80 .BI \-n \ length
  81 Interpret only
  82 .I length
  83 bytes of input.
  84 .TP
  85 .B \-o
  86 \fITwo-byte octal display\fR.  Display the input offset in hexadecimal,
  87 followed by eight space-separated, six-column, zero-filled, two-byte
  88 quantities of input data, in octal, per line.
  89 .TP
  90 .BI \-s \ offset
  91 Skip
  92 .I offset
  93 bytes from the beginning of the input.  By default,
  94 .I offset
  95 is interpreted as a decimal number.  With a leading
  96 .B 0x
  97 or
  98 .BR 0X ,
  99 .I offset
 100 is interpreted as a hexadecimal number, otherwise, with a leading
 101 .BR 0 ,
 102 .I offset
 103 is interpreted as an octal number.  Appending the character
 104 .BR b ,
 105 .BR k ,
 106 or
 107 .B m
 108 to
 109 .I offset
 110 causes it to be interpreted as a multiple of
 111 .IR 512 ,
 112 .IR 1024 ,
 113 or
 114 .IR 1048576 ,
 115 respectively.
 116 .TP
 117 .B \-v
 118 The
 119 .B \-v
 120 option causes
 121 .B hexdump
 122 to display all input data.  Without the
 123 .B \-v
 124 option, any number of groups of output lines which would be identical to the
 125 immediately preceding group of output lines (except for the input offsets),
 126 are replaced with a line comprised of a single asterisk.
 127 .TP
 128 .B \-x
 129 \fITwo-byte hexadecimal display\fR.  Display the input offset in hexadecimal,
 130 followed by eight space-separated, four-column, zero-filled, two-byte
 131 quantities of input data, in hexadecimal, per line.
 132 .PP
 133 For each input file,
 134 .B hexdump
 135 sequentially copies the input to standard output, transforming the data
 136 according to the format strings specified by the
 137 .B \-e
 138 and
 139 .B \-f
 140 options, in the order that they were specified.
 141 .SH FORMATS
 142 A format string contains any number of format units, separated by whitespace.
 143 A format unit contains up to three items: an iteration count, a byte count,
 144 and a format.
 145 .PP
 146 The iteration count is an optional positive integer, which defaults to one.
 147 Each format is applied iteration count times.
 148 .PP
 149 The byte count is an optional positive integer.  If specified it defines the
 150 number of bytes to be interpreted by each iteration of the format.
 151 .PP
 152 If an iteration count and/or a byte count is specified, a single slash must
 153 be placed after the iteration count and/or before the byte count to
 154 disambiguate them.  Any whitespace before or after the slash is ignored.
 155 .PP
 156 The format is required and must be surrounded by double quote (" ") marks.
 157 It is interpreted as a fprintf-style format string (see
 158 .BR fprintf (3),
 159 with the following exceptions:
 160 .TP
 161 1.
 162 An asterisk (*) may not be used as a field width or precision.
 163 .TP
 164 2.
 165 A byte count or field precision
 166 .I is
 167 required for each
 168 .B s
 169 conversion character (unlike the
 170 .BR fprintf (3)
 171 default which prints the entire string if the precision is unspecified).
 172 .TP
 173 3.
 174 The conversion characters
 175 .BR h , \ l , \ n , \ p ,
 176 .RB  and \ q
 177 are not supported.
 178 .TP
 179 4.
 180 The single character escape sequences described in the C standard are
 181 supported:
 182 .PP
 183 .RS 13
 184 .PD 0
 185 .TP 21
 186 NULL
 187 \e0
 188 .TP
 189 <alert character>
 190 \ea
 191 .TP
 192 <backspace>
 193 \eb
 194 .TP
 195 <form-feed>
 196 \ef
 197 .TP
 198 <newline>
 199 \en
 200 .TP
 201 <carriage return>
 202 \er
 203 .TP
 204 <tab>
 205 \et
 206 .TP
 207 <vertical tab>
 208 \ev
 209 .PD
 210 .RE
 211 .PP
 212 .SS Conversion strings
 213 The
 214 .B hexdump
 215 utility also supports the following additional conversion strings.
 216 .TP
 217 .B \&_a[dox]
 218 Display the input offset, cumulative across input files, of the next byte to
 219 be displayed.  The appended characters
 220 .BR d ,
 221 .BR o ,
 222 and
 223 .B x
 224 specify the display base as decimal, octal or hexadecimal respectively.
 225 .TP
 226 .B \&_A[dox]
 227 Identical to the
 228 .B \&_a
 229 conversion string except that it is only performed once, when all of the
 230 input data has been processed.
 231 .TP
 232 .B \&_c
 233 Output characters in the default character set.  Nonprinting characters are
 234 displayed in three-character, zero-padded octal, except for those
 235 representable by standard escape notation (see above), which are displayed as
 236 two-character strings.
 237 .TP
 238 .B \&_p
 239 Output characters in the default character set.  Nonprinting characters are
 240 displayed as a single
 241 .RB ' \&. '.
 242 .TP
 243 .B \&_u
 244 Output US ASCII characters, with the exception that control characters are
 245 displayed using the following, lower-case, names.  Characters greater than
 246 0xff, hexadecimal, are displayed as hexadecimal strings.
 247 .PP
 248 .nf
 249           000 nul  001 soh  002 stx  003 etx  004 eot  005 enq
 250           006 ack  007 bel  008 bs   009 ht   00A lf   00B vt
 251           00C ff   00D cr   00E so   00F si   010 dle  011 dc1
 252           012 dc2  013 dc3  014 dc4  015 nak  016 syn  017 etb
 253           018 can  019 em   01A sub  01B esc  01C fs   01D gs
 254           01E rs   01F us   0FF del
 255 .nf
 256 .SS Counters
 257 The default and supported byte counts for the conversion characters
 258 are as follows:
 259 .TP
 260 .BR \&%_c , \ \&%_p , \ \&%_u , \ \&%c
 261 One byte counts only.
 262 .TP
 263 .BR \&%d , \ \&%i , \ \&%o , \ \&%u , \ \&%X , \ \&%x
 264 Four byte default, one, two and four byte counts supported.
 265 .TP
 266 .BR \&%E , \ \&%e , \ \&%f , \ \&%G , \ \&%g
 267 Eight byte default, four byte counts supported.
 268 .PP
 269 The amount of data interpreted by each format string is the sum of the data
 270 required by each format unit, which is the iteration count times the byte
 271 count, or the iteration count times the number of bytes required by the
 272 format if the byte count is not specified.
 273 .PP
 274 The input is manipulated in
 275 .IR blocks ,
 276 where a block is defined as the largest amount of data specified by any
 277 format string.  Format strings interpreting less than an input block's worth
 278 of data, whose last format unit both interprets some number of bytes and does
 279 not have a specified iteration count, have the iteration count incremented
 280 until the entire input block has been processed or there is not enough data
 281 remaining in the block to satisfy the format string.
 282 .PP
 283 If, either as a result of user specification or
 284 .B hexdump
 285 modifying the iteration count as described above, an iteration count is
 286 greater than one, no trailing whitespace characters are output during the
 287 last iteration.
 288 .PP
 289 It is an error to specify a byte count as well as multiple conversion
 290 characters or strings unless all but one of the conversion characters or
 291 strings is
 292 .B \&_a
 293 or
 294 .BR \&_A .
 295 .PP
 296 If, as a result of the specification of the
 297 .B \-n
 298 option or end-of-file being reached, input data only partially satisfies a
 299 format string, the input block is zero-padded sufficiently to display all
 300 available data (i.e. any format units overlapping the end of data will
 301 display some number of the zero bytes).
 302 .PP
 303 Further output by such format strings is replaced by an equivalent number of
 304 spaces.  An equivalent number of spaces is defined as the number of spaces
 305 output by an
 306 .B s
 307 conversion character with the same field width and precision as the original
 308 conversion character or conversion string but with any
 309 .RB ' \&+ ',
 310 \' \',
 311 .RB ' \&# '
 312 conversion flag characters 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 .B \-x
 317 option.
 318 .SH "EXIT STATUS"
 319 .B hexdump
 320 exits 0 on success and >0 if an error occurred.
 321 .SH EXAMPLES
 322 Display the input in perusal format:
 323 .nf
 324    "%06.6_ao "  12/1 "%3_u "
 325    "\et\et" "%_p "
 326    "\en"
 327 .nf
 328 .PP
 329 Implement the \-x option:
 330 .nf
 331    "%07.7_Ax\en"
 332    "%07.7_ax  " 8/2 "%04x " "\en"
 333 .nf
 334 .SH STANDARDS
 335 The
 336 .B hexdump
 337 utility is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
 338 .SH AVAILABILITY
 339 The hexdump command is part of the util-linux package and is available from
 340 .UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 341 Linux Kernel Archive
 342 .UE .