FileAnalyzer

Script Control of the FileAnalyzers

As an alternative to using the graphical user interface, many functions of the FileAnalyzer can also be controlled via command line commands. This includes, for example, reading individual values from the file structure, comparing entire chunks or individual properties of multiple files, searching for byte sequences, numbers or strings as well as searching within the file structure. This makes it possible to automate the FileAnalyzer and integrate it into other programs or scripts.

In this tutorial we would like to take a step-by-step look at how this works in detail and which parameters are available to you. The tutorial is divided into the following sections:

• Basics of the Script Control of the FileAnalyzer
• Selection of Files
• Selecting Files from Folders
• The Path Concept
• Readout of individual Values
• Comparison of Chunks of multiple Files
• Comparison of Chunks within one File
• Comparison of individual Properties of multiple Files
• Search for Byte Sequences
• Search for Numbers
• Search for Strings
• Search in the File Structure
• Output to the Console or Storage as File
• Format of Storage and Console Output
• Columns and Column Headings of the Output
• Overview of the Default Columns of the various Output and Search Types
• Overview of all Column Parameters
• Overview of all available Parameters

Basics of the Script Control of the FileAnalyzer

Before we have a look at the various options for script controlling the FileAnalyzer in detail, we would first like to clarify the basic principle of script controlling this program with the help of the following ten example calls that demonstrate the different types of command and output types of the FileAnalyzer:

FileAnalyzer.exe -cl C:\Font.ttf get-val=/head:macStyle.Bold
FileAnalyzer.exe -cl C:\Folder filter-ext=jpg/jpeg compare=/APP1
FileAnalyzer.exe -cl C:\Icon.ico compare=/Image/ImageDescriptor
FileAnalyzer.exe -cl C:\Image1.png C:\Image2.png compare=/IHDR:Width,Height
FileAnalyzer.exe -cl C:\Folder filter-onlytextfiles=1 search-bytes=0D0A cols=file_name,offset_file colh=0
FileAnalyzer.exe -cl C:\Folder search-subdirs=0 filter-name=[0-9]+ filter-name-regex=1 search-uint32be=1
FileAnalyzer.exe -cl C:\Folder search-str=abc search-enc=utf16le search-bom=1 format=csv
FileAnalyzer.exe -cl C:\Folder search-val=7 save=C:\Result.xlsx openfile=1
FileAnalyzer.exe -cl C:\Folder filter-ext=wav search-prop=Channels search-val=2
FileAnalyzer.exe -cl C:\Folder filter-ext=exe search-path=/pe_optional_header search-prop=OSVersion search-val=4.0-6.1 search-val-cop=between

The general proceeding is always the same: First we put the FileAnalyzer into the command line mode with the parameter "-cl", then we select files, define an action and specify how the result should be saved or output.

• Start FileAnalyzer in Command Line Mode: In all example calls you can see that we always first pass the parameter "-cl". This parameter ensures that the FileAnalyzer starts in the command line mode without a graphical user interface. If we omit this parameter, the program will start with a graphical user interface and the selected files will only be opened in the FileAnalyzer but not processed automatically.
• Select Files: Next, we select the files that we want to analyze, compare or read out. In principle, for doing so, there are two options available to us. Either we specify the path to one or more files directly (as in the first, third and fourth example calls) or we pass the path to one or more folders (as in the other example calls). If we don't want to include all files from the specified folder or folders, we can additionally specify filters. We do this, for instance, in the second example with "filter-ext=jpg/jpeg", which ensures that from the folder only files with the file extensions JPG or JPEG are taken into account, in the fifth call with "filter-onlytextfiles=1" (only text files are taken into account) or in the sixth call, where we filter by the file name using regular expressions. With "search-subdirs" (sixth example) we can furthermore determine whether also subfolders should be searched (1) or not (0). You can find out more about selecting files as well as other filter options in the sections about selecting files and selecting files from folders.
• Define Action: After selecting the files, we specify what should be done with the files. In the first example we read a single value from a file, in the next three examples we compare several chunks with each other: in the second call we compare all values of a chunk of several files with each other, in the third example we compare the same chunk type within one file and in the fourth example, we limit the comparison to only single properties / values of a chunk. In the fifth, sixth and seventh examples, the search for byte sequences, the search for numbers as well as the search for strings follow, while the last three examples demonstrate the search within the file structure. The specification of chunks
  within the file structure is thereby done using the chunk path.
• Specification of the Output Format: Finally, we determine the form in which the result should be output. Basically, the result can either be saved as a file (eighth example) or output directly to the console (all other examples). If the "save" parameter is not specified, output is done to the console. Apart from that, if a file path is specified with the "save" parameter, the output is saved in this file. The format of the output can be specified either via the file extension of the specified file or via the "format" parameter (seventh example). If you pass "openfile=1" the file will be opened immediately after it is created. You can learn more about this topic in the sections about outputting to file or console as well as about the output format.
• Specification of Columns: If you want to write other than the default columns into your output, you can do this using the parameter "cols", which is used in the fifth example to write the file name and the byte offset of the found value into the result. Via "colh" you can moreover determine whether your output table should contain column headings or not. You can learn more about the specification of columns and their order in the section about the columns and column headings of the output.

