chiark / gitweb /
Document crc-mktab a little.
authormdw <mdw>
Sun, 9 Nov 2003 13:13:50 +0000 (13:13 +0000)
committermdw <mdw>
Sun, 9 Nov 2003 13:13:50 +0000 (13:13 +0000)
man/Makefile.am
man/crc-mktab.1 [new file with mode: 0644]

index 141f4d8..b477c2b 100644 (file)
@@ -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 (file)
index 0000000..0d285c2
--- /dev/null
@@ -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@nsict.org>
+