1[manpage_begin crc16 n 1.1.1]
2[copyright {2002, Pat Thoyts}]
3[moddesc   {Cyclic Redundancy Checks}]
4[titledesc {Perform a 16bit Cyclic Redundancy Check}]
5[category  {Hashes, checksums, and encryption}]
6[require Tcl 8.2]
7[require crc16 [opt 1.1.1]]
8[description]
9[para]
10
11This package provides a Tcl-only implementation of the CRC
12algorithms based upon information provided at
13http://www.microconsultants.com/tips/crc/crc.txt
14
15There are a number of permutations available for calculating CRC
16checksums and this package can handle all of them. Defaults are set up
17for the most common cases.
18
19[section COMMANDS]
20
21[list_begin definitions]
22
23[call [cmd ::crc::crc16] [opt "-format [arg format]"] \
24  [opt "-seed [arg value]"] [opt "-implementation [arg procname]"] [arg message]]
25[call [cmd ::crc::crc16] [opt "-format [arg format]"] \
26  [opt "-seed [arg value]"] [opt "-implementation [arg procname]"] "-filename [arg file]"]
27[call [cmd ::crc::crc-ccitt] [opt "-format [arg format]"] \
28  [opt "-seed [arg value]"] [opt "-implementation [arg procname]"] [arg message]]
29[call [cmd ::crc::crc-ccitt] [opt "-format [arg format]"] \
30  [opt "-seed [arg value]"] [opt "-implementation [arg procname]"] "-filename [arg file]"]
31[call [cmd ::crc::xmodem] [opt "-format [arg format]"] \
32  [opt "-seed [arg value]"] [opt "-implementation [arg procname]"] [arg message]]
33[call [cmd ::crc::xmodem] [opt "-format [arg format]"] \
34  [opt "-seed [arg value]"] [opt "-implementation [arg procname]"] "-filename [arg file]"]
35
36The command takes either string data or a file name and returns a checksum
37value calculated using the CRC algorithm. The command used sets up the
38CRC polynomial, initial value and bit ordering for the desired
39standard checksum calculation. The result is formatted
40using the [arg format](n) specifier provided or as an unsigned integer
41(%u) by default.
42
43[para]
44
45A number of common polynomials are in use with the CRC algorithm and
46the most commonly used of these are included in this package. For
47convenience each of these has a command alias in the crc namespace.
48
49[para]
50
51It is possible to implement the CRC-32 checksum using this crc16
52package as the implementation is sufficiently generic to extend to 32
53bit checksums. As an example this has been done already - however this
54is not the fastest method to implement this algorithm in Tcl and a
55separate [package crc32] package is available.
56
57[list_end]
58
59[section OPTIONS]
60
61[list_begin definitions]
62
63[def "-filename [arg name]"]
64
65Return a checksum for the file contents instead of for parameter data.
66
67[def "-format [arg string]"]
68
69Return the checksum using an alternative format template.
70
71[def "-seed [arg value]"]
72
73Select an alternative seed value for the CRC calculation. The default
74is 0 for the CRC16 calculation and 0xFFFF for the CCITT version.
75This can be useful for calculating the CRC for data
76structures without first converting the whole structure into a
77string. The CRC of the previous member can be used as the seed for
78calculating the CRC of the next member. It is also used for
79accumulating a checksum from fragments of a large message (or file)
80
81[def "-implementation [arg procname]"]
82
83This hook is provided to allow users to provide their own
84implementation (perhaps a C compiled extension). The
85procedure specfied is called with two parameters. The first is the
86data to be checksummed and the second is the seed value. An
87integer is expected as the result.
88[para]
89The package provides some implementations of standard CRC polynomials
90for the XMODEM, CCITT and the usual CRC-16 checksum. For convenience,
91additional commands have been provided that make use of these
92implementations.
93
94[list_end]
95
96[section EXAMPLES]
97
98[para]
99[example {
100% crc::crc16 "Hello, World!"
10164077
102}]
103
104[para]
105[example {
106% crc::crc-ccitt "Hello, World!"
10726586
108}]
109
110[para]
111[example {
112% crc::crc16 -format 0x%X "Hello, World!"
1130xFA4D
114}]
115
116[para]
117[example {
118% crc::crc16 -file crc16.tcl
11951675
120}]
121
122[see_also sum(n) cksum(n) crc32(n)]
123[section AUTHORS]
124Pat Thoyts
125
126[section {BUGS, IDEAS, FEEDBACK}]
127
128This document, and the package it describes, will undoubtedly contain
129bugs and other problems.
130
131Please report such in the category [emph crc] of the
132[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
133
134Please also report any ideas for enhancements you may have for either
135package and/or documentation.
136
137
138[keywords cksum checksum crc crc32 crc16 {cyclic redundancy check} {data integrity} security]
139[manpage_end]
140