Begin man pages

man/haggis.3

@@ -0,0 +1,109 @@
+\."                 _,.---._    .-._        .--.-. ,--.--------.         
+\."   _,..---._   ,-.' , -  `. /==/ \  .-._/==/  //==/,  -   , -\
+\." /==/,   -  \ /==/_,  ,  - \|==|, \/ /, |==\ -\\==\.-.  - ,-./        
+\." |==|   _   _\==|   .=.     |==|-  \|  | \==\- \`--`\==\- \
+\." |==|  .=.   |==|_ : ;=:  - |==| ,  | -|  `--`-'     \==\_ \
+\." |==|,|   | -|==| , '='     |==| -   _ |             |==|- |          
+\." |==|  '='   /\==\ -    ,_ /|==|  /\ , |             |==|, |          
+\." |==|-,   _`/  '.='. -   .' /==/, | |- |             /==/ -/          
+\." `-.`.____.'     `--`--''   `--`./  `--`             `--`--`          
+\."                    _ __    ,---.      .-._         .=-.-.  _,.----.   
+\."                 .-`.' ,`..--.'  \    /==/ \  .-._ /==/_ /.' .' -   \
+\."                /==/, -   \==\-/\ \   |==|, \/ /, /==|, |/==/  ,  ,-'  
+\."               |==| _ .=. /==/-|_\ |  |==|-  \|  ||==|  ||==|-   |  .  
+\."               |==| , '=',\==\,   - \ |==| ,  | -||==|- ||==|_   `-' \
+\."               |==|-  '..'/==/ -   ,| |==| -   _ ||==| ,||==|   _  , | 
+\."               |==|,  |  /==/-  /\ - \|==|  /\ , ||==|- |\==\.       / 
+\."               /==/ - |  \==\ _.\=\.-'/==/, | |- |/==/. / `-.`.___.-'  
+\."               `--`---'   `--`        `--`./  `--``--`-`
+\."
+\."	@(#)Copyright (c) 2023, Nathan D. Fisher.
+\."
+\."      This is free software.  It comes with NO WARRANTY.
+\."      Permission to use, modify and distribute this source code
+\."      is granted subject to the following conditions.
+\."      1/ that the above copyright notice and this notice
+\."      are preserved in all copies and that due credit be given
+\."      to the author.
+\."      2/ that any changes to this code are clearly commented
+\."      as such so that the author does not get blamed for bugs
+\."      other than his own.
+\."
+.Dd Aug 28, 2023
+.Dt HAGGIS_NODE 3
+.Os
+.Sh NAME
+.Nm haggis_create_node ,
+.Nm haggis_extract_node ,
+.Nm haggis_load_node ,
+.Nm haggis_store_node ,
+.Nm haggis_node_deinit
+.Nd haggis node manipulation
+.Sh LIBRARY
+.Lb libhaggis
+.Sh SYNOPSIS
+.In haggis.h
+.Ft haggis_node *
+.Fn haggis_create_node "char * path" "haggis_algorithm a" "haggis_linkmap * map"
+.Ft int
+.Fn haggis_extract_node "FILE * stream" "haggis_node * node"
+.Ft int
+.Fn haggis_load_node "FILE * stream" "haggis_node * node"
+.Ft int
+.Fn haggis_store_node "FILE * stream" "haggis_node * node"
+.Ft void
+.Fn haggis_node_deinit "haggis_node * node"
+.Sh DESCRIPTION
+The
+.Fn haggis_create_node
+function creates a haggis archive node from the file residing at
+.Fa path .
+.Pp
+The argument
+.Fa a
+specifies a hashing algorithm to be used to calculate the file's checksum.
+The
+.Fa map
+argument points to a
+.Vt haggis_linkmap
+structure as defined by
+.In haggis.h
+and which is used to keep track of hard links, so as not to use more space than
+necessary to store a complete archive.
+.Pp
+The
+.Fn haggis_extract_node
+function extracts the haggis archive node
+.Fa node
+and writes it's contents into
+.Fa stream .
+.Pp
+The
+.Fn haggis_load_node
+function loads a haggis node from
+.Fa stream
+and stores it in
+.Fa node .
+.Pp
+The
+.Fn haggis_store_node
+function takes the data stored as
+.Fa node
+and stores it in
+.Fa stream .
+.Pp
+The values accepted as a hashing algorithm by
+.Fn haggis_create_node
+are defined in the enum
+.Vt haggis_algorithm
+.Bl -tag -width indent
+.It Dv md5
+The Md5 hash algorithm is a quick hash function supported almost everywhere
+.It Dv sha1
+The Sha1 hash algorithm is almost as fast as md5 but with less chance of hash collision
+.It Dv sha256
+The Sha256 hash algorithm is considered crytographically secure, and provides the most
+surety of the integrity of your data.
+.It Dv skip
+No hash is to be used.
+.Pp