wxChecksums > Manual

wxChecksums 1.2.0 manual

Copyright © 2003-2004 Julien Couot.
http://wxchecksums.sourceforge.net/

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.


Table of contents

Introduction
Installation
Windows
Linux
Using wxChecksums
Checksums' files
Management of checksums' files
Check multiple checksums' files
Batch creation of checksums' files
Invoke wxChecksums from the command line
Configuration
Configuration files
User preferences
Available languages
License
Author
Links

Introduction

wxChecksums is a program which calculates and verifies checksums1. So you can check the integrity of one or more files.

wxChecksums is able to read and write files in SFV and MD5 (files generated by md5sum) format.

wxChecksums is available under Windows 9x/Me/2000/XP and Linux.

Note: In this manual some dialogs will be in french because I cannot have access to a Windows in english language. If you have Windows in english, all the dialogs should be displayed in english.

Back to the table of contents.


Installation

Windows

There is three ways to install wxChecksums:

Note: If you are using Windows NT, Windows 2000 or Windows XP Professional, launch the installer from an administrator account if you want to create icons in the start menu for all the users of the machine. If you to wish to create icons in the start menu only for you, launch the installer from your account.

Note: A shell extension for the Windows' explorer is also available. It permits you to creates checksums' files directly from the explorer. For more information, please see the web page of wxChecksums Shell Extension for Microsoft Windows.

Linux

A RPM package is provided for Mandrake Linux 9.2. For others Linux distributions, please compile the source code with the instructions given in the COMPILE.txt file.

Back to the table of contents.


Using wxChecksums

Checksums' files

The checksums' files are files which contain information that check the integrity of other files. There are various methods to calculate a checksum.

wxChecksums currently manages two types of files:

The checksums can only check the integrity of the files and cannot repair them. If you wish a tool allowing you to check the integrity of the files and to repair them, visit the site of Parchive.

The checksums' files store only information to check the integrity of the files, not the files themselves.

Relative and absolute file names

The relative file names are file names given from a reference directory. The absolute file names are file names whose path is completely defined.

Example:

The file names are stored in the relative form in the cheksums' files. The reference directory is which where the checksums' file itself is stored.

It is strongly advised to save the checksums' file in the directory where the files to be checked are.

Management of the checksums' files

Here the main window of wxChecksums:

This window is composed of:

Creation of a checksums' file

The creation of a file is done by the File> New... menu or by the tool.

Choose the type and the name of the new checksums' file in the following dialog:

The Browser... button allows you to choose a file name with a traditional dialog:

Opening of a checksums' file

The opening of a checksums' file can be done in two ways:

Saving the checksums' file

When a checksums' file was modified, you can save it by the File > Save menu or by the tool.

To save the checksums' file under another name, use the File > Save as... menu.

Closing of the checksums' file

Use the File > Close menu.

Adding files in the checksums' file

Adding files in the checksums' file can be done in four ways:

Note: if a file is already present in the checksums' file, it is not added.

Removing files from the checksums' file

To remove files from the checksums' file, use the Sums > Remove menu. The files are removed from the checksums' file but not from the disc.

Checking files

To check the integrity of the files, use the Sums > Check menu or the tool . If no file is selected all the files will be checked.

Recomputing the checksum of the files

To recompute the checksum of the files, use the Sums > Recompute menu or the tool . The checksums will be recomputed only for the selected files.

Check multiple checksums' files

It is possible to check simultaneously several checksums' files, by the command Tools > Check multiple checksums' files....

The first dialog permits you to choose the checksums' files to check:

This dialog works like the Add matching files dialog, but the Search and add button launch immediately the file search and you can only specify absolute directory names.

Once the checksums' files to check are selected, the following progress dialog is displayed:

The displayed information can be set in the Multiple check section of the settings dialog.

Batch creation of checksums' files

The batch creation of checksums' files permits you to create one or more checksums' file types per file that you have previously selected. The batch creation of checksums' files is accessible by the command Tools > Batch creation of checksums' files....

The first dialog permits you to choose the files from which the checksums' files will be created:

This dialog works like the Add matching files dialog, but the Search and add button launch immediately the file search and you can only specify absolute directory names.

Select at least one type of checksum' file to create for each selected file.

The Options... button permits you to temporary (for the current batch creation process) change the default options for the batch creation of checksums' file defined in the configuration dialog:

For more information on these parameters, please see the Batch creation section of the configuration dialog.

Once the files to process are selected, the following progress dialog is displayed:

Invoke wxChecksums from the command line

The general form of the command line of wxChecksums is:
wxcksums [-h] [-V] [-v] [-a str] [-c str] [-ct str] [-fl str] [--delete-temp-list] [file(s)...]