In the next sections we will go into more detail about these and all other available parameters. At the end of this tutorial you can additionally find an overview table of all parameters. This table contains a brief description of the parameters including their default values, which are used if the relevant parameter is not explicitly specified.

Selection of Files

If you want to process individual files with the FileAnalyzer, you can simply pass their paths. In the following example, we read the property "macStyle.Bold" from the header of a font file in this way:

FileAnalyzer.exe -cl C:\Font.ttf get-val=/head:macStyle.Bold

As the next example call shows, you can also pass multiple file paths at the same time. This time we compare all values of the complete header of two font files:

FileAnalyzer.exe -cl C:\Font1.ttf C:\Font2.ttf compare=/head

Instead of specifying each file individually, alternatively, we can also pass the path of a folder to process files from that folder. More on this in the next section.

Selecting Files from Folders

If we want to process a lot of files or an indefinite collection of files with the FileAnalyzer, it is advisable to pass the path to a folder or concurrently the paths to several folders to the FileAnalyzer in order to simultaneously process all files or a selection of files from these folders.

The paths of the folders can be specified in the same way as the paths of files, as we saw in the last section. For example, like in our next call, in which we want to compare the Exif data (stored in the chunk "APP1") of several JPG files with each other:

FileAnalyzer.exe -cl C:\Images compare=/APP1

This call compares the APP1 element of all files stored in the folder "C:\Images" with each other.

File paths and folder paths can also be mixed as desired. For example, the next example compares the Exif data of the image "C:\Image.jpg" with the JPG images stored in the folder "C:\Images":

FileAnalyzer.exe -cl C:\Image.jpg C:\Images compare=/APP1

Of course, our specified folders could also contain files other than JPG images for which the APP1 comparison doesn't make sense. For this case, the FileAnalyzer provides you with some filters with which you can limit the processed files from a folder to a specific selection. For example, in our case here, we could make use if the filter for the file extension "filter-ext":

FileAnalyzer.exe -cl C:\Folder filter-ext=jpg compare=/APP1

This call would only process the files with the file extension "jpg" from the folder "C:\Folder". Since also the ending "jpeg" is common for JPG files, we could also specify this file extension additionally:

FileAnalyzer.exe -cl C:\Folder filter-ext=jpg/jpeg compare=/APP1

Accordingly, multiple file extensions can be listed separated by a comma. Alternatively, if all the images in your folder are JPG files, you could also use the filter "filter-type=image" instead, which allows you to filter by a general file type rather than a specific file extension. The options available are "image", "video", "text", "document", "spreadsheet", "website", "font", "executable", "archive", "playlist", "sourcecode" and "other".

Additionally or alternatively, you can also filter by the name of the files. To do this, you can use the filter "filter-name", which can be combined with the parameters "filter-name-matchcase" (case sensitive), "filter-name-matchall" (entire file name must match) and "filter-name-regex" (regular expression). Let's also look at an example for this:

FileAnalyzer.exe -cl C:\Folder filter-ext=jpg filter-name=2000 compare=/APP1
FileAnalyzer.exe -cl C:\Folder filter-name=[0-9]+ filter-name-regex=1 compare=/APP1
FileAnalyzer.exe -cl C:\Folder filter-name=[0-9]+ filter-name-regex=1 filter-name-matchall=1 compare=/APP1
FileAnalyzer.exe -cl C:\Folder filter-name=abc filter-name-matchcase=1 compare=/APP1
FileAnalyzer.exe -cl C:\Folder filter-name=abc/def compare=/APP1

The first call finds all files with the file extension "JPG" whose names contain the number "2000". In the second call we tell the FileAnalyzer with "filter-name-regex=1" that it should interpret the search term "[0-9]+" as a regular expression. So, all files that contain at least one digit are found. If we add the parameter "filter-name-matchall=1" as in the third example, it is no longer sufficient that the file name just contains numbers. Instead, with this command, the entire file name must now correspond to the search term, so only file names that consist exclusively of numbers (except for the file extension) are found. Next, we look for all files that contain the lowercase text "abc". If we omitted "filter-name-matchcase=1", the search would be carried out regardless of the uppercase and lowercase writing and, for example, files whose file names contain the text "ABC" would also be found. If we added "filter-name-matchall=1", only files named "abc" would be found. Finally, we see how we can search for multiple names at the same time. This call finds all files whose names contain either "abc" or "def". Of course, we can also combine this multiple search with any available option parameters such as "filter-name-matchall" or "filter-name-regex".

Another important parameter related to passing folders to the FileAnalyzer is the parameter "search-subdirs". You use this parameter to specify whether subfolders of the passed folder should also be searched. By default, subfolder searching is enabled, which corresponds to the specification "search-subdirs=1". In all of our previous examples in this section, files from a folder like "C:\Folder\SubFolder" would also be processed. If you don't want this, you can pass this parameter like "search-subdirs=0" as the next example demonstrates:

FileAnalyzer.exe -cl C:\Folder search-subdirs=0 filter-ext=jpg compare=/APP1

The individual filters can be combined with each other as desired and it does not matter in which order you specify the filters. You can find a list of the filters presented in this section and other filters in the overview table of all parameters at the end of this tutorial.

The Path Concept

Before we look at how to read, compare and search properties and values from the structure of files, we would like to briefly discuss how we can address the individual file parts (chunks) in which the properties and values are stored using the FileAnalyzer. The FileAnalyzer understands the internal structure of files in a similar way as a folder structure, in which each chunk can be unambiguously selected via a path.

