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