Note that the files with jokers ('*' and '?') are not treated.

Here is a table that sums up the switchs and options that wxChecksums accepts:

Long option name Short option name Type Can't be used with Can be used with Description
--help -h Switch   All Shows an help message.
--version -V Switch   All Shows the version of wxChecksums.
--verify -v Switch -a, -c -ct (-ct is ignored), -fl Verifies the given checksums' file. Only one checksums' file can be specified.
--append=<str> -a str Option (string) -c, -v -ct, -fl Appends to the given checkums' file the given list of files. If the checksums' file doesn't exist, it is created.
--create=<str> -c str Option (string) -a, -v -ct, -fl Creates the given checkums' file and adds to it the given list of files. If the checksums' file exists, it is overwrited (without any warning message). Prefer in general the append option.
--create-type=<str> -ct str Option (string)  

-a, -c, -v, -fl

Specifies the type of checksums' file to create if it doesn't exist. If this option is not given, wxChecksums uses the extension of the given checksums' file: md5 for an MD5 checksums' file; for all others extensions a SFV checksums' file is created.
--file-list=<str> -fl str Option (string)   -a, -c, -v, -ct Specifies file(s) that contain a list of names of files. Theses files are text files with one name of file by line. You can specify several lists of files by separating them by the '|' character.
--delete-temp-list   Switch   -fl When specifying a list of names of files with the -fl option, deletes those which are temporary. A list of names of files is considered temporary when the extension of the file that contains the list matches one of the extensions specified by the Files/TempExts entry in the configuration file of wxChecksums. Default extensions are tmp and temp. See the Configuration file section for more information.

Examples:

wxcksums -a wxChecksums-x-x-x.md5 wxChecksums-x.x.x
Appends to the wxChecksums-x-x-x.md5 checksums' file the files that are in the wxChecksums-x.x.x directory. If wxChecksums-x-x-x.md5 MD5 checksums' file doesn't exist, it is created.

wxcksums -v C:\Progs\wxChecksums\wxChecksums-x-x-x.sfv
wxcksums -v wxChecksums-x-x-x.sfv
Checks the wxChecksums-x-x-x.sfv checksums' file.

wxcksums -c wxChecksums.sfv -fl "wxChecksums-1.0.0\wxChecksums-1.0.0.txt|wxChecksums-1.1.0\wxChecksums-1.1.0.tmp" --delete-temp-list -ct sfv README.txt NEWS.txt
Creates or overwrites the checksums' file wxChecksums.sfv, loads the files' names contained in wxChecksums-1.0.0\wxChecksums-1.0.0.txt and wxChecksums-1.1.0\wxChecksums-1.1.0.tmp, deletes the file wxChecksums-1.1.0\wxChecksums-1.1.0.tmp, adds to wxChecksums.sfv the files README.txt and NEWS.txt, adds to wxChecksums.sfv the files listed in wxChecksums-1.0.0\wxChecksums-1.0.0.txt and wxChecksums-1.1.0\wxChecksums-1.1.0.tmp.

wxcksums "C:\Documents and Settings\My account\My checksums file.txt"
Opens C:\Documents and Settings\My account\My checksums file.txt in wxChecksums.

Configuration

The dialog box of configuration of wxChecksums is accessible by the Settings > Configure wxChecksums... or by the tool. It is composed of six panels:

This dialog is resizable and its dimensions are saved when you validate it.

Display

Behavior

Language

This tab enables you to choose the language that wxChecksums must use. The Language of the system option uses the language of the system if it is available, if not english is used by default.

Command line

These parameters defines the behavior of the GUI when wxChecksums is called with options in the command line.

Note: If you use the wxChecksums Shell Extension for Microsoft Windows, these parameters apply for it too because this extension uses the wxChecksums command line to process the action selected by the user.

If the Don't show the GUI if all the checksums are correct option is checked and if you use the --verify switch, the GUI is shown only if one or more checksums are incorrect. If all the checksums are correct and if the Opens a dialog box to sum up the check option in the Behavior page is not checked, no message is displayed to sum up the check.

The When adding files to a checksums' file and When creating a checksums' file options respectively set when to show the GUI when using the --append and --create options. An error can be for example that the checksums' file can't be saved. For the moment no warnings can occurs but future releases of wxChecksums can have it.

SFV files

The parameters presented above are the default settings. They have been defined to ensure a maximum compatibility with the other software that use SFV files.

MD5 files

The parameters presented above are the default settings. They have been defined to ensure a maximum compatibility with md5sum.

Multiple check

Batch creation