As an example, we would like to look at the ISO Base Media File Format, a container format that stores files such as the formats MP4, M4A, MOV, 3GP, HEIC, HEIF, AVIF or CR3, for example. An MP4 video file or an M4A audio file typically contains chunks such as the File Type Box (ftyp), the Media Data Container (mdat) and the Movie Box (moov) at the first level. We can address these chunks using the paths /ftyp, /mdat or /moov.

If we now want to read out a property like the playing time of these files, we have to delve deeper into the file structure. The playing time of MP4 videos or M4A audios is stored in the Track Header (tkhd). The Track Header is located in the Track Container (trak), which in turn is located inside the Movie Box (moov). Since the movie box is on the first level, we are finished and the path is /moov/trak/tkhd, which we can use for our task.

While audio files typically contain only one audio track, video files can contain both an audio track and a video track. MP4 files that contain both an audio track and a video track therefore contain two track containers below their movie box (moov), both of them having the same name "trak". In this case, our path "/moov/trak/tkhd" is of course no longer unique. To make the path unique, the FileAnalyzer numbers such paths with an index starting at 0. The first path of such a file would therefore be clearly accessible via "/moov/trak[0]/tkhd", the second via "/moov/ trak[1]/tkhd".

So, if we use one of these two paths with an index in the search function of the FileAnalyzer, we only search in the respective path and not in both. On the other hand, if we write the path without an index (here "/moov/trak/tkhd"), the search function would search both the audio track header and the video track header. By omitting or specifying an index, we can control whether we mean a specific chunk or all chunks of the respective type.

Of course, you don't need to know by memory which properties are stored in which path of a file format. Simply open a file of your choice in the FileAnalyzer and just browse through the file using the tree structure on the left side of the program or use the search functions to find specific properties. If you have selected an element within the tree structure, the respective path of this element is displayed below the tree structure. Additionally, if you right-click the element, the path can be conveniently copied to the clipboard, so you don't have to enter the path manually.

That's everything you should know about the path concept of the FileAnalyzer. In the next section we will take up the example of reading out the playing time of MP4 and M4A files again and take a look at how reading out via a script call can actually look like.

Readout of individual Values

Individual values of certain properties can be read from the file structure using the parameter "get-val". The name of the property as well as the path where the property we want to read out is stored can be specified in the following form:

get-val=/path:property

