1[manpage_begin crc32 n 1.3]
2[copyright {2002, Pat Thoyts}]
3[moddesc   {Cyclic Redundancy Checks}]
4[titledesc {Perform a 32bit Cyclic Redundancy Check}]
5[category  {Hashes, checksums, and encryption}]
6[require Tcl 8.2]
7[require crc32 [opt 1.3]]
8[description]
9[para]
10
11This package provides a Tcl implementation of the CRC-32
12algorithm based upon information provided at
13http://www.naaccr.org/standard/crc32/document.html
14
15If either the [package critcl] package or the [package Trf] package
16are available then a compiled version may be used internally to
17accelerate the checksum calculation.
18
19[section COMMANDS]
20
21[list_begin definitions]
22
23[call [cmd "::crc::crc32"] \
24        [opt "-format [arg format]"] \
25        [opt "-seed [arg value]"] \
26        [lb] [arg "-channel chan"] | \
27             [arg "-filename file"] | \
28             [arg message] [rb]]
29
30The command takes either string data or a channel or file name and
31returns a checksum value calculated using the CRC-32 algorithm. The
32result is formatted using the [arg format](n) specifier provided. The
33default is to return the value as an unsigned integer (format %u).
34
35[list_end]
36
37[section OPTIONS]
38
39[list_begin definitions]
40
41[def "-channel [arg name]"]
42
43Return a checksum for the data read from a channel. The command will
44read data from the channel until the [cmd "eof"] is true. If you need
45to be able to process events during this calculation see the
46[sectref {PROGRAMMING INTERFACE}] section
47
48[def "-filename [arg name]"]
49
50This is a convenience option that opens the specified file, sets the
51encoding to binary and then acts as if the [arg -channel] option had
52been used. The file is closed on completion.
53
54[def "-format [arg string]"]
55
56Return the checksum using an alternative format template.
57
58[def "-seed [arg value]"]
59
60Select an alternative seed value for the CRC calculation. The default
61is 0xffffffff. This can be useful for calculating the CRC for data
62structures without first converting the whole structure into a
63string. The CRC of the previous member can be used as the seed for
64calculating the CRC of the next member.
65
66Note that the crc32 algorithm includes a final XOR step. If
67incremental processing is desired then this must be undone before
68using the output of the algorithm as the seed for further
69processing. A simpler alternative is to use the 
70[sectref {PROGRAMMING INTERFACE}] which is intended for this mode of
71operation.
72
73[list_end]
74
75[section {PROGRAMMING INTERFACE}]
76
77The CRC-32 package implements the checksum using a context variable to
78which additional data can be added at any time. This is expecially
79useful in an event based environment such as a Tk application or a web
80server package. Data to be checksummed may be handled incrementally
81during a [cmd fileevent] handler in discrete chunks. This can improve
82the interactive nature of a GUI application and can help to avoid
83excessive memory consumption.
84
85[list_begin definitions]
86
87[call [cmd "::crc::Crc32Init"] [opt [arg "seed"]]]
88
89Begins a new CRC32 context. Returns a token ID that must be used for the
90remaining functions. An optional seed may be specified if required.
91
92[call [cmd "::crc::Crc32Update"] [arg "token"] [arg "data"]]
93
94Add data to the checksum identified by token. Calling 
95[emph {Crc32Update $token "abcd"}] is equivalent to calling
96[emph {Crc32Update $token "ab"}] followed by 
97[emph {Crc32Update $token "cb"}]. See [sectref {EXAMPLES}].
98
99
100[call [cmd "::crc::Crc32Final"] [arg "token"]]
101
102Returns the checksum value and releases any resources held by this
103token. Once this command completes the token will be invalid. The
104result is a 32 bit integer value.
105
106[list_end]
107
108[section EXAMPLES]
109
110[para]
111[example {
112% crc::crc32 "Hello, World!"
1133964322768
114}]
115
116[para]
117[example {
118% crc::crc32 -format 0x%X "Hello, World!"
1190xEC4AC3D0
120}]
121
122[para]
123[example {
124% crc::crc32 -file crc32.tcl
125483919716
126}]
127
128[para]
129[example {
130% set tok [crc::Crc32Init]
131% crc::Crc32Update $tok "Hello, "
132% crc::Crc32Update $tok "World!"
133% crc::Crc32Final $tok
1343964322768
135}]
136
137[see_also sum(n) cksum(n) crc16(n)]
138[section AUTHORS]
139Pat Thoyts
140
141[section {BUGS, IDEAS, FEEDBACK}]
142
143This document, and the package it describes, will undoubtedly contain
144bugs and other problems.
145
146Please report such in the category [emph crc] of the
147[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
148
149Please also report any ideas for enhancements you may have for either
150package and/or documentation.
151
152
153[keywords cksum checksum crc crc32 {cyclic redundancy check} {data integrity} security]
154[manpage_end]
155