]>
Commit | Line | Data |
---|---|---|
6dbe3af9 KZ |
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 | .\" | |
3a60b1c2 | 32 | .\" @(#)hexdump.1 8.2 (Berkeley) 4/18/94 |
6dbe3af9 | 33 | .\" |
cdeb4292 | 34 | .TH HEXDUMP "1" "April 2013" "util-linux" "User Commands" |
7570e15a | 35 | .SH NAME |
07990fdc | 36 | hexdump \- display file contents in hexadecimal, decimal, octal, or ascii |
7570e15a SK |
37 | .SH SYNOPSIS |
38 | .B hexdump | |
1f94a78c | 39 | .RI [options] " file" ... |
7570e15a | 40 | .SH DESCRIPTION |
5bcd986e | 41 | The |
7570e15a | 42 | .B hexdump |
5bcd986e BS |
43 | utility is a filter which displays the specified files, or |
44 | standard input if no files are specified, in a user-specified | |
6dbe3af9 | 45 | format. |
7570e15a | 46 | .SH OPTIONS |
1f94a78c BS |
47 | Below, the \fIlength\fR and \fIoffset\fR arguments may be followed by the multiplicative |
48 | suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB | |
49 | (the "iB" is optional, e.g. "K" has the same meaning as "KiB"), or the suffixes | |
50 | KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB. | |
7570e15a | 51 | .TP |
cdeb4292 | 52 | \fB\-b\fR, \fB\-\-one\-byte\-octal\fR |
7570e15a SK |
53 | \fIOne-byte octal display\fR. Display the input offset in hexadecimal, |
54 | followed by sixteen space-separated, three-column, zero-filled bytes of input | |
55 | data, in octal, per line. | |
56 | .TP | |
cdeb4292 | 57 | \fB\-c\fR, \fB\-\-one\-byte\-char\fR |
7570e15a SK |
58 | \fIOne-byte character display\fR. Display the input offset in hexadecimal, |
59 | followed by sixteen space-separated, three-column, space-filled characters of | |
60 | input data per line. | |
61 | .TP | |
cdeb4292 | 62 | \fB\-C\fR, \fB\-\-canonical\fR |
7570e15a SK |
63 | \fICanonical hex+ASCII display\fR. Display the input offset in hexadecimal, |
64 | followed by sixteen space-separated, two-column, hexadecimal bytes, followed | |
65 | by the same sixteen bytes in | |
66 | .B %_p | |
67 | format enclosed in | |
68 | .RB ' | ' | |
69 | characters. | |
70 | .TP | |
cdeb4292 | 71 | \fB\-d\fR, \fB\-\-two\-bytes\-decimal\fR |
7570e15a SK |
72 | \fITwo-byte decimal display\fR. Display the input offset in hexadecimal, |
73 | followed by eight space-separated, five-column, zero-filled, two-byte units | |
6dbe3af9 | 74 | of input data, in unsigned decimal, per line. |
7570e15a | 75 | .TP |
cdeb4292 | 76 | \fB\-e\fR, \fB\-\-format\fR \fIformat_string\fR |
6dbe3af9 | 77 | Specify a format string to be used for displaying data. |
7570e15a | 78 | .TP |
1f94a78c BS |
79 | \fB\-f\fR, \fB\-\-format\-file\fR \fIfile\fR |
80 | Specify a file that contains one or more newline-separated format strings. | |
7570e15a | 81 | Empty lines and lines whose first non-blank character is a hash mark (\&#) |
6dbe3af9 | 82 | are ignored. |
7570e15a | 83 | .TP |
1f94a78c | 84 | \fB\-L\fR, \fB\-\-color\fR[=\fIwhen\fR] |
5d51dc2a | 85 | Accept color units for the output. The optional argument \fIwhen\fP |
1f94a78c | 86 | can be \fBauto\fR, \fBnever\fR or \fBalways\fR. If the \fIwhen\fR argument is omitted, |
e8cf378e BS |
87 | it defaults to \fBauto\fR. The colors can be disabled; for the current built-in default |
88 | see the \fB\-\-help\fR output. See also the \fBColors\fR subsection and | |
89 | the \fBCOLORS\fR section below. | |
1f94a78c | 90 | .TP |
cdeb4292 | 91 | \fB\-n\fR, \fB\-\-length\fR \fIlength\fR |
6dbe3af9 | 92 | Interpret only |
7570e15a | 93 | .I length |
6dbe3af9 | 94 | bytes of input. |
7570e15a | 95 | .TP |
cdeb4292 | 96 | \fB\-o\fR, \fB\-\-two\-bytes\-octal\fR |
7570e15a SK |
97 | \fITwo-byte octal display\fR. Display the input offset in hexadecimal, |
98 | followed by eight space-separated, six-column, zero-filled, two-byte | |
99 | quantities of input data, in octal, per line. | |
100 | .TP | |
cdeb4292 | 101 | \fB\-s\fR, \fB\-\-skip\fR \fIoffset\fR |
6dbe3af9 | 102 | Skip |
7570e15a | 103 | .I offset |
6ad533db | 104 | bytes from the beginning of the input. |
7570e15a | 105 | .TP |
cdeb4292 | 106 | \fB\-v\fR, \fB\-\-no\-squeezing\fR |
6dbe3af9 | 107 | The |
7570e15a | 108 | .B \-v |
5bcd986e | 109 | option causes |
7570e15a SK |
110 | .B hexdump |
111 | to display all input data. Without the | |
112 | .B \-v | |
113 | option, any number of groups of output lines which would be identical to the | |
114 | immediately preceding group of output lines (except for the input offsets), | |
115 | are replaced with a line comprised of a single asterisk. | |
116 | .TP | |
cdeb4292 | 117 | \fB\-x\fR, \fB\-\-two\-bytes\-hex\fR |
7570e15a SK |
118 | \fITwo-byte hexadecimal display\fR. Display the input offset in hexadecimal, |
119 | followed by eight space-separated, four-column, zero-filled, two-byte | |
120 | quantities of input data, in hexadecimal, per line. | |
07990fdc BS |
121 | .TP |
122 | .BR \-V , " \-\-version" | |
123 | Display version information and exit. | |
124 | .TP | |
125 | .BR \-h , " \-\-help" | |
126 | Display help text and exit. | |
7570e15a | 127 | .PP |
6dbe3af9 | 128 | For each input file, |
7570e15a SK |
129 | .B hexdump |
130 | sequentially copies the input to standard output, transforming the data | |
131 | according to the format strings specified by the | |
132 | .B \-e | |
6dbe3af9 | 133 | and |
7570e15a | 134 | .B \-f |
6dbe3af9 | 135 | options, in the order that they were specified. |
7570e15a SK |
136 | .SH FORMATS |
137 | A format string contains any number of format units, separated by whitespace. | |
138 | A format unit contains up to three items: an iteration count, a byte count, | |
139 | and a format. | |
140 | .PP | |
141 | The iteration count is an optional positive integer, which defaults to one. | |
6dbe3af9 | 142 | Each format is applied iteration count times. |
7570e15a SK |
143 | .PP |
144 | The byte count is an optional positive integer. If specified it defines the | |
145 | number of bytes to be interpreted by each iteration of the format. | |
146 | .PP | |
147 | If an iteration count and/or a byte count is specified, a single slash must | |
148 | be placed after the iteration count and/or before the byte count to | |
149 | disambiguate them. Any whitespace before or after the slash is ignored. | |
150 | .PP | |
151 | The format is required and must be surrounded by double quote (" ") marks. | |
6dbe3af9 | 152 | It is interpreted as a fprintf-style format string (see |
7570e15a SK |
153 | .BR fprintf (3), |
154 | with the following exceptions: | |
155 | .TP | |
156 | 1. | |
6dbe3af9 | 157 | An asterisk (*) may not be used as a field width or precision. |
7570e15a SK |
158 | .TP |
159 | 2. | |
6dbe3af9 | 160 | A byte count or field precision |
7570e15a SK |
161 | .I is |
162 | required for each | |
163 | .B s | |
164 | conversion character (unlike the | |
165 | .BR fprintf (3) | |
6dbe3af9 | 166 | default which prints the entire string if the precision is unspecified). |
7570e15a SK |
167 | .TP |
168 | 3. | |
169 | The conversion characters | |
170 | .BR h , \ l , \ n , \ p , | |
171 | .RB and \ q | |
172 | are not supported. | |
173 | .TP | |
174 | 4. | |
175 | The single character escape sequences described in the C standard are | |
176 | supported: | |
177 | .PP | |
178 | .RS 13 | |
179 | .PD 0 | |
180 | .TP 21 | |
181 | NULL | |
182 | \e0 | |
183 | .TP | |
184 | <alert character> | |
185 | \ea | |
186 | .TP | |
187 | <backspace> | |
188 | \eb | |
189 | .TP | |
190 | <form-feed> | |
191 | \ef | |
192 | .TP | |
193 | <newline> | |
194 | \en | |
195 | .TP | |
196 | <carriage return> | |
197 | \er | |
198 | .TP | |
199 | <tab> | |
200 | \et | |
201 | .TP | |
202 | <vertical tab> | |
203 | \ev | |
204 | .PD | |
205 | .RE | |
206 | .PP | |
207 | .SS Conversion strings | |
5bcd986e | 208 | The |
7570e15a SK |
209 | .B hexdump |
210 | utility also supports the following additional conversion strings. | |
211 | .TP | |
212 | .B \&_a[dox] | |
213 | Display the input offset, cumulative across input files, of the next byte to | |
214 | be displayed. The appended characters | |
215 | .BR d , | |
216 | .BR o , | |
6dbe3af9 | 217 | and |
7570e15a SK |
218 | .B x |
219 | specify the display base as decimal, octal or hexadecimal respectively. | |
220 | .TP | |
221 | .B \&_A[dox] | |
6dbe3af9 | 222 | Identical to the |
7570e15a SK |
223 | .B \&_a |
224 | conversion string except that it is only performed once, when all of the | |
225 | input data has been processed. | |
226 | .TP | |
227 | .B \&_c | |
d35df4db | 228 | Output characters in the default character set. Non-printing characters are |
7570e15a SK |
229 | displayed in three-character, zero-padded octal, except for those |
230 | representable by standard escape notation (see above), which are displayed as | |
231 | two-character strings. | |
232 | .TP | |
233 | .B \&_p | |
d35df4db | 234 | Output characters in the default character set. Non-printing characters are |
7570e15a SK |
235 | displayed as a single |
236 | .RB ' \&. '. | |
237 | .TP | |
238 | .B \&_u | |
6dbe3af9 | 239 | Output US ASCII characters, with the exception that control characters are |
7570e15a SK |
240 | displayed using the following, lower-case, names. Characters greater than |
241 | 0xff, hexadecimal, are displayed as hexadecimal strings. | |
100af003 SK |
242 | .RS 10 |
243 | .TS | |
244 | tab(|); | |
245 | left l l l l l. | |
246 | 000 nul|001 soh|002 stx|003 etx|004 eot|005 enq | |
247 | 006 ack|007 bel|008 bs|009 ht|00A lf|00B vt | |
248 | 00C ff|00D cr|00E so|00F si|010 dle|011 dc1 | |
249 | 012 dc2|013 dc3|014 dc4|015 nak|016 syn|017 etb | |
250 | 018 can|019 em|01A sub|01B esc|01C fs|01D gs | |
251 | 01E rs|01F us|0FF del | |
252 | .TE | |
098ab077 | 253 | .SS Colors |
100af003 SK |
254 | When put at the end of a format specifier, hexdump highlights the |
255 | respective string with the color specified. Conditions, if present, are | |
256 | evaluated prior to highlighting. | |
257 | .PP | |
258 | .B \&_L[color_unit_1,\:color_unit_2,\:...,\:color_unit_n] | |
259 | .PP | |
098ab077 | 260 | The full syntax of a color unit is as follows: |
100af003 SK |
261 | .PP |
262 | .B [!]COLOR\:[:VALUE]\:[@OFFSET_START[-END]] | |
098ab077 OO |
263 | .TP |
264 | .B ! | |
100af003 SK |
265 | Negate the condition. Please note that it only makes sense to negate a |
266 | unit if both a value/\:string and an offset are specified. In that case | |
267 | the respective output string will be highlighted if and only if the | |
268 | value/\:string does not match the one at the offset. | |
269 | .TP | |
098ab077 OO |
270 | .BR COLOR |
271 | One of the 8 basic shell colors. | |
100af003 SK |
272 | .TP |
273 | .B VALUE | |
274 | A value to be matched specified in hexadecimal, or octal base, or as a | |
275 | string. Please note that the usual C escape sequences are not | |
276 | interpreted by hexdump inside the color_units. | |
277 | .TP | |
278 | .B OFFSET | |
279 | An offset or an offset range at which to check for a match. Please note | |
3bf7ede9 | 280 | that lone OFFSET_START uses the same value as END offset. |
7570e15a | 281 | .SS Counters |
6dbe3af9 KZ |
282 | The default and supported byte counts for the conversion characters |
283 | are as follows: | |
7570e15a SK |
284 | .TP |
285 | .BR \&%_c , \ \&%_p , \ \&%_u , \ \&%c | |
6dbe3af9 | 286 | One byte counts only. |
7570e15a SK |
287 | .TP |
288 | .BR \&%d , \ \&%i , \ \&%o , \ \&%u , \ \&%X , \ \&%x | |
6dbe3af9 | 289 | Four byte default, one, two and four byte counts supported. |
7570e15a SK |
290 | .TP |
291 | .BR \&%E , \ \&%e , \ \&%f , \ \&%G , \ \&%g | |
6dbe3af9 | 292 | Eight byte default, four byte counts supported. |
7570e15a SK |
293 | .PP |
294 | The amount of data interpreted by each format string is the sum of the data | |
295 | required by each format unit, which is the iteration count times the byte | |
296 | count, or the iteration count times the number of bytes required by the | |
297 | format if the byte count is not specified. | |
298 | .PP | |
299 | The input is manipulated in | |
300 | .IR blocks , | |
301 | where a block is defined as the largest amount of data specified by any | |
302 | format string. Format strings interpreting less than an input block's worth | |
303 | of data, whose last format unit both interprets some number of bytes and does | |
304 | not have a specified iteration count, have the iteration count incremented | |
305 | until the entire input block has been processed or there is not enough data | |
306 | remaining in the block to satisfy the format string. | |
307 | .PP | |
5bcd986e | 308 | If, either as a result of user specification or |
7570e15a | 309 | .B hexdump |
5bcd986e | 310 | modifying the iteration count as described above, an iteration count is |
7570e15a SK |
311 | greater than one, no trailing whitespace characters are output during the |
312 | last iteration. | |
313 | .PP | |
6dbe3af9 | 314 | It is an error to specify a byte count as well as multiple conversion |
7570e15a SK |
315 | characters or strings unless all but one of the conversion characters or |
316 | strings is | |
317 | .B \&_a | |
6dbe3af9 | 318 | or |
7570e15a SK |
319 | .BR \&_A . |
320 | .PP | |
6dbe3af9 | 321 | If, as a result of the specification of the |
7570e15a SK |
322 | .B \-n |
323 | option or end-of-file being reached, input data only partially satisfies a | |
324 | format string, the input block is zero-padded sufficiently to display all | |
325 | available data (i.e. any format units overlapping the end of data will | |
326 | display some number of the zero bytes). | |
327 | .PP | |
328 | Further output by such format strings is replaced by an equivalent number of | |
329 | spaces. An equivalent number of spaces is defined as the number of spaces | |
6dbe3af9 | 330 | output by an |
7570e15a SK |
331 | .B s |
332 | conversion character with the same field width and precision as the original | |
333 | conversion character or conversion string but with any | |
334 | .RB ' \&+ ', | |
335 | \' \', | |
336 | .RB ' \&# ' | |
337 | conversion flag characters removed, and referencing a NULL string. | |
338 | .PP | |
e8cf378e BS |
339 | If no format strings are specified, the default display is very similar to |
340 | the \fB\-x\fR output format (the \fB\-x\fR option causes more space to be | |
341 | used between format units than in the default output). | |
7570e15a SK |
342 | .SH "EXIT STATUS" |
343 | .B hexdump | |
6dbe3af9 | 344 | exits 0 on success and >0 if an error occurred. |
7570e15a | 345 | .SH EXAMPLES |
6dbe3af9 | 346 | Display the input in perusal format: |
7570e15a SK |
347 | .nf |
348 | "%06.6_ao " 12/1 "%3_u " | |
349 | "\et\et" "%_p " | |
350 | "\en" | |
351 | .nf | |
352 | .PP | |
6dbe3af9 | 353 | Implement the \-x option: |
7570e15a SK |
354 | .nf |
355 | "%07.7_Ax\en" | |
356 | "%07.7_ax " 8/2 "%04x " "\en" | |
357 | .nf | |
098ab077 | 358 | .PP |
100af003 SK |
359 | MBR Boot Signature example: Highlight the addresses cyan and the bytes at |
360 | offsets 510 and 511 green if their value is 0xAA55, red otherwise. | |
098ab077 OO |
361 | .nf |
362 | "%07.7_Ax_L[cyan]\en" | |
363 | "%07.7_ax_L[cyan] " 8/2 " %04x_L[green:0xAA55@510-511,!red:0xAA55@510-511] " "\en" | |
364 | .nf | |
60ec67ff | 365 | .SH COLORS |
052e512a | 366 | Implicit coloring can be disabled by an empty file \fI/etc/terminal-colors.d/hexdump.disable\fR. |
60ec67ff | 367 | |
052e512a KZ |
368 | See |
369 | .BR terminal-colors.d (5) | |
370 | for more details about colorization configuration. | |
7570e15a | 371 | .SH STANDARDS |
ffc43748 | 372 | The |
7570e15a SK |
373 | .B hexdump |
374 | utility is expected to be IEEE Std 1003.2 ("POSIX.2") compatible. | |
375 | .SH AVAILABILITY | |
601d12fb | 376 | The hexdump command is part of the util-linux package and is available from |
d673b74e | 377 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
7570e15a SK |
378 | Linux Kernel Archive |
379 | .UE . |