1 |
%$Header$ |
2 |
|
3 |
\chapter[\ccchzeroshorttitle{}]{\ccchzerolongtitle{}} |
4 |
|
5 |
\label{ccch0} |
6 |
|
7 |
\beginchapterquote{``\ldots{} Beauty is the first test: there is no permanent |
8 |
place in the world for ugly mathematics.''} |
9 |
{G.H. Hardy \cite{bibref:b:mathematiciansapology:1940}, |
10 |
p.85} |
11 |
|
12 |
\section{Introduction} |
13 |
%Section Tag: INT |
14 |
|
15 |
|
16 |
\section{crc32} |
17 |
|
18 |
\begin{tclcommandname}{crc32}% |
19 |
generates the CRC-32 of a file or string. This CRC can be reliably used to obtain |
20 |
digital signatures of files or data. |
21 |
\end{tclcommandname} |
22 |
|
23 |
\begin{tclcommandsynopsis} |
24 |
\tclcommandsynopsisline{crc32}{filename} |
25 |
\tclcommandsynopsisline{crc32}{-string binarystringval} |
26 |
\tclcommandsynopsisline{crc32}{-initialstate} |
27 |
\tclcommandsynopsisline{crc32}{-advancestate state filename} |
28 |
\tclcommandsynopsisline{crc32}{-advancestate -string state binarystringval} |
29 |
\tclcommandsynopsisline{crc32}{-crcfromstate state} |
30 |
\end{tclcommandsynopsis} |
31 |
|
32 |
\begin{tclcommanddescription} |
33 |
The \emph{crc32} command forms the CRC-32 of the binary contents of a file |
34 |
or of the binary contents of a string. The CRC-32 is useful as a digital |
35 |
signature, and can be used with unity probability to determine that two |
36 |
files are different, or with a probability of about $1-2^{-32}$ to determine |
37 |
that two files are almost certainly identical. |
38 |
|
39 |
In the invocations below, the CRC-32 is always returned as a 10-character ASCII string |
40 |
of the form \emph{``0xDDDDDDDD''}, where \emph{``DDDDDDDD''} is the hexadecimal representation |
41 |
of the 32-bit CRC-32, and \emph{``0x''} is a constant 2-character prefix which is included for |
42 |
aesthetics. It is guaranteed that: |
43 |
|
44 |
\begin{itemize} |
45 |
\item The string returned will be exclusive ASCII. |
46 |
\item The string will have a length of exactly 10 characters. |
47 |
\item The first two characters of the string will be \emph{``0x''}. |
48 |
\item Any letters in the hexadecimal representation will be upper-case. |
49 |
\end{itemize} |
50 |
|
51 |
\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{filename}} |
52 |
Returns the CRC-32 of \emph{filename}, treated as an ordered collection of bytes (i.e. |
53 |
newline characters and file termination characters are not treated---the file is |
54 |
treated as a binary file). \emph{filename} must be specified in the form accepted by |
55 |
the Tcl internals (forward slashes only). |
56 |
\end{tclcommandinternaldescription} |
57 |
|
58 |
\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{-string binarystringval}} |
59 |
Returns the CRC-32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e. |
60 |
newline characters and string termination characters are not honored---the string is |
61 |
treated as a binary string).\footnote{For an ASCII string, the \emph{crc32} extension will |
62 |
behave as expected, and will process all characters up to but not including the zero |
63 |
terminator. However, the \emph{crc32} extension will also correctly process non-ASCII strings.} |
64 |
\end{tclcommandinternaldescription} |
65 |
|
66 |
|
67 |
|
68 |
|
69 |
|
70 |
\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{-initialstate}% |
71 |
\tclcommanddescsynopsisline{crc32}{-advancestate state filename}% |
72 |
\tclcommanddescsynopsisline{crc32}{-advancestate -string state filename}% |
73 |
\tclcommanddescsynopsisline{crc32}{-crcfromstate state}% |
74 |
} |
75 |
The four forms above are designed to allow ``running CRCs'' to be calculated; in which |
76 |
the CRC is calculated piecemeal. These forms allow the caller to retain the internal |
77 |
state vector of the CRC calculation algorithm. |
78 |
|
79 |
The first form, \emph{crc32 -initialstate}, returns an ASCII representation of the |
80 |
correct initial state vector of the CRC-32 state machine. The client is required |
81 |
to obtain this initial state before beginning a piecemeal CRC calculation. Although the |
82 |
returned string is a constant (it will always be the same), representational details |
83 |
may change in future versions of the \emph{crc32} extension, and so a caller should never |
84 |
make assumptions about what this invocation will return, as these assumptions may |
85 |
render a script incompatible with future versions of \emph{crc32}. |
86 |
|
87 |
The second and third forms, \emph{crc32 -advancestate state filename} |
88 |
and \emph{crc32 -advancestate -string state filename}, apply a file or a binary string |
89 |
to \emph{state} to produce a new \emph{state}, which is returned. This new \emph{state} |
90 |
must be retained by the caller and used in subsequent calls. |
91 |
|
92 |
The final form, \emph{crc32 -crcfromstate state}, maps from the state vector to the |
93 |
calculated CRC, and will return a 10-character ASCII string as described above. |
94 |
\end{tclcommandinternaldescription} |
95 |
|
96 |
\end{tclcommanddescription} |
97 |
|
98 |
|
99 |
\begin{tclcommandusagenotes} |
100 |
The ``piecemeal'' forms are as efficient as the file and string forms---there is no difference |
101 |
in the internal algorithms. The primary cost of the piecemeal forms is in importing and |
102 |
exporting the algorithm state vector to/from an ASCII string. |
103 |
Thus, the piecemeal forms become less efficient when |
104 |
small files or strings are processed, as there are more exports and imports |
105 |
of the state vector. When using the piecemeal forms, processing the data in |
106 |
larger chunks will give better performance. |
107 |
\end{tclcommandusagenotes} |
108 |
|
109 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
110 |
\noindent\begin{figure}[!b] |
111 |
\noindent\rule[-0.25in]{\textwidth}{1pt} |
112 |
\begin{tiny} |
113 |
\begin{verbatim} |
114 |
$HeadURL$ |
115 |
$Revision$ |
116 |
$Date$ |
117 |
$Author$ |
118 |
\end{verbatim} |
119 |
\end{tiny} |
120 |
\noindent\rule[0.25in]{\textwidth}{1pt} |
121 |
\end{figure} |
122 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
123 |
% |
124 |
%End of file C_CCH0.TEX |