commit a6c4b818c5a36c3416a7c3783f289643724ac973
parent dbe54b4a293eeefdbab40e9d169be3afc32be1bf
Author: Mattias Andrée <maandree@kth.se>
Date: Mon, 9 May 2016 14:55:46 +0200
manual: initialisation and errors
Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat:
4 files changed, 175 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
@@ -75,7 +75,8 @@ DOC =\
TEXSRC =\
doc/libzahl.tex\
doc/what-is-libzahl.tex\
- doc/libzahls-design.tex
+ doc/libzahls-design.tex\
+ doc/get-started.tex
HDR_PUBLIC = zahl.h $(HDR_SEMIPUBLIC)
HDR = $(HDR_PUBLIC) $(HDR_PRIVATE)
diff --git a/doc/get-started.tex b/doc/get-started.tex
@@ -0,0 +1,171 @@
+\chapter{Get started}
+\label{chap:Get started}
+
+In this chapter, you will learn the basics of libzahl.
+You should read the sections in order.
+
+\vspace{1cm}
+\minitoc
+
+
+\newpage
+\section{Initialisation}
+\label{sec:Initialisation}
+
+Before using libzahl, it most be initialised. When
+initialising, you must select a location whither libzahl
+long jumps on error.
+
+\begin{alltt}
+ #include <zahl.h>
+
+ int
+ main(void)
+ \{
+ jmp_buf jmpenv;
+ if (setjmp(jmpenv))
+ return 1; \textcolor{c}{/* \textrm{Exit on error} */}
+ zsetup(jmpenv);
+ \textcolor{c}{/* \textrm{\ldots} */}
+ return 0;
+ \}
+\end{alltt}
+
+{\tt zsetup} also initialises temporary variables used
+by libzahl's functions, and constants used by libzahl's
+functions. Furthermore, it initialises the memory pool
+and a stack which libzahl to keep track of temporary
+allocations that need to be pooled for use if a function
+fails.
+
+It is recommended to also uninitialise libzahl when you
+are done using it, for example before the program exits.
+
+\begin{alltt}
+ \textcolor{c}{int
+ main(void)
+ \{
+ jmp_buf jmpenv;
+ if (setjmp(jmpenv))
+ return 1; /* \textrm{Exit on error} */
+ zsetup(jmpenv);
+ /* \textrm{\ldots} */}
+ zunsetup();
+ \textcolor{c}{return 0;
+ \}}
+\end{alltt}
+
+{\tt zunsetup} all memory that has be reclaim to the
+memory pool, and all memory allocated by {\tt zsetup}.
+Note that this does not free integers that are still
+in use. It is possible to simply call {\tt zunsetup}
+directly followed by {\tt zsetup} to free all pooled
+memory.
+
+
+\newpage
+\section{Exceptional conditions}
+\label{sec:Exceptional conditions}
+
+Exceptional conditions, casually called `errors',
+are treated in libzahl using long jumps.
+
+\begin{alltt}
+ int
+ main(int argc, char *argv[])
+ \{
+ jmp_buf jmpenv;
+ if (setjmp(jmpenv))
+ return 1; \textcolor{c}{/* \textrm{Exit on error} */}
+ zsetup(jmpenv);
+ return 0;
+ \}
+\end{alltt}
+
+Just exiting on error is not a particularly good
+idea. Instead, you may want to print an error message.
+This is done with {\tt zperror}.
+
+\begin{alltt}
+ if (setjmp(jmpenv)) \{
+ zperror(\textcolor{c}{*argv});
+ \textcolor{c}{return 1;}
+ \}
+\end{alltt}
+
+\noindent
+{\tt zperror} works just like {\tt perror}. It
+outputs an error description to standard error.
+A line break is printed at the end of the message.
+If the argument passed to {\tt zperror} is neither
+{\tt NULL} nor an empty string, it is printed in
+front of the description, with a colon and a
+space separating the passed string and the description.
+For example, {\tt zperror("my-app")} may output
+
+\begin{verbatim}
+ my-app: Cannot allocate memory
+\end{verbatim}
+
+libzahl also provides {\tt zerror}. Calling this
+function will provide you with an error code and
+a textual description.
+
+\begin{alltt}
+ \textcolor{c}{if (setjmp(jmpenv)) \{}
+ const char *description;
+ zerror(&description);
+ fprintf(stderr, "\%s: \%s\verb|\|n", *argv, description);
+ \textcolor{c}{return 1;}
+ \textcolor{c}{\}}
+\end{alltt}
+
+\noindent
+This code behaves like the example above that
+calls {\tt zperror}. If you are interested in the
+error code, you instead look at the return value.
+
+\begin{alltt}
+ \textcolor{c}{if (setjmp(jmpenv)) \{}
+ enum zerror e = zerror(NULL);
+ switch (e) \{
+ case ZERROR_ERRNO_SET:
+ perror("");
+ \textcolor{c}{return 1;}
+ case ZERROR_0_POW_0:
+ fprintf(stderr, "Indeterminate form: 0^0\verb|\|n");
+ \textcolor{c}{return 1;}
+ case ZERROR_0_DIV_0:
+ fprintf(stderr, "Indeterminate form: 0/0\verb|\|n");
+ \textcolor{c}{return 1;}
+ case ZERROR_DIV_0:
+ fprintf(stderr, "Do not divide by zero, dummy\verb|\|n");
+ \textcolor{c}{return 1;}
+ case ZERROR_NEGATIVE:
+ fprintf(stderr, "Undefined (negative input)\verb|\|n");
+ \textcolor{c}{return 1;}
+ default:
+ zperror("");
+ \textcolor{c}{return 1;}
+ \}
+ \textcolor{c}{\}}
+\end{alltt}
+
+To change the point whither libzahl's functions
+jump, call {\tt setjmp} and {\tt zsetup} again.
+
+\begin{alltt}
+ jmp_buf jmpenv;
+
+ if (setjmp(jmpenv)) \{
+ \textcolor{c}{/* \textrm{\ldots} */}
+ \}
+ zsetup(jmpenv);
+
+ \textcolor{c}{/* \textrm{\ldots} */}
+
+ if (setjmp(jmpenv)) \{
+ \textcolor{c}{/* \textrm{\ldots} */}
+ \}
+ zsetup(jmpenv);
+\end{alltt}
diff --git a/doc/libzahl.tex b/doc/libzahl.tex
@@ -78,6 +78,7 @@ all copies or substantial portions of the Document.
\input doc/what-is-libzahl.tex
\input doc/libzahls-design.tex
+\input doc/get-started.tex
\appendix
diff --git a/doc/libzahls-design.tex b/doc/libzahls-design.tex
@@ -212,7 +212,7 @@ or
Like any self respecting bignum library, libzahl
supports using the same big integer reference as
for output as input, as long as the all output
-parameters are unique to each other. For example
+parameters are mutually unique. For example
\begin{alltt}
a += b;
