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