Return to hexdump.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / usr.bin / hexdump

Annotation of 43BSDReno/usr.bin/hexdump/hexdump.1, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.