Format-Hex
Displays a file or other input as hexadecimal.
Syntax
Format-Hex
[-Path] <String[]>
[-Count <Int64>]
[-Offset <Int64>]
[<CommonParameters>]
Format-Hex
-LiteralPath <String[]>
[-Count <Int64>]
[-Offset <Int64>]
[<CommonParameters>]
Format-Hex
-InputObject <PSObject>
[-Encoding <Encoding>]
[-Count <Int64>]
[-Offset <Int64>]
[-Raw]
[<CommonParameters>]
Description
The Format-Hex
cmdlet displays a file or other input as hexadecimal values. To determine the
offset of a character from the output, add the number at the leftmost of the row to the number at
the top of the column for that character.
The Format-Hex
cmdlet can help you determine the file type of a corrupted file or a file that
might not have a filename extension. You can run this cmdlet, and then read the hexadecimal output
to get file information.
When using Format-Hex
on a file, the cmdlet ignores newline characters and returns the entire
contents of a file in one string with the newline characters preserved.
Examples
Example 1: Get the hexadecimal representation of a string
This command returns the hexadecimal values of a string.
'Hello World' | Format-Hex
Label: String (System.String) <2944bec3>
Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 48 65 6C 6C 6F 20 57 6F 72 6C 64 Hello World
The string Hello World is sent down the pipeline to the Format-Hex
cmdlet. The hexadecimal
output from Format-Hex
shows the values of each character in the string.
Example 2: Find a file type from hexadecimal output
This example uses the hexadecimal output to determine the file type. The cmdlet displays the file's full path and the hexadecimal values.
To test the following command, make a copy of an existing PDF file on your local computer and rename
the copied file to File.t7f
.
Format-Hex -Path .\File.t7f -Count 48
Label: C:\Test\File.t7f
Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 25 50 44 46 2D 31 2E 35 0D 0A 25 B5 B5 B5 B5 0D %PDF-1.5..%????.
0000000000000010 0A 31 20 30 20 6F 62 6A 0D 0A 3C 3C 2F 54 79 70 .1 0 obj..
The Format-Hex
cmdlet uses the Path parameter to specify a filename in the current directory,
File.t7f
. The file extension .t7f
is uncommon, but the hexadecimal output %PDF
shows that it
is a PDF file. In this example, the Count parameter is used to limit the output to the first 48
bytes of the file.
Example 3: Format an array of different data types
This example uses an array of different data types to highlight how Format-Hex
handles them in the
Pipeline.
It will pass each object through the Pipeline and process individually. However, if it's numeric data, and the adjacent object is also numeric, it will group them into a single output block.
'Hello world!', 1, 1138, 'foo', 'bar', 0xdeadbeef, 1gb, 0b1101011100 , $true, $false | Format-Hex
Label: String (System.String) <24f1f0a3>
Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 48 65 6C 6C 6F 20 77 6F 72 6C 64 21 Hello world!
Label: Int32 (System.Int32) <2eb933c5>
Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 01 00 00 00 72 04 00 00 � r�
Label: String (System.String) <4078b66c>
Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 66 6F 6F foo
Label: String (System.String) <51e4a317>
Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 62 61 72 bar
Label: Int32 (System.Int32) <5adf167b>
Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 EF BE AD DE 00 00 00 40 5C 03 00 00 ï¾Þ @\�
Label: Boolean (System.Boolean) <7d8c4c1d>
Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 01 00 00 00 00 00 00 00 �
Parameters
This represents the number of bytes to include in the hex output.
This parameter was introduced in PowerShell 6.2.
Type: | Int64 |
Position: | Named |
Default value: | Int64.MaxValue |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies the encoding of the input strings. This only applies to [string]
input. The parameter
has no effect on numeric types. The output value is always utf8NoBOM
.
The acceptable values for this parameter are as follows:
ascii
: Uses the encoding for the ASCII (7-bit) character set.bigendianunicode
: Encodes in UTF-16 format using the big-endian byte order.oem
: Uses the default encoding for MS-DOS and console programs.unicode
: Encodes in UTF-16 format using the little-endian byte order.utf7
: Encodes in UTF-7 format.utf8
: Encodes in UTF-8 format.utf8BOM
: Encodes in UTF-8 format with Byte Order Mark (BOM)utf8NoBOM
: Encodes in UTF-8 format without Byte Order Mark (BOM)utf32
: Encodes in UTF-32 format.
Beginning with PowerShell 6.2, the Encoding parameter also allows numeric IDs of registered code
pages (like -Encoding 1251
) or string names of registered code pages (like
-Encoding "windows-1251"
). For more information, see the .NET documentation for
Encoding.CodePage.
Type: | Encoding |
Accepted values: | ASCII, BigEndianUnicode, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32 |
Position: | Named |
Default value: | UTF8NoBOM |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Used for pipeline input. Pipeline input supports only certain scalar types and [system.io.fileinfo]
instances for piping from Get-ChildItem
.
The supported scalar types are:
[string]
,[char]
[byte]
,[sbyte]
[int16]
,[uint16]
,[short]
,[ushort]
[int]
,[uint]
,[int32]
,[uint32]
,[long]
,[ulong]
,[int64]
,[uint64]
[single]
,[float]
,[double]
[boolean]
Prior to PowerShell 6.2, Format-Hex
would handle a Pipeline input with multiple input types by
grouping all like objects together. Now, it handles each individual object as it passes through the
Pipeline and won't group objects together unless like objects are adjacent.
Type: | PSObject |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Specifies the complete path to a file. The value of LiteralPath is used exactly as it is typed. This parameter does not accept wildcard characters. To specify multiple paths to files, separate the paths with a comma. If the LiteralPath parameter includes escape characters, enclose the path in single quotation marks. PowerShell does not interpret any characters in a single quoted string as escape sequences. For more information, see about_Quoting_Rules.
Type: | String[] |
Aliases: | PSPath, LP |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
This represents the number of bytes to skip from being part of the hex output.
This parameter was introduced in PowerShell 6.2.
Type: | Int64 |
Position: | Named |
Default value: | 0 |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies the path to files. Use a dot (.
) to specify the current location. The wildcard character
(*
) is accepted and can be used to specify all the items in a location. If the Path parameter
includes escape characters, enclose the path in single quotation marks. To specify multiple paths to
files, separate the paths with a comma.
Type: | String[] |
Position: | 0 |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | True |
This parameter no longer does anything. It is retained for script compatibility.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
You can pipe a string to this cmdlet.
Outputs
This cmdlet returns a ByteCollection. This object represents a collection of bytes. It includes
methods that convert the collection of bytes to a string formatted like each line of output returned
by Format-Hex
. The output also states they type of bytes being processed. If you specify the
Path or LiteralPath parameter, the object contains the path of the file that contains
each byte. If you pass a string, boolean, integer, etc, it will be labeled appropriately.
Notes
The right-most column of output tries to render the bytes as ASCII characters:
Generally, each byte is interpreted as a Unicode code point, which means that:
- Printable ASCII characters are always rendered correctly
- Multi-byte UTF-8 characters never render correctly
- UTF-16 characters render correctly only if their high-order byte happens be
NUL
.