After computing the checksum(s) of a file, wxChecksums try to save the checksums' file(s). The naming of these checksums' files can be changed in the Create the name of the checksums' file by section:

When wxChecksums tries to save the checksums' files, if a checksums' file already exists, you can make wxChecksums:

The verbosity level permits you to choose the quantity of the information displayed in the progress dialog:

Errors only Display errors only.
Errors and warnings Display errors and warnings only.
Normal Display all the useful messages.
Talkative Display additional information (like the values of the calculated checksums).

The buttons of the Text colours box allow to change the colour of the text used in the dialog of batch creation of checksums' files.

Back to the table of contents.


Configuration files

User preferences

wxChecksums.ini is a text file which can be edited with a simple text editor.

Here the descrition of the entries:

Key Type Values Description
GUI/ConfigDlg/WindowSize int,int   Size of the configuration dialog box.
GUI/ConfigDlg/SashPosition int   Position of the separator between the tree of selection of the preferences and the preference panels.
GUI/Main/SaveWindowPosition bool   Save and restore the position of the main window.
GUI/Main/SaveWindowSize bool   Save and restore the size of the main window.
GUI/Main/WindowPosition int,int   Position of the main window.
GUI/Main/WindowSize int,int   Size of the main window.
GUI/Main/ShowToolbar bool   Show the tools bar.
GUI/Main/ShowStatusbar bool   Show the status bar.
GUI/Main/LastDirectory string   Last directory used for the opening of the checksums' files.
GUI/Main/ChecksumsList/SaveColumnToSort bool   Save the column to sort (and the order).
GUI/Main/ChecksumsList/ColumnToSort int 0-3 The column to sort.
GUI/Main/ChecksumsList/SaveColumnSortOrder int 0-2 The sort order of the column.
GUI/Main/ChecksumsList/SaveColumnsWidths bool   Save the width of the columns.
GUI/Main/ChecksumsList/DirsInAbsolutePath bool   Display directory paths in absolute mode.
GUI/Main/ChecksumsList/Uppercase bool   Display the checksums in uppercase (1) or in lowercase (0).
GUI/Main/ChecksumsList/HRules bool   Draws light horizontal rules between rows.
GUI/Main/ChecksumsList/VRules bool   Draws light vertical rules between columns.
GUI/Main/ChecksumsList/ColumnWidthFileName int 1- Width of the column File name.
GUI/Main/ChecksumsList/ColumnWidthDirectory int 1- Width of the column Directory.
GUI/Main/ChecksumsList/ColumnWidthChecksumValue int 1- Width of the column Checksum value.
GUI/Main/ChecksumsList/ColumnWidthState int 1- Width of the column State.
GUI/Main/ChecksumsList/ColumnFirst int 0-3 Element of the first column (0 = file name, 1 = directory, 2 = checksum value, 3 = state).
GUI/Main/ChecksumsList/ColumnSecond int 0-3 Element of the second column.
GUI/Main/ChecksumsList/ColumnThird int 0-3 Element of the third column.
GUI/Main/ChecksumsList/ColumnFourth int 0-3 Element of the fourth column.
GUI/Main/History/FileXX string   Name of the checksums' files recently opened. XX is an integer between 00 and 16.
GUI/NewFile/LastDirectory string   Last directory used for the creation of a new checksums' files.
GUI/NewFile/LastFileType int 1-2 Last type of created checksums' file (1 = SFV, 2 = MD5).
GUI/Behavior/AutoCheckOnOpen bool   Checks automatically the checksums file when opening it.
GUI/Behavior/DlgSumUpCheck bool   Opens a dialog box to sum up the check.
GUI/Behavior/WarnOnInvalidWhenSaving bool   Displays a warning if the state of all the files is not 'OK' when saving a checksums file.
GUI/CommandLine/DontShowWhenAllCorrect bool   Don't show the GUI when all the checksums are correct.
GUI/CommandLine/AppendShowGUI int 0-3 Show the GUI when using the --append option (0 = never, 1 = on errors, 2 = on errors or warnings, 3 = always).
GUI/CommandLine/CreateShowGUI int 0-3 Show the GUI when using the --create option (0 = never, 1 = on errors, 2 = on errors or warnings, 3 = always).
GUI/AddMatchingFilesDlg/WindowSize int,int   Size of the dialog of adding files using matching patterns.
GUI/AddMatchingFilesDlg/LastSaveListDirectory string   Name of the last directory used when saving the list of the matching patterns.
GUI/AddMatchingFilesDlg/LastAddListDirectory string   Name of the last directory used when adding a list of matching patterns.
GUI/AddMatchingFilesDlg/LastLoadListDirectory string   Name of the last directory used when loading a list of matching patterns.
GUI/AddMatchingFilesDlg/History/MatchPatternXX string   History of the matching patterns entered in the field Pattern(s). XX is an interger between 00 and 16.
GUI/AddMatchingFilesDlg/History/DirectoryXX string   History of the directories entered in the field Directory. XX is an interger between 00 and 16.
GUI/AddMatchingFilesDlg/PatternsList/SortBy int 0-2 Sort the list of the matching patterns directory (0), matching pattern (1), depth (2).
GUI/AddMatchingFilesDlg/PatternsList/SortOrder int 0-2 The sort order (0 = ascending, 1 = descending, 2 = no sort).
GUI/AddMatchingFilesDlg/PatternsList/ColumnWidthDirectory int   Width of the column of the directories.
GUI/AddMatchingFilesDlg/PatternsList/ColumnWidthPatterns int   Width of the column of the matching patterns.
GUI/AddMatchingFilesDlg/PatternsList/ColumnWidthDepth int   Width of the column of the depths.
GUI/MultiCheck/GlobalSummary bool   Display a global summary.
GUI/MultiCheck/ChecksumsFileSummary bool   Display a summary for each checksums' file.
GUI/MultiCheck/FileState bool   Display the state of each checked file.
GUI/MultiCheck/NoCorrectFileState bool   Don't display the state of the correct files.
GUI/MultiCheck/NormalColour int   Colour of the normal text in the dialog of checking of several checksums' files.
GUI/MultiCheck/SuccessColour int   Colour of the text that indicates a success in the dialog of checking of several checksums' files.
GUI/MultiCheck/WarningColour int   Colour of the text that indicates a warning in the dialog of checking of several checksums' files.
GUI/MultiCheck/ErrorColour int   Colour of the text that indicates an error in the dialog of checking of several checksums' files.
GUI/MultiCheck/WindowSize int,int   Size of the dialog of checking of several checksums' files.
GUI/MultiCheckConfigDlg/WindowSize string   Size of the dialog for select the checksums' files to check.
GUI/MultiCheckConfigDlg/LookInBrowseLastDir string   Name of the last directory selected by the Browse command.
GUI/MultiCheckConfigDlg/LastSaveListDirectory string   Name of the last directory used when saving the list of the checksums' files to check.
GUI/MultiCheckConfigDlg/LastAddListDirectory string   Name of the last directory used when adding a list of checksums' files to check.
GUI/MultiCheckConfigDlg/LastLoadListDirectory string   Name of the last directory used when loading a list of checksums' files to check.
GUI/MultiCheckConfigDlg/History/NamedXX string   History of the names of files or mathing patterns entered in the field Named. XX is an interger between 00 and 16.
GUI/MultiCheckConfigDlg/History/LookInXX string   History of the directories entered in the field Look in. XX is an interger between 00 and 16.
GUI/MultiCheckConfigDlg/FilesList/SortBy int 0-1 Sort the list of the checksums' files to check by file name (0) or directory name (1).
GUI/MultiCheckConfigDlg/FilesList/SortOrder int 0-2 The sort order (0 = ascending, 1 = descending, 2 = no sort).
GUI/MultiCheckConfigDlg/FilesList/ColumnWidthFileName int   Width of the column of the file names.
GUI/MultiCheckConfigDlg/FilesList/ColumnWidthDirectory int   Width of the column of the directories.
GUI/BatchCreation/OvrCkFileWhenItExists bool   If true (=1) overwrites the checksums' file when it exists in the batch creation of checksums' files process. Otherwise skips the creation of the checksums' file.
GUI/BatchCreation/ReplaceExtension bool   If true (=1) names the created checksums' file by replacing the extension of the source file with the extension of the type of the checksums' file. Otherwise names the created checksums' file by adding the extension of the type of the checksums' file to the name of the source file.
GUI/BatchCreation/VerbosityLevel int 0-3 Verbosity level (0 = errors only, 1 = errors and warnings, 2 = normal, 3 = talkative).
GUI/BatchCreation/NormalColour int   Colour of the normal text in the dialog of checking of batch creation of checksums' files.
GUI/BatchCreation/SuccessColour int   Colour of the text that indicates a success in the dialog of batch creation of checksums' files.
GUI/BatchCreation/WarningColour int   Colour of the text that indicates a warning in the dialog of batch creation of checksums' files.
GUI/BatchCreation/ErrorColour int   Colour of the text that indicates an error in the dialog of batch creation of checksums' files.
GUI/BatchCreation/WindowSize int,int   Size of the dialog of batch creation of checksums' files.
GUI/BatchCreationConfigDlg/WindowSize string   Size of the dialog for selecting the files for the batch creation of checksums' files.
GUI/BatchCreationConfigDlg/LookInBrowseLastDir string   Name of the last directory selected by the Browse command.
GUI/BatchCreationConfigDlg/LastSaveListDirectory string   Name of the last directory used when saving the list of the files on which the batch creation of checksums' files should be made.
GUI/BatchCreationConfigDlg/LastAddListDirectory string   Name of the last directory used when adding a list of the files on which the batch creation of checksums' files should be made.
GUI/BatchCreationConfigDlg/LastLoadListDirectory string   Name of the last directory used when loading a list of the files on which the batch creation of checksums' files should be made.
GUI/BatchCreationConfigDlg/History/NamedXX string   History of the names of files or mathing patterns entered in the field Named. XX is an interger between 00 and 16.
GUI/BatchCreationConfigDlg/History/LookInXX string   History of the directories entered in the field Look in. XX is an interger between 00 and 16.
GUI/BatchCreationConfigDlg/FilesList/SortBy int 0-1 Sort the list of the files on which the batch creation of checksums' files should be made by file name (0) or directory name (1).
GUI/BatchCreationConfigDlg/FilesList/SortOrder int 0-2 The sort order (0 = ascending, 1 = descending, 2 = no sort).
GUI/BatchCreationConfigDlg/FilesList/ColumnWidthFileName int   Width of the column of the file names.
GUI/BatchCreationConfigDlg/FilesList/ColumnWidthDirectory int   Width of the column of the directories.
ChecksumsFiles/SFV/ReadPathSeparator int   Path separator on reading SFV files.
ChecksumsFiles/SFV/WriteGeneratorAndDate bool   Save the name of the generator and the date of creation in the comments.
ChecksumsFiles/SFV/WriteFileSizeAndDate bool   Save the size and the modification date of the files in the comments.
ChecksumsFiles/SFV/WritePathSeparator int   Path separator on writing.
ChecksumsFiles/SFV/WriteEndOfLine int   End of line of writng.
ChecksumsFiles/SFV/IdentifyAs/Generator string   Name of the generator used actually. If it is empty, the name of the application is used.
ChecksumsFiles/SFV/IdentifyAs/History/IdentifyXX string   History of the names of generator entered. XX is an interger between 00 and 16.
ChecksumsFiles/MD5/ReadPathSeparator int   Path separator on reading MD5 files.
ChecksumsFiles/MD5/WriteGeneratorAndDate bool   Save the name of the generator and the date of creation in the comments.
ChecksumsFiles/MD5/WriteFileSizeAndDate bool   Save the size and the modification date of the files in the comments.
ChecksumsFiles/MD5/WritePathSeparator int   Path separator on writing.
ChecksumsFiles/MD5/WriteEndOfLine int   End of line of writng.
Engine/ReadBuffer int 1- Size of the buffer for reading files. Default value: 0xFFFF.
Language/Name string en, fr Language of the user interface.
Files/TempExts string   List of file extensions separated by a space. wxChecksums considers that the lists of files given with the --file-list option which have an extension that is present is this parameter are temporary lists of files and must be deleted. Default value for this parameter is 'tmp temp'.

