From 7c14e95516ab18246239f74687d028e36ef8e7b2 Mon Sep 17 00:00:00 2001 Message-Id: <7c14e95516ab18246239f74687d028e36ef8e7b2.1714074986.git.mdw@distorted.org.uk> From: Mark Wooding Date: Sun, 9 Nov 2003 13:13:50 +0000 Subject: [PATCH] Document crc-mktab a little. Organization: Straylight/Edgeware From: mdw --- man/Makefile.am | 19 +++++- man/crc-mktab.1 | 167 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+), 3 deletions(-) create mode 100644 man/crc-mktab.1 diff --git a/man/Makefile.am b/man/Makefile.am index 141f4d8..b477c2b 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1,6 +1,6 @@ ## -*-makefile-*- ## -## $Id: Makefile.am,v 1.2 2003/05/16 00:24:05 mdw Exp $ +## $Id: Makefile.am,v 1.3 2003/11/09 13:13:49 mdw Exp $ ## ## Makefile for mLib's manual pages ## @@ -29,6 +29,9 @@ ##----- Revision history ---------------------------------------------------- ## ## $Log: Makefile.am,v $ +## Revision 1.3 2003/11/09 13:13:49 mdw +## Document crc-mktab a little. +## ## Revision 1.2 2003/05/16 00:24:05 mdw ## maninst isn't shipped here. ## @@ -49,6 +52,9 @@ manext = @manext@ ## --- Manual pages --- MANPAGES = \ + crc-mktab.1 + +MANPAGESEXT = \ alloc.3 arena.3 assoc.3 atom.3 base64.3 bits.3 bres.3 conn.3 \ crc32.3 darray.3 dspool.3 dstr.3 env.3 exc.3 fdflags.3 fwatch.3 \ hash.3 ident.3 lbuf.3 lock.3 mLib.3 mdwopt.3 pkbuf.3 pool.3 \ @@ -60,14 +66,21 @@ install-man: $(MANPAGES) $(mkinstalldirs) $(DESTDIR)$(mandir) $(top_srcdir)/maninst \ -d $(DESTDIR)$(mandir) -s $(srcdir) \ - -i "$(INSTALL)" -e $(manext) \ + -i "$(INSTALL)" \ install $(MANPAGES) + $(top_srcdir)/maninst \ + -d $(DESTDIR)$(mandir) -s $(srcdir) \ + -i "$(INSTALL)" -e $(manext) \ + install $(MANPAGESEXT) uninstall-man: $(MANPAGS) @$(NORMAL_UNINSTALL) $(top_srcdir)/maninst \ - -d $(DESTDIR)$(mandir) -s $(srcdir) -e $(manext) \ + -d $(DESTDIR)$(mandir) -s $(srcdir) \ uninstall $(MANPAGES) + $(top_srcdir)/maninst \ + -d $(DESTDIR)$(mandir) -s $(srcdir) -e $(manext) \ + uninstall $(MANPAGESEXT) install-data-local: install-man uninstall-local: uninstall-man diff --git a/man/crc-mktab.1 b/man/crc-mktab.1 new file mode 100644 index 0000000..0d285c2 --- /dev/null +++ b/man/crc-mktab.1 @@ -0,0 +1,167 @@ +.\" nroff +.ie t \{\ +. ds ss \s8\u +. ds se \d\s0 +.\} +.el \{\ +. ds ss ^ +. ds se +.\} +.TH crc-mktab 1 "9 November 2003" "Straylight/Edgeware" "mLib utilities library" +.SH NAME +crc-mktab \- construct CRC tables for efficient computation +.SH SYNOPSIS +.B crc-mktab +.RB [ \-cr ] +.RB [ \-s +.IR symbol ] +.RB [ \-t +.IR type ] +.RB [ \-i +.IR header ] +.br + \c +.RB [ \-g +.IR macro ] +.RB [ \-b +.IR bits ] +.RB [ \-B +.IR chunk ] +.RB [ \-p +.IR poly ] +.br + \c +.RB [ \-o +.IR filename ] +.SH DESCRIPTION +The +.B crc-mktab +program constructs tables for efficient computation of CRC (cyclic +redundancy check) values. It will produce the table as either an array +defined in a C source file or as an initializer macro defined in a C +header file. +.SS "Options" +The program accepts no non-option arguments. At least one of +.B \-b +or +.B \-p +must be given. The options are as follows. +.TP +.B "\-h, \-\-help" +Print a help message to standard output and exit successfully. +.TP +.B "\-v, \-\-version" +Print the program's version number to standard output and exit +successfully. +.TP +.B "\-u, \-\-usage" +Print a one-line usage summary to standard output and exit successfully. +.TP +.B "\-c, \-\-c-source" +Produce a C source file which exports a symbol naming the array, instead +of a C header file. +.TP +.BI "\s, \-\-symbol=" symbol +Name the table +.IR symbol . +This is the name of the macro defined by a header file, or the array +exported by a C source. The default macro name is +.BR CRC_TAB ; +the default array name is +.BR crctab . +.TP +.BI "\-t, \-\-type=" type +Specify the element type of the array defined by a C source output. The +default is +.B "unsigned short" +if the polynomial has degree 16 or less, or +.B "unsigned long" +otherwise. This option does nothing without the +.B \-c +option. +.TP +.BI "\-i, \-\-include=" header +Request that generated C source include the named +.I header +file. Inserts a +line of the form +.PP +.nf +.BI " #include """ header """" +.fi +.IP +at the top of the generated C source. The default is not to include a +header file. This option does nothing without the +.B \-c +option. +.TP +.BI "\-g, \-\-guard=" macro +Use the named +.I macro +as a guard against multiple inclusion of the generated header file. +Inserts a pair of lines of the form +.PP +.nf +.BI " #ifndef " macro +.BI " #define " macro +.fi +.IP +at the top of the generated header, and a line +.PP +.nf +.BI " #endif" +.fi +.IP +at the end. The default guard macro name is built from the output file +name specified with +.B \-o +by uppercasing all alphabetic characters in the name and replacing +nonalphanumeric characters by underscores +.RB ` _ '. +This option does nothing with the +.B \-c +option. +.TP +.BI "\-b, \-\-bits=" bits +Specifies the degree of the CRC polynomial or, equivalently, the length +of the generated CRC. This must be an integer between 1 and 32 +inclusive. If it is not specified, the polynomial given by +.B \-p +is examined and an educated guess made. (Currently we choose the +smallest multiple of 8 which is large enough.) +.TP +.BI "\-B, \-\-bit-chunk=" chunk +Chunk size in which bits are taken from the input. The number of +entries in the table is precisely +.RI 2\*(ss chunk \*(se. +The default chunk size is 8. +.TP +.BI "\-p, \-\-polynomial=" poly +Specifies the CRC polynomial as an integer. The polynomial has a +nonzero coefficient in its +.IR x \*(ss i \*(se +term if and only if bit +.I i +of +.I poly +is nonzero. Note that if you want to specify the polynomial in +hexadecimal, you must prefix it with +.BR 0x . +Default polynomials of degree 16 and 32 are known. +.TP +.B "\-r, \-\-reverse" +Construct the table to compensate for unusual bit-ordering. Without +this option, you'd have to reverse the order of all input chunks and the +output CRC. +.SS "The table and how to use it" +Describing in detail the contents of the table would take too long. For +an example of use, see the header file +.BR crc32.h . +.SH "SEE ALSO" +.BR crc32 (3). +.PP +.I A painless guide to CRC error detection algorithms +by Ross N. Williams. +.SH "AUTHOR" +Mark Wooding, + -- [mdw]