In the following example, we want to read out the playing time of an M4A audio file using the "get-val" parameter. An M4A audio file is based on the ISO Base Media File Format, in which the playing time is stored in the path "/moov/trak/tkhd" under the property "Duration" (if you haven't read all parts of this tutorial yet: how we came to this path and what it means you can learn in the previous section, how we can select files you can find out here). We can therefore construct the following call for our concern:

FileAnalyzer.exe -cl C:\Audio.m4a get-val=/moov/trak/tkhd:Duration

Theoretically, we could use the same call also for video files in MP4 format, which are also based on the ISO Base Media File Format. However, videos can contain both an audio track and a video track, so in this case this call would return two playing times, one for each track contained in the file. If we only want to have one playing time (the playing times of the audio and video tracks typically differ only slightly, if at all), it is sufficient to just read out the first track. So we specify an index for "trak" and instead use "trak[0]" to address the first trak chunk only (more on this in the previous section):

FileAnalyzer.exe -cl C:\Audio.mp4 get-val=/moov/trak[0]/tkhd:Duration

Both of these calls simply provide us with just the value of the playing time or duration, as this is the default output configuration for the parameter "get-val". If we need more information, we can define additional columns for the output using the parameter "cols", for example, as the next example shows:

FileAnalyzer.exe -cl C:\Videos filter-ext=mp4 get-val=/moov/trak[0]/tkhd:Duration cols=file_name,offset_file,value colh=1

With this call we read the playing time of all MP4 files from the folder "C:\Videos" and create a table that contains the columns file name (file_name), offset of the value within the file (offset_file) and the values themselves (value). In addition, we pass the parameter "colh=1" with which we specify that column headings should also be included in the table. If we do not overwrite the default value of the two parameters cols and colh in this way, the defaults "cols=value" and "colh=0" will be used for "get-val", which means, as already mentioned, only the requested one value is output. To learn more about defining columns and the other column parameters available, see the columns and column headings section.

By the way, in this call we have used the path "/moov/mvhd:Duration" instead of "/moov/trak[0]/tkhd:Duration". In addition to the two duration specifications in the headers of the individual tracks (tkhd), there is a third, general specification of the playing time of the file stored in the movie header (mvhd). However, in the first examples we deliberately took the more complicated route to demonstrate the use of indices.

Comparison of Chunks of multiple Files

If you want to compare the properties of a chunk with the properties of the same chunk of other files, you can do this with the help of the compare parameter, with which you can simply pass the path of the chunk to be compared.

With the following call we would, for example, like to compare the "PE Optional Header" of all EXE applications (based on the Portable Executable Format) from the folder "C:\Folder":

FileAnalyzer.exe -cl C:\Folder filter-ext=exe compare=/pe_optional_header

With this call we can expect an output that looks exactly like the comparison table generated by the compare function in the graphical user interface of the FileAnalyzer. The output table contains the columns file name (file_name), path of the chunk (chunk_path), byte offset of the chunk within the file (chunk_offset), all values of the properties of the chunk as separate columns (values) as well as the file path of the respective file being searched. If you need other columns, you can configure them using the column parameters explained in the section about the configuration of columns and column headings.

Comparison of Chunks within one File

In addition to comparing the same chunks of several different files, the compare function can also be used to compare the same chunks within one file. For example, to compare the different sized images that can be stored in an icon:

FileAnalyzer.exe -cl C:\Icon.ico compare=/image/imagedescriptor

This call gives us an overview table in which information such as width, height, bit count or byte offset of the single images contained in the icon "C:\Icon.ico" is listed.

It is important that for this comparison we are using the general path without an image index (here "/image/imagedescriptor") instead of the path of the individual images (like "/image[0]/imagedescriptor" for image 1, "/image[1]/imagedescriptor" for image 2 and so on) to select not just one but all chunks of the same file for the comparison. If we wrote "/image[0]/imagedescriptor" instead and selected multiple images at the same time, we could use the call to compare the first image of all selected images. You can find out more about the background of that path selection in the section about the path concept.

The "PE Optional Header" from our first example showing the use of the compare parameter from the last section contains dozens of properties, the "ImageDescriptor" from our second example in this section slightly over 10. If you are not interested in all properties of a chunk, you can in addition to the other columns that can be configured using the parameter cols, also influence the property-columns of the results table by selecting only individual properties for the comparison. You can find out how this works in the next section.

Comparison of individual Properties of multiple Files

In the last two sections we looked at how we can compare all the properties of a chunk across multiple files or within one file. However, chunks can contain a lot of properties, some of which may not be of interest to us. For this reason, the FileAnalyzer also offers the option of selecting only individual properties of a chunk for comparison. To do this, all we have to do is append the property we are interested in to the path in the following form:

compare=/path:property

If we are interested in multiple properties, we can list them separated by a comma:

compare=/path:property1,property2,property3,...

In the next example call, we will take up the first example from the last section again. This time we only want to compare the "OSVersion" property (minimum supported Windows version of the portable executable) with the other EXE files from the specified folder:

FileAnalyzer.exe -cl C:\Folder filter-ext=exe compare=/pe_optional_header:OSVersion

As a result, we get a table like the one we have already described in the last section. However, with the exception that this table no longer contains all the properties of the PE Optional Header but only the property "OSVersion". Of course, also in this case we can customize the other columns of this table according to our own needs in the same way as we have done it in the last section.

We would also like to look at an example of how to select multiple properties:

FileAnalyzer.exe -cl C:\Images filter-ext=bmp compare=/infoheader:Width,Height

This call compares the width and the height of all bitmap files with the file extension BMP (filter-ext=bmp) from the folder "C:\Images". The width and the height of bitmaps are stored in the "/infoheader" chunk using the properties "Width" and "Height". That's why we called the compare parameter with "/infoheader:Width,Height". If we only wrote "compare=/infoheader", our comparison would also include all other properties of the bitmap info header such as Planes, BitCount, Compression, XPelsPerMeter, YPelsPerMeter or ColorsUsed. But this way, we only get our desired properties "Width" and "Height".

Search for Byte Sequences

With the parameter "search-bytes" you can search arbitrary files for any sequence of bytes. The bytes to be searched can be specified directly with the parameter:

FileAnalyzer.exe -cl C:\Folder filter-ext=mkv search-bytes=1F43B675

With this call you generate a list of all occurrences of the byte sequence "1F 43 B6 75" (Start / ElementID of a Matroska Cluster) found in the MKV files stored in the folder "C:\Folder". By default, the list contains the columns file name (file_name), file structure path of the chunk in which the bytes were found (chunk_path), property and value within the file structure in which the bytes were found (property and value), byte offset of the byte sequence within the file (offset_file), data size (datasize) and the path of the file (file_path).

You can use the parameter "cols" to change these default columns for your output (more on this in the section on configuring columns and column headings). For example, the next call only lists the file name and the byte offset (cols=file_name,offset_file) of the byte sequence "0D 0A" of all text files (filter-onlytextfiles=1) from the folder "C:\Folder" ("0D 0A" are the two bytes of the Windows line break CR LF):

FileAnalyzer.exe -cl C:\Folder filter-onlytextfiles=1 "search-bytes=0D 0A" cols=file_name,offset_file

This example also demonstrates that we can also specify the bytes with spaces for better readability. To make clear that the space does not introduce a new parameter, in this case we have to enclose the entire parameter in quotation marks.

If the bytes you want to search have the meaning of a number or a text, it is not necessary to manually determine the byte sequence required for the search. Instead, you can specify the number or the text as such using parameters such as search-str or search-val and let the FileAnalyzer do the rest. We would like to take a look at how this works in the next sections of this tutorial.

Search for Numbers

If you want to search files for numbers of different formats, it is not necessary to first convert the number you want to search into its byte equivalent. Instead, you can search for a specific number directly in the FileAnalyzer with stating the number format. The syntax of this search parameter is the following:

search-(u/s)int(8/16/24/32/40/48/56/64)(le/be)=<Number>

After "search-" we first specify the signedness of our number using "uint" (unsigned) or "sint" (signed). Subsequently, it follows the size determined in bits as well as the endianness ("le" stands for little endian, "be" for big endian). When we have composed our parameter in this way, the number we want to find can be specified after the equal sign.

With the following call we are, as an example, looking for the 4 byte (= 32 bit) unsigned little endian number "1":

FileAnalyzer.exe -cl C:\Folder search-uint32be=1

Internally, the FileAnalyzer will convert this information into the resulting byte sequence "00 00 00 01" and will by means of this call search all files from the folder "C:\Folder" for it.

Another example is the next call, which searches the file "C:\File.dat" for the signed number "-2" in 8-byte/64-bit little endian format, which corresponds to a search for the byte sequence "FE FF FF FF FF FF FF FF":

FileAnalyzer.exe -cl C:\File.dat search-sint64be=-2 cols=offset_file

Without explicitly specifying your desired columns, when searching for numbers, the same columns are used for the output by default as when searching directly for byte sequences, what we have looked at in the previous section. Again, this behavior can be controlled using the parameter "cols", which we used in this call to indicate that we are only interested in the respective byte offset of the occurrences.

One problem with using this pure number search presented here is that the format and the structure of the file being searched is not taken into account. This means that this command searches for the numbers solely based on the bytes and does not take into account what meaning the bytes have within a file respectively file format or whether the byte equivalent is even used in the sense of the searched number within the file. Especially with numbers of small byte size, it can quickly happen that the generated byte sequences in the file mean anything else than the number you are looking for.

For this reason, you should prefer the search in the file structure rather than just searching for byte-level numbers when possible. When searching within the file structure, you can also search for numbers with using the parameter "search-val", but the numbers will only be found if they appear as such as a property within the file structure. In addition, with this type of search you do not need to worry about the data size, signedness and endianness of the numbers to be searched, as the number format is automatically determined by the file format.

Search for Strings

The string search respectively the search for texts using the parameter "search-str" works similar to the number search introduced in the last section. If we want, as an example, search all files from the folder "C:\Folder" for the text "abc" regardless of the file structure of the searched files, we can call the FileAnalyzer in the following way:

FileAnalyzer.exe -cl C:\Folder search-str=abc

Internally, the FileAnalyzer will convert our given string to a byte sequence in order to search for it. By default, unless we specify otherwise, the string will be converted to UTF-8 encoding without a byte order mark. Our string "abc", which only contains characters from the ASCII character set, becomes the byte sequences "61 62 63".

If we want to search a string using a different encoding or with an introducing byte order mark, we can use the parameters "search-enc" and "search-bom" for our specifications. For example like this:

FileAnalyzer.exe -cl C:\Folder search-str=abc search-enc=utf16le search-bom=1

Here we want to search for the UTF-16 Little Endian encoded string "abc" with Byte Order Mark (BOM). In UTF-16 little-endian bytes, "abc" corresponds to the byte sequence "61 00 62 00 63 00". The byte order mark for UTF-16 moreover consists of the 2 bytes "FF FE", so this call would lead to a search for the byte sequence "FF FE 61 00 62 00 63 00".

The default columns for the string search correspond to the default columns used by the byte sequence search and the number search. If you want a different column configuration for your result, you can again use the column parameters cols and colh for your setting.

As with the number search that we looked at in the last section, also the string search using the parameter "search-str" is carried out without taking the underlying file structure into account. If you only want to find texts that are used as such within the file structure, you should search for your text using "search-val" instead of "search-str". Explanations and examples can be found in the next section on searching the file structure.

Search in the File Structure

The search types for byte sequences, numbers or strings, introduced so far, had in common that the search carried out by these search functions is done without taking into account the underlying structure of the file to be searched.

So, the bytes of a number or a string, generated from the respective search input, could, for example, also only be some partial bytes of larger numbers or strings, the bytes could be used in the sense of a different data type (for example, numbers could be part of a string) or even comprise several actually syntactically independent chunks or properties, for example if the first bytes occur at the end of a chunk and the next chunk begins with the remaining bytes in the searched file. The probability is of course highest for short numbers, while it decreases as the length of a string search increases.

Of course, also the search functions for byte sequences, numbers and strings have their areas of application. However, if you are looking for a specific value that should appear as such within the file structure, you should prefer the file structure search presented in this section over the other search functions.

The search within the file structure is based on the three basic parameters search-path, search-prop and search-val, with which you can limit your search to a specific chunk path, a specific property or a specific value. The three parameters can all be used together, but also in any combination or individually.

The following example shows how to use all three parameters together:

FileAnalyzer.exe -cl C:\Folder filter-ext=avi search-path=/list/avih search-prop=Width search-val=1280

With this call we search for AVI videos (filter-ext=avi) from the folder "C:\Folder" that have a width of 1280 pixels and output the result to the console. Since the width and height are stored in the AVI header (avih) and the AVI header is located in the path "/list/avih" of the Resource Interchange File Format (RIFF format), we set the search path to "/list/avih". At the same time, we are only interested in the "Width" property (search-prop=Width) from the AVI header, the value of which should be "1280", which is why we finally pass the parameter "search-val=1280".

In the end, the only insight from this type of search is which files from the passed folder match our search criteria, since the path, property and value are already determined before the search is carried out. The situation is different if we do not specify all of the search criteria, as in the following example:

FileAnalyzer.exe -cl C:\Folder filter-ext=tiff search-val=1 save=SearchResult.csv

In this call, we leave the path and the property open by leaving the search-path and search-prop parameters blank. Instead, we simply search the file structure of all TIFF files (Tagged Image File Format) from the specified folder for the value "1" and then save the search result as a CSV file. By leaving both the path and the property blank, we can get any properties in any paths as a result. So the "1" could appear in our search result as the value of ImageWidth or ImageLength as well as Orientation, ResolutionUnit, Compression or any other TIFF property, too.

Of course, we can also work with any other combination of our three basic parameters. For example, if we only define search-path and search-prop, we search for any value of the specified property in the specified path (a short form of this type of search is searching for single values via the parameter gel-val). If we only define search-path instead, we will find all properties in the specified path with their arbitrary values. And so on.

In our previous examples we have always looked for a property that should correspond to a specific value. This is equivalent to the comparison operator "equals", which is always active by default unless we specify another different comparison operator. In addition to "equals", there are the comparison operators "contains", "starts_with", "ends_with", "matches_regex" (corresponds to regular expression), "contains_regex" (contains regular expression), "greater", "greater_or_equal", "smaller", "smaller_or_equal" (less than or equal) and "between" (between two values, including these values). We can pass these operators to the FileAnalyzer with the parameters search-prop-cop for search-prop as well as search-val-cop for search-val. The suffix "cop" stands for "comparison operator". Let's look at examples:

FileAnalyzer.exe -cl C:\Folder filter-ext=ico search-path=/fileheader search-prop=NumberOfImages search-val=3 search-val-cop=greater

With this call we search for all icons from the specified folder that contain more than 3 images. For this, we use the parameters "search-val=3 search-val-cop=greater".

FileAnalyzer.exe -cl C:\Folder filter-ext=exe search-path=/pe_optional_header search-prop=OSVersion search-val=4.0-6.1 search-val-cop=between

In this call, we use the "between" comparison operator to list all EXE files with a minimum supported Windows version between 4.0 (Windows 95) and 6.1 (Windows 7).

FileAnalyzer.exe -cl C:\Folder filter-ext=jpg search-path=/app1/exifdata search-prop=Image search-prop-cop=starts_with search-val=[0-9] search-val-cop=contains_regex

And in this call we use both search-prop-cop as well as search-val-cop to extract all Exif data of all JPG images from the folder "C:\Folder" that start with "Image" ("search- prop=Image search-prop-cop=starts_with") and have at least one arbitrary number in its value (no non-nummeric strings). The search for an arbitrary number is realised using the regular expression [0-9] ("search-val=[0-9] search-val-cop=contains_regex").

In addition to search-prop-cop and search-val-cop, there are two other parameters available to you, search-prop-rev and search-val-rev, with which you can influence the interpretation of the values specified via search-prop or search-val. The two parameters can each take the values 0 or 1 and reverse the search ("rev" stands for reverse search). An example is the next call:

FileAnalyzer.exe -cl C:\Folder filter-ext=wav search-prop=Channels search-val=2 search-val-rev=1

With this call we search for all WAV files from the specified folder whose number of channels is not 2. We define the number "2" using "search-val=2" and write "search-val-rev=1" to reverse the search. If we omit "search-val-rev=1" the default search would search for all files whose value of the "Channels" property is exactly "2" (this corresponds to "search-val-rev=0"). The search-prop-rev parameter works in the same way and can be used to search all properties except the specified property. Of course, the -rev parameters can aslo be combined with the various -cop parameters in any way, beyond only reversing the "equals" search.

So far we haven't thought about what information is actually written into the result through our calls. By default, the search in the file structure uses the columns file name (file_name), chunk path (chunk_path), property (property), value (value), data type of the value (datatype), data size of the value (datasize), byte offset of the value within the file (offset_file) as well as path of the file (file_path) for both output in the console and for saving as a file. In addition, column headings are used for the columns by default.

Using the two parameters cols (type and order of columns, defined by comma-separated column parameters) as well as colh (colh=1 - column headings; colh=0 - no column headings), we can overwrite this standard output as desired with our own column preferences. Let's also look at an example for this:

FileAnalyzer.exe -cl C:\Image.gif search-path=/image/imagedescriptor search-prop=ImageSeparator cols=offset_file colh=0

With this call we want to list the byte offsets of all individual images contained in the specified GIF file "C:\Image.gif". We already know the file name and we are not interested in the data type, data size, column headers and so on, so here we only define the column for the byte offset from the beginning of the file (offset_file) using the cols parameter and deactivated the column headers using the colh parameter. So we get a list that only contains the byte offsets of the single images of our GIF.

To learn more about configuring results tables, see the section about the output columns and column headings. You can additionally find out more about the different column types and their parameters, including descriptions and examples, in the overview table of all column parameters.

Output to the Console or Storage as File

Regardless of what information you read out or generate with the FileAnalyzer, the output can always be carried out either directly into the console or saved as a file. You control this difference in output via the parameter "save", which can be used to define a file for the output. If this parameter is defined, output occurs in the form of the specified file. If this parameter is missing, the output is written to the console.

With the following two calls we both times compare the File Type Box (ftyp) of all MP4 files stored in the specified folder:

FileAnalyzer.exe -cl C:\Folder filter-ext=mp4 compare=/ftyp
FileAnalyzer.exe -cl C:\Folder filter-ext=mp4 compare=/ftyp save=C:\ComparisonFTYP.xlsx

However, we have only defined an output file for the second call. Therefore, the result is output to the console in the first call, while in the second call it is saved in the form of an Excel spreadsheet under the name "C:\ComparisonFTYP.xlsx".

If you want the saved file to be opened automatically after it is created, you can additionally add the parameter "openfile=1":

FileAnalyzer.exe -cl C:\Folder filter-ext=png compare=/ihdr save=C:\ComparisonIHDR.xlsx openfile=1

With this call we compare the image header (IHDR) of all PNG images from the folder "C:\Folder" and save the result under the name "C:\ComparisonIHDR.xlsx". The generated Excel sheet will be opened automatically immediately after it is generated because we have passed the parameter "openfile=1". By default, this parameter is not activated, so that the created file will only be opened automatically if we explicitly specify the parameter in this form.

In the next section you can find out in which formats the output can be made and how you can influence the format used.

Format of Storage and Console Output

When outputting the results in the form of a file, the format of the output is generally automatically determined via the file extension of the output file, which you pass via the save parameter. The formats currently supported are TXT (simple text file), CSV (Comma-Separated Values), TSV (Tab-Separated Values), XLSX (Excel Spreadsheet), ODS (Open Document Spreadsheet), DIF (Data Interchange Format) as well as HTM/ HTML (webpage). Each of the following example calls searches all files located in the specified folder "C:\Folder" for the text "abc" and outputs the result each in a different one of the supported formats:

FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.txt
FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.csv
FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.tsv
FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.xlsx
FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.ods
FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.dif
FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.htm
FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.html

Using the parameter "format", you are able to overwrite the format predetermined by the file extension. When saving as a file, the format parameter can take the values txt, csv, tsv, xlsx, ods, dif, htm or html. In practice, this can look like this:

FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.dat format=txt
FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.csv format=tsv

The first call saves the result under the name "Result.dat". Since the file extension "dat" does not yield to a clear format for storage, we use "format=txt" to instruct the FileAnalyzer to save in text format. The situation is different in the second call. Based on the file extension it would be saved in CSV format, but we would like to have a TSV file with the file extension "CSV". If the file extension does not provide a clear format and the format parameter is not specified, the file is saved in text format by default. In the first example, we could have omitted "format=txt" and still have achieved the same result.

If the output should be written directly into the console, the file extension is naturally missing as an indication of the desired storage format. Therefore, the format parameter has a special meaning in this case. In the following example, we want to output the result of our search in CSV format to the console. For this reason we pass the parameter "format=csv":

FileAnalyzer.exe -cl C:\Folder search-str=abc format=csv

When output to the console, the format parameter can take the values txt, csv, tsv, dif, htm or html. Accordingly, no binary formats are supported. If we do not explicitly specify the format parameter for a console output, the text format will be used by default in this case too. The default is therefore "format=txt".

By default, the text-file-based formats TXT, CSV, TSV, DIF, HTM and HTML are saved using the UTF-8 encoding without a byte order mark. As line break, the system line break type is used, thus CRLF for Windows. The field separator for the CSV export also depends on the system settings (comma or semicolon). You can override these defaults using the parameters enc (encoding), bom (byte order mark), lb (line break) and fs (field separator) parameters:

FileAnalyzer.exe -cl C:\Folder search-str=abc save=C:\Result.csv enc=utf32be bom=0 lb=cr fs=pipe

With this call, we save the search result in UTF-32 Big Endian Encoding without Byte Order Mark using the CR line break type and the | character (pipe) as a field separator. If we were to omit some of these parameters, the default values would be used. An overview of all the values that the 4 parameters can assume can be found in the overview table of all available parameters at the end of this tutorial.

Columns and Column Headings of the Output

Regardless of whether you want to save the result of your readout, comparison or search as a file or have it output into the console, you can configure the appearance of the result table using the two parameters cols and colh.

You can use the parameter "cols" (from columns) to specify which columns should be included in your table and in what order. The parameter "colh" (from column headers) can additionally used to determine whether your table should contain column headers or not.

More specifically, you can use the parameter "cols" to pass a comma-separated list of your desired columns. At the same time, you specify with this parameter the order of the columns, since the arrangement of the columns in the output table corresponds exactly to the order in which you have specified the columns with this parameter. The columns are specified using the column parameters, which you can find in the column parameter overview table. This table also shows which columns are available for which output and search types. The "colh" parameter, on the other hand, can only take the values 0 (no column headings) or 1 (table with column headings).

If you do not explicitly specify both or only one of the parameters, the corresponding default values of the parameter(s) not specified will be used for the output. These depend on the output or search type you use. For example, "get-val" defaults to using only the column "value" and no column headers for its output, while the compare function defaults to producing an output with column headers and multiple columns. The default configuration of the column parameters used for the various output and search types can be found in the overview table of the default columns directly following this section.

The following examples show the use of the two parameters:

FileAnalyzer.exe -cl C:\Icon.ico get-val=/FileHeader:NumberOfImages cols=value colh=0

With this call we want to read the number of images of an icon file and only output this value directly to the console without any additional columns or column headings. For this reason, in addition to passing the file path, we use the two parameters "cols=value" (we only define one column, the column "value" for outputting the value) as well as "colh=0" (we don't want any column headers in our table ). This means that our "table" ultimately only consists of one cell into which the number of images is written.

We proceed differently in the next example, in which we want to define several columns as well as a table design with column headings:

FileAnalyzer.exe -cl C:\Folder search-val=7 cols=file_name,chunk_path,property colh=1 save=7.xlsx

With this call we search all file structures of all files from the folder "C:\Folder" for the value 7, which we allow appear in any property, since we neither restrict the property itself nor the chunk path for the search in any way. As columns we define the name of the file (file_name), the chunk path in which the property with the value was found (chunk_path) as well as the name of the property found with the value 7 (property) in exactly this order. With the next parameter "colh=1" we explicitly specify that our table should have column headings and finally we tell the FileAnalyzer with the parameter "save=7.xlsx" that the result of this search should be saved as an Excel spreadsheet under the name "7.xlsx". In the first example, we omitted the save parameter, which causes the output to go directly to the console.

By the way, in our first example, we could have omitted the parameters "cols=value" and "colh=0" as well as the parameter "colh=1" specified in our second example, since these values also correspond exactly to the default values of these parameters for "get-val" respectively "search-val". Nevertheless, these parameters were deliberately set for the example calls to clarify the difference between the two situations.

Overview of the Default Columns of the various Output and Search Types

The various parameters for reading values, for comparing chunks and properties as well as for the different search types are using different default values for the columns used in their output. These default values are used if you do not explicitly specify the parameters cols and/or colh in order to overwrite the default value and are listed for the two parameters in the following table.

The different search types for byte sequences (search-bytes), numbers (search-uint.../search-sint...) and strings (search-str) each use the same default values for their columns. The search within the file structure (search-path, search-prop and/or search-val) uses two additional columns by default.

To learn more about using the column parameters cols and colh, see the section about configuring the columns and column headings of the output. In the next section you will additionally find a table of all available column parameters including a description and an example for each parameter as well as an overview of which columns you can combine with which output or search type.

Overview of all Column Parameters

In the following table you can see an overview of all available column parameters and their meaning. For clarification, we show possible values of the respective parameter in the column "Example", as they could result when reading out the duration of the movie header chunk (mvhd) of an MP4 file. The last four columns list whether the respective parameter can be used (D or ●) for the various output and search types get-val (V), compare (C), search-bytes / search-int / search-str (S) or the file structure search (F) or is even used as a default column (D) by the parameter in question.

The difference between the parameters "value" and "values" is that "value" only represents one column (like all the other parameters listed) while "values" can create several columns. When simply reading out individual values, for example via the search functions (S and F) or via "get-val" (V), always the "value" parameter is used, while "values" is only used for the comparison function (C) with its compare parameter.

Since the comparison function can be used to compare any number of properties with each other and also the different chunks to be compared can contain an indefinite number of properties, we need this variable parameter to suit this particular situation so that we do not have to define all of these columns (possibly of unknown nature) individually by hand. However, the columns that are hidden behind "values" can nevertheless be determined both in their type and in their order by restricting the comparison function to individual properties and thus determining your desired properties not via the parameter "cols" but via the parameter "compare". For more detailed explanations and examples, see the section on comparing individual properties across multiple files.

How you can use the column parameters presented here to configure the columns of your result output, you can see in the section about configuring the output columns.

Overview of all available Parameters

The following table shows an overview of all available parameters that you can use in FileAnalyzer's batch mode. The name of the parameter can be found in the first column. The second column contains a list of all values that the respective parameter can take. The following column shows the default value, which is used if the respective parameter is not explicitly specified. In addition, you will find a brief description of the parameter in the last column. Often, in this column you can also find a link to the section of this tutorial where the parameter in question is explained and where you can also find examples of its use.

If a parameter is written in italics in the first column, this means that the corresponding parameter is an additional parameter for the last parameter not written in italics and can only be used together with it.

Grundsätzlich können alle in dieser Tabelle aufgeführten Parameter frei miteinander kombiniert und innerhalb des selben Aufrufs des FileAnalyzers gemeinsam miteinander verwendet werden. Eine Ausnahme bilden die Parameter zum Auslesen und Vergleichen von Chunks, Werten und Eigenschaften (get-val und compare) sowie die Parameter für die Suche von Bytesequenzen (search-bytes), die Suche von Zahlen, die Suche von Strings (search-str) und die Suche innerhalb der Dateistruktur (search-path, search-prop und/oder search-val). Von diesen Parametergruppen kann jeweils nur einer gleichzeitig angewendet werden. In welcher Reihenfolge die einzelnen Parameter dem FileAnalyzer übergeben werden, spielt dagegen keine Rolle.

Generally, all parameters listed in this table can be freely combined with each other and used together within the same FileAnalyzer call. An exception are the parameters for reading and comparing chunks, values and properties (get-val and compare) as well as the parameters for searching byte sequences (search-bytes), searching for numbers, searching for strings (search-str) and searching within the file structure (search-path, search-prop and/or search-val). Only one of these parameter groups can be applied at the same time. However, it does not matter in which order the individual parameters are passed to the FileAnalyzer.

If the FileAnalyzer is called without defining a specific parameter, the value from the column "Default" of this table is assumed for this parameter. If the value "-" is specified in the "Default" column of a parameter, this means that the parameter in question is empty by default and is therefore not used if it is not explicitly defined.