Available languages

From wxChecksums 1.2.0, wxChecksums uses a configuration file to determine which languages are availables. If wxChecksums doesn't find this file, english will be the only available language. The contents of this file won't be described in this manual because it's not useful to the end-users.

Under Windows, wxChecksums searches for this file in the following locations:

Under Unix, wxChecksums searches for this file in the following locations:

Back to the table of contents.


License

wxChecksums is released under the GNU GENERAL PUBLIC LICENSE.
See the LICENSE.txt and gpl.txt files for more details.

wxChecksums uses the wxWidgets toolkit. Please consult its website to take note of its license.

Back to the table of contents.


Author

Julien Couot <jcouot at users.sourceforge.net>

Back to the table of contents.


Links

http://wxchecksums.sourceforge.net/
- wxChecksums homepage.

http://www.jrsoftware.org/
- Inno Setup homepage.

http://www.gnu.org/
- GNU project homepage.

Back to the table of contents.


Notes:

1. Checksum (from Wikipedia):
In computer technology, a checksum is a very simple integrity-protection measure. It is used mainly in data storage, and networking protocols.

It works by adding up the bytes, or some other basic components in a string of data, and storing the resulting value.

Later, anyone (who has the authentic checksum) can verify that the message was not corrupted by doing the same operation on the data, and "checking" the "sum".

Back to the table of contents.