Merge lp:~millihenrik/hashit/man-pages into lp:hashit

[Henrik Holst]

* provided man pages for the hashit project

[David Gómez (dabisu)]

review: Approve

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2010-03-12 13:19:03 +0000
+++ CMakeLists.txt	2017-06-06 00:05:29 +0000
@@ -12,10 +12,14 @@
 	MESSAGE (FATAL_ERROR "pkg-config not found...")
 ENDIF (NOT PKG_CONFIG_FOUND)
 
+set(INSTALL_PKGCONFIG_DIR "${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX}/pkgconfig"
+	CACHE PATH "Installation directory for pkgconfig (.pc) files")
+set(INSTALL_MAN_DIR "${CMAKE_INSTALL_PREFIX}/share/man"
+	CACHE PATH "Manpage directory")
+
 ADD_DEFINITIONS (-DDATADIR=\\\"${CMAKE_INSTALL_PREFIX}/share\\\")
 
 ADD_LIBRARY (hashit SHARED src/hashit.c src/hfunctions.c)
-ADD_DEPENDENCIES (hashit src/hashit.c src/hfunctions.c src/hashit.h src/hfunctions.h)
 
 FILE(WRITE libhashit.pc "prefix=${CMAKE_INSTALL_PREFIX}\n")	
 FILE(APPEND libhashit.pc "libdir=${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX}\n")	
@@ -28,7 +32,18 @@
 
 INSTALL (TARGETS hashit LIBRARY DESTINATION lib${LIB_SUFFIX})	
 INSTALL (FILES src/hashit.h DESTINATION include)
-INSTALL (FILES libhashit.pc DESTINATION lib${LIB_SUFFIX}/pkg-config)
+INSTALL (FILES libhashit.pc DESTINATION ${INSTALL_PKGCONFIG_DIR})
+INSTALL (FILES man/hashit_create.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_delete.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_destroy.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_getkeys.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_getvalues.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_insert.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_lookup.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_replace.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_size.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/hashit_tablesize.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
+INSTALL (FILES man/libhashit.3 DESTINATION ${INSTALL_MAN_DIR}/man3)
 
 SET_TARGET_PROPERTIES (hashit PROPERTIES VERSION 1.0 SOVERSION 1)	
 SET (LIBRARY_OUTPUT_PATH src)

=== modified file 'INSTALL'
--- INSTALL	2008-12-18 18:56:03 +0000
+++ INSTALL	2017-06-06 00:05:29 +0000
@@ -13,11 +13,17 @@
 
 	$ cmake -DCMAKE_INSTALL_PREFIX=/usr .
 
-	Use CMAKE_BUILD_TYPE=Debug or CMAKE_BUILD_TYPE=Release if you
+	Use -DCMAKE_BUILD_TYPE=Debug or -DCMAKE_BUILD_TYPE=Release if you
 	wish to select the build type. Default is Release.
 
 	By default hashit is installed /usr/local.
 
+	Use -DINSTALL_PKGCONFIG_DIR=<path> to install the pkgconfig file to
+	'<path>/libhashit.pc' instead of the default.
+
+	Use -DINSTALL_MAN_DIR=<path> to install the man pages to <path>/man3/
+	instead of the default.
+
 	hashit includes a pkg-config file, therefore you only need to use the
 	pkg-config utility in the usual way to link your binary to hashit.
 

=== added directory 'man'
=== added file 'man/hashit_create.3'
--- man/hashit_create.3	1970-01-01 00:00:00 +0000
+++ man/hashit_create.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,67 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_create
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B hash_t hashit_create(uint32_t \fIsizehint\fB, size_t \fIkeysize\fB, uint32_t(*) \fIhfunc()\fB, int(*) \fIcfunc()\fB, unsigned int \fIflags\fB);
+
+.SH DESCRIPTION
+The \fBhashit_create\fR function creates a hash table which is returned as a hash_t type.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B sizehint
+It's used to give an aproximated desired value for the hash table, 
+the function calculates the real size of the table using this 
+parameter as a hint to the final value.
+.TP
+.B keysize
+This is the size for the data type used as a key in the hash table. 
+Keys are void *, so hashit needs to know how long they are. If key size 
+is 0, is assumed that keys are strings.
+.TP
+.B hfunc
+hfunc is a pointer to the hash function for the hash table. Typically 
+you want to put here the value NULL to use the default hash function. 
+Avaliable hash functions are BOB_HASH(Default) and ONEAT_HASH. You can 
+add your own hash function if you know what are you doing ;).
+.TP
+.B cfunc
+cfunc is the comparation function for the keys data. Semantics are the 
+same that in strcmp function. The function should return 0 if both keys 
+are equal, and a value different from zero if they are not.
+.TP
+.B flags
+flags can have the following values:
+.RS
+.TP
+.B CHAIN_H
+Hash table uses chaining for handling collisions.
+.TP
+.B OADDRESS_H
+Hash table uses open address hashing for handling collisions.
+.TP
+.B OVERFLOW_H
+Hash table uses an overflow area for handling collisions. 
+.TP
+If you're not sure about what collision handling your hash table should have, then use CHAIN_H.
+.RE
+.RE
+
+.SH RETURN VALUE
+Return value is a reference to the table just created or NULL when the table creation has failed.
+
+.SH ERRORS
+.B EINVAL\fR The \fIcfunc\fR provided was NULL, or \fIflags\fR was invalid.
+.PP
+.B ENOMEM\fR Could not allocated memory for the internal table.
+
+.SH SEE ALSO
+hashit_insert(3), hashit_delete(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_getvalues(3), hashit_size(3), 
+hashit_tablesize(3), hashit_destroy(3)
+

=== added file 'man/hashit_delete.3'
--- man/hashit_delete.3	1970-01-01 00:00:00 +0000
+++ man/hashit_delete.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,37 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_delete
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B int hashit_delete(hash_t \fIhtable\fB, void *\fIkey\fB);
+
+.SH DESCRIPTION
+The \fBhashit_delete\fR function deletes a key/data pair that is inside the hash table,
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.TP
+.B key
+Pointer to the key value for the element that should be deleted from
+the hash table. The application has the duty to free the data
+associated to this key.
+.RE
+
+.SH RETURN VALUE
+Return value is 0 if hashit_delete succeeded and -1 if delete fails.
+
+.SH ERRORS
+.B EFAULT\fR The \fIkey\fR could not be found in the hash table.
+
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_getvalues(3), hashit_size(3), 
+hashit_tablesize(3), hashit_destroy(3)
+

=== added file 'man/hashit_destroy.3'
--- man/hashit_destroy.3	1970-01-01 00:00:00 +0000
+++ man/hashit_destroy.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,32 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_destroy
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B int hashit_destroy(hash_t \fIhtable\fB);
+
+.SH DESCRIPTION
+The \fBhashit_destroy\fR function destroys the hash table and free previously allocated memory. This function
+should be called when all the work with the hash table is finished and it
+won't be needed again.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.RE
+
+.SH RETURN VALUE
+Always returns 0.
+
+.SH ERRORS
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_delete(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_getvalues(3), hashit_size(3), 
+hashit_tablesize(3)
+

=== added file 'man/hashit_getkeys.3'
--- man/hashit_getkeys.3	1970-01-01 00:00:00 +0000
+++ man/hashit_getkeys.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,36 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_getkeys
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B void **hashit_getkeys(hash_t \fIhtable\fB);
+
+.SH DESCRIPTION
+The \fBhashit_getkeys\fR function walks through the hash table and returns all the
+key values inside it. This way there is no need to keep track of
+all the keys we've inserted in our table.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.RE
+
+.SH RETURN VALUE
+Return value is a null terminated array containing all the keys in
+the hash table, or NULL if a error has ocurred. The returned array
+must be freed by the caller.
+
+.SH ERRORS
+.B ENOMEM\fR Not enough memory to allocate a new element.
+
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_delete(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getvalues(3), hashit_size(3), 
+hashit_tablesize(3), hashit_destroy(3)
+

=== added file 'man/hashit_getvalues.3'
--- man/hashit_getvalues.3	1970-01-01 00:00:00 +0000
+++ man/hashit_getvalues.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,35 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_getvalues
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B void **hashit_getvalues(hash_t \fIhtable\fB);
+
+.SH DESCRIPTION
+The \fBhashit_getvalues\fR function walks through the hash table and returns all the
+data values inside it.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.RE
+
+.SH RETURN VALUE
+Return value is a null terminated array containing all the data pointers in
+the hash table, or NULL if a error has ocurred. The returned array
+must be freed by the caller.
+
+.SH ERRORS
+.B ENOMEM\fR Not enough memory to allocate a new element.
+
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_delete(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_size(3), 
+hashit_tablesize(3), hashit_destroy(3)
+

=== added file 'man/hashit_insert.3'
--- man/hashit_insert.3	1970-01-01 00:00:00 +0000
+++ man/hashit_insert.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,44 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_insert
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B int hashit_insert(hash_t \fIhtable\fB, void *\fIkey\fB, void *\fIdata\fB);
+
+.SH DESCRIPTION
+The \fBhashit_insert\fR function inserts a key/data pair in the hash table.
+.TP
+All the keys inserted in the table must have the size given at creation time, and all must have the same data type, if not, behavior is undefined.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.TP
+.B key
+Pointer to the key value. It must have been previously allocated
+by the application that is using the library.
+.TP
+.B value
+Pointer to the data value. It must have been previously allocated by
+the application that is using the library.
+.RE
+
+.SH RETURN VALUE
+Return value is 0 if insert succeeded and -1 if insert fails.
+
+.SH ERRORS
+.B EINVAL\fR The \fIkey\fR is already inserted in the hash table.
+.PP
+.B ENOMEM\fR Not enough memory to allocate a new element.
+
+.SH SEE ALSO
+hashit_create(3), hashit_delete(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_getvalues(3), hashit_size(3), 
+hashit_tablesize(3), hashit_destroy(3)
+

=== added file 'man/hashit_lookup.3'
--- man/hashit_lookup.3	1970-01-01 00:00:00 +0000
+++ man/hashit_lookup.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,36 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_lookup
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B int hashit_lookup(hash_t \fIhtable\fB, void *\fIkey\fB);
+
+.SH DESCRIPTION
+The \fBhashit_lookup\fR function searches an element in the hash table, using the key passed as parameter and returns the data associated to that key.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.TP
+.B key
+Pointer to a key value for the searched element
+.RE
+
+.SH RETURN VALUE
+Return value is a pointer to element data for the searched key and NULL 
+if the search operation fails.
+
+.SH ERRORS
+.B EFAULT\fR The \fIkey\fR could not be found in the hash table.
+
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_delete(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_getvalues(3), hashit_size(3), 
+hashit_tablesize(3), hashit_destroy(3)
+

=== added file 'man/hashit_replace.3'
--- man/hashit_replace.3	1970-01-01 00:00:00 +0000
+++ man/hashit_replace.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,39 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_replace
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B int hashit_replace(hash_t \fIhtable\fB, void *\fIkey\fB void *\fInewvalue\fB);
+
+.SH DESCRIPTION
+The \fBhashit_replace\fR function replaces the data for the element associated to the key 'key' with
+the data pointer by 'newvalue'.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.TP
+.B key
+Pointer to a key value whose assocciated value will be changed.
+.TP
+.B newvalue
+Pointer to new data to be assigned to this key, if exists.
+.RE
+
+.SH RETURN VALUE
+Return value is 0 if the replace succeeded or -1 if replace failed.
+
+.SH ERRORS
+.B EFAULT\fR The \fIkey\fR could not be found in the hash table.
+
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_delete(3), hashit_lookup(3), 
+hashit_getkeys(3), hashit_getvalues(3), hashit_size(3), 
+hashit_tablesize(3), hashit_destroy(3)
+

=== added file 'man/hashit_size.3'
--- man/hashit_size.3	1970-01-01 00:00:00 +0000
+++ man/hashit_size.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,31 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_size
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B size_t hashit_size(hash_t \fIhtable\fB);
+
+.SH DESCRIPTION
+The \fBhashit_size\fR function returns the number of elements in the hash table.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.RE
+
+.SH RETURN VALUE
+The number of elements in the hash table.
+
+.SH ERRORS
+
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_delete(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_getvalues(3), 
+hashit_tablesize(3), hashit_destroy(3)
+

=== added file 'man/hashit_tablesize.3'
--- man/hashit_tablesize.3	1970-01-01 00:00:00 +0000
+++ man/hashit_tablesize.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,34 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+hashit_tablesize
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B size_t hashit_tablesize(hash_t \fIhtable\fB);
+
+.SH DESCRIPTION
+The \fBhashit_tablesize\fR function returns the hash table size. This has different meanings depending on the
+hash collision method used. For example, for chaining hash, it returns
+the number of buckets in the hash table, for open address its equal to
+the hash table size (maximum number of elements), for overflow hash it's
+the size of the main table without the overflow area.
+.TP
+.SS Parameters:
+.RS
+.TP
+.B htable
+Pointer to the hash table, this must be the value returned by the
+\fBhashit_create(3)\fR function.
+.RE
+
+.SH RETURN VALUE
+Returns the hash table size.
+
+.SH ERRORS
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_delete(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_getvalues(3), hashit_size(3), 
+hashit_destroy(3)
+

=== added file 'man/libhashit.3'
--- man/libhashit.3	1970-01-01 00:00:00 +0000
+++ man/libhashit.3	2017-06-06 00:05:29 +0000
@@ -0,0 +1,45 @@
+.TH LIBHASHIT 3 "2017-06-05"
+
+.SH NAME
+libhashit \- generic hash library with diverse collision methods
+
+.SH SYNOPSIS
+.B #include <hashit.h>
+.PP
+.B hash_t hashit_create(uint32_t \fIsizehint\fB, size_t \fIkeysize\fB, uint32_t(*) \fIhfunc()\fB, int(*) \fIcfunc()\fB, unsigned int \fIflags\fB);
+.PP
+.B int hashit_insert(hash_t \fIhtable\fB, void *\fIkey\fB, void *\fIdata\fB)
+.PP
+.B int hashit_delete(hasht_t \fIhtable\fB, void *\fIkey\fB)
+.PP
+.B void *hashit_lookup(hash_t \fIhtable\fB, void *\fIkey\fB)
+.PP
+.B int hashit_replace(hash_t \fIhtable\fB, void *\fIkey\fB, void *\fInewvalue\fB)
+.PP
+.B void **hashit_getkeys(hash_t \fIhtable\fB)
+.PP
+.B void **hashit_getvalues(hash_t \fIhtable\fB)
+.PP
+.B size_t hashit_size(hash_t \fIhtable\fB)
+.PP
+.B size_t hashit_tablesize(hash_t \fIhtable\fB)
+.PP
+.B int hashit_destroy(hash_t \fIhtable\fB)
+
+.SH DESCRIPTION
+hashit is a generic hash library implemented in C which supports multiple collision handling methods. 
+.PP
+Nowadays not much work is going into it, but it's maintained :), just in case some bug comes out of nowhere.
+.PP
+Credit is due to Bob Jenkins, author of the default hash function used in hashit and which is available here along with a lot of material related to hashing.
+.PP
+
+.SH AUTHOR
+.TP
+David Gómez <[e-mail]>
+
+.SH SEE ALSO
+hashit_create(3), hashit_insert(3), hashit_delete(3), hashit_lookup(3), 
+hashit_replace(3), hashit_getkeys(3), hashit_getvalues(3), hashit_size(3), 
+hashit_tablesize(3), hashit_destroy(3)
+