From c8be5ec837713599db8efd53192303cac7c5c2af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dag-Erling=20Sm=C3=B8rgrav?= Date: Sat, 17 Sep 2016 17:30:13 +0200 Subject: [PATCH] Document all the hash and checksum functions. --- lib/hash/Makefile.am | 3 ++ lib/hash/cryb_adler32.3 | 78 +++++++++++++++++++++++++++++++++++ lib/hash/cryb_fletcher.3 | 5 ++- lib/hash/cryb_hash.3 | 82 ++++++++++++++++++++---------------- lib/hash/cryb_pearson.3 | 89 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 220 insertions(+), 37 deletions(-) create mode 100644 lib/hash/cryb_adler32.3 create mode 100644 lib/hash/cryb_pearson.3 diff --git a/lib/hash/Makefile.am b/lib/hash/Makefile.am index e2779bc..62d90e9 100644 --- a/lib/hash/Makefile.am +++ b/lib/hash/Makefile.am @@ -13,5 +13,8 @@ libcryb_hash_la_SOURCES = \ cryb_hash.c dist_man3_MANS = \ + cryb_adler32.3 \ cryb_fletcher.3 \ + cryb_pearson.3 \ + \ cryb_hash.3 diff --git a/lib/hash/cryb_adler32.3 b/lib/hash/cryb_adler32.3 new file mode 100644 index 0000000..5ea65df --- /dev/null +++ b/lib/hash/cryb_adler32.3 @@ -0,0 +1,78 @@ +.\"- +.\" Copyright (c) 2015-2016 Universitetet i Oslo +.\" Copyright (c) 2016 Dag-Erling Smørgrav +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 8, 2016 +.Dt CRYB_ADLER32 3 +.Os +.Sh NAME +.Nm cryb_adler32_hash +.Nd hash functions +.Sh LIBRARY +.Lb libcryb-hash +.Sh SYNOPSIS +.In stddef.h +.In stdint.h +.In cryb/hash.h +.Ft uint32_t +.Fn cryb_adler32_hash "const void *data" "size_t len" +.Sh DESCRIPTION +The +.Fn cryb_adler32_hash +function returns a 32-bit checksum of the +.Va len +first bytes of the object pointed to by +.Va data +using the Adler-32 algorithm described in RFC 1950. +.Pp +Unlike the Pearson hash implemented by +.Fn cryb_pearson_hash +or cryptographic message digests such as the SHA family, these +checksums are suitable for error detection. +.Sh IMPLEMENTATION NOTES +The +.In cryb/hash.h +header provides macros which allows these functions to be referred to +without their +.Dq Li cryb_ +prefix. +.Sh SEE ALSO +.Xr cryb_hash 3 +.Sh REFERENCES +.Rs +.%A "Deutsch, P." +.%A "Gailly, J.-L." +.%D "May 1996" +.%R "ZLIB Compressed Data Format Specification version 3.3" +.%O "RFC 1950" +.Re +.Sh AUTHORS +The +.Fn cryb_adler32_hash +function and this manual page were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . diff --git a/lib/hash/cryb_fletcher.3 b/lib/hash/cryb_fletcher.3 index c2375fc..cfc3562 100644 --- a/lib/hash/cryb_fletcher.3 +++ b/lib/hash/cryb_fletcher.3 @@ -37,6 +37,7 @@ .Sh LIBRARY .Lb libcryb-hash .Sh SYNOPSIS +.In stddef.h .In stdint.h .In cryb/hash.h .Ft uint16_t @@ -57,7 +58,7 @@ first bytes of the object pointed to by .Va data . .Pp Unlike the Pearson hash implemented by -.Fn cryb_hash +.Fn cryb_pearson_hash or cryptographic message digests such as the SHA family, these checksums are suitable for error detection. .Sh IMPLEMENTATION NOTES @@ -72,7 +73,7 @@ caller should take care to either pad the input or truncate the argument before calling the checksum function. .Sh SEE ALSO .Xr cryb_hash 3 -.\".Sh REFERENCES +.Sh STANDARDS .Rs .%A "Fletcher, John G." .%D "January 1982" diff --git a/lib/hash/cryb_hash.3 b/lib/hash/cryb_hash.3 index 50a1700..063c4c1 100644 --- a/lib/hash/cryb_hash.3 +++ b/lib/hash/cryb_hash.3 @@ -1,5 +1,5 @@ .\"- -.\" Copyright (c) 2015-2016 Universitetet i Oslo +.\" Copyright (c) 2016 Dag-Erling Smørgrav .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -26,55 +26,67 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd January 8, 2016 +.Dd September 17, 2016 .Dt CRYB_HASH 3 .Os .Sh NAME -.Nm cryb_hash , -.Nm cryb_strhash -.Nd hash functions +.Nm cryb_hash_version , +.Nm cryb_adler32_hash , +.Nm cryb_fletcher16_hash , +.Nm cryb_fletcher32_hash , +.Nm cryb_fletcher64_hash , +.Nm cryb_pearson_hash , +.Nm cryb_pearson_hash_str +.Nd hash and checksum functions .Sh LIBRARY .Lb libcryb-hash .Sh SYNOPSIS +.In stddef.h .In stdint.h .In cryb/hash.h +.Ft const char * +.Fn cryb_hash_version "void" +.Ft uint32_t +.Fn cryb_adler32_hash "const void *data" "size_t len" +.Ft uint16_t +.Fn fletcher16_hash "const void *data" "size_t len" +.Ft uint32_t +.Fn fletcher32_hash "const void *data" "size_t len" +.Ft uint64_t +.Fn fletcher64_hash "const void *data" "size_t len" .Ft uint8_t -.Fn cryb_hash "const void *data" "size_t len" +.Fn cryb_pearson_hash "const void *data" "size_t len" .Ft uint8_t -.Fn cryb_strhash "const char *str" +.Fn cryb_pearson_hash_str "const char *str" .Sh DESCRIPTION The -.Fn cryb_hash -function returns an 8-bit hash of the -.Va len -first bytes of the object pointed to by -.Va data . +.Fn cryb_hash_version +function returns a pointer to a string containing the specific version +of the +.Lb libcryb-hash +library. .Pp -The -.Fn cryb_strhash -function returns an 8-bit hash of the NUL-terminated string pointed to -by -.Va str , -not including the terminating NUL. -It is equivalent to calling -.Li cryb_hash(str, strlen(str)) . +For descriptions of the other functions in this library, see their +respective manual pages. .Sh SEE ALSO -.Xr cryb_sha1 3 -.Sh REFERENCES -.Rs -.%A "Pearson, Peter K." -.%D "June 1990" -.%T "Fast Hashing of Variable-Length Text Strings" -.%J "Communications of the ACM" -.%V "33" -.%N "6" -.%P "677" -.%O "doi:10.1145/78973.78978" -.Re +.Xr cryb_adler32 3 , +.Xr cryb_fletcher 3 , +.Xr cryb_pearson 3 .Sh AUTHORS The -.Fn cryb_hash +.Fn cryb_hash_version , +.Fn cryb_adler32_hash , +.Fn cryb_fletcher16 , +.Fn cryb_fletcher32 and -.Fn cryb_strhash -functions and this manual page were written for the University of Oslo by +.Fn cryb_fletcher64 +functions and corresponding manual pages were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . +.Pp +The +.Fn cryb_pearson_hash +and +.Fn cryb_pearson_hash_str +functions and corresponding manual pages were written for the +University of Oslo by .An Dag-Erling Sm\(/orgrav Aq Mt d.e.smorgrav@usit.uio.no . diff --git a/lib/hash/cryb_pearson.3 b/lib/hash/cryb_pearson.3 new file mode 100644 index 0000000..6360448 --- /dev/null +++ b/lib/hash/cryb_pearson.3 @@ -0,0 +1,89 @@ +.\"- +.\" Copyright (c) 2015-2016 Universitetet i Oslo +.\" Copyright (c) 2016 Dag-Erling Smørgrav +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 17, 2016 +.Dt CRYB_PEARSON_HASH 3 +.Os +.Sh NAME +.Nm cryb_pearson_hash , +.Nm cryb_pearson_hash_str +.Nd hash functions +.Sh LIBRARY +.Lb libcryb-hash +.Sh SYNOPSIS +.In stddef.h +.In stdint.h +.In cryb/hash.h +.Ft uint8_t +.Fn cryb_pearson_hash "const void *data" "size_t len" +.Ft uint8_t +.Fn cryb_pearson_hash_str "const char *str" +.Sh DESCRIPTION +The +.Fn cryb_pearson_hash +function returns an 8-bit hash of the +.Va len +first bytes of the object pointed to by +.Va data . +.Pp +The +.Fn cryb_pearson_hash_str +function returns an 8-bit hash of the NUL-terminated string pointed to +by +.Va str , +not including the terminating NUL. +It is equivalent to calling +.Li cryb_pearson_hash(str, strlen(str)) . +.Sh IMPLEMENTATION NOTES +The +.In cryb/hash.h +header provides macros which allows these functions to be referred to +without their +.Dq Li cryb_ +prefix. +.Sh SEE ALSO +.Xr cryb_hash 3 +.Sh STANDARDS +.Rs +.%A "Pearson, Peter K." +.%D "June 1990" +.%T "Fast Hashing of Variable-Length Text Strings" +.%J "Communications of the ACM" +.%V "33" +.%N "6" +.%P "677" +.%O "doi:10.1145/78973.78978" +.Re +.Sh AUTHORS +The +.Fn cryb_pearson_hash +and +.Fn cryb_pearson_hash_str +functions and this manual page were written for the University of Oslo by +.An Dag-Erling Sm\(/orgrav Aq Mt d.e.smorgrav@usit.uio.no .