--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pws_init.3.xml	Wed Mar 25 17:10:23 2015 +0100
@@ -0,0 +1,159 @@
+<?xml version="1.0"?>
+<!--
+
+Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
+  <info>
+    <author>
+      <personname>
+        <firstname>Guido</firstname>
+        <surname>Berhoerster</surname>
+      </personname>
+      <email>guido+libpws@berhoerster.name</email>
+      <personblurb/>
+    </author>
+    <date>21 March, 2015</date>
+  </info>
+  <refmeta>
+    <refentrytitle>libpws</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo class="source"/>
+    <refmiscinfo class="version"/>
+    <refmiscinfo class="manual">Library Functions</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>pws_init</refname>
+    <refname>pws_finalize</refname>
+    <refname>pws_set_alloc_functions</refname>
+    <refname>pws_generate_uuid</refname>
+    <refpurpose>initalize and deinitialize libpws</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>cc</command>
+      <arg choice="opt" rep="repeat">
+        <option>flag</option>
+      </arg>
+      <arg choice="plain" rep="repeat">
+        <option>file</option>
+      </arg>
+      <arg choice="plain">
+        <option>-lpws</option>
+      </arg>
+      <arg choice="plain">
+        <option>-lnettle</option>
+      </arg>
+      <arg choice="opt" rep="repeat">
+        <option>library</option>
+      </arg>
+    </cmdsynopsis>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+#include &lt;pws.h&gt;
+</funcsynopsisinfo>
+      <funcprototype>
+        <funcdef>int <function>pws_init</function></funcdef>
+        <void/>
+      </funcprototype>
+      <funcprototype>
+        <funcdef>void <function>pws_finalize</function></funcdef>
+        <void/>
+      </funcprototype>
+      <funcprototype>
+        <funcdef>void <function>pws_set_alloc_functions</function></funcdef>
+        <paramdef>void
+        *<funcparams>*<replaceable>alloc_function</replaceable></funcparams><funcparams>size_t</funcparams></paramdef>
+        <paramdef>void
+        *<funcparams>*<replaceable>realloc_function</replaceable></funcparams><funcparams>void *, size_t</funcparams></paramdef>
+        <paramdef>void <funcparams>*<replaceable>free_function</replaceable></funcparams><funcparams>void
+        *, size_t</funcparams></paramdef>
+        <paramdef>void
+        *<funcparams>*<replaceable>secure_alloc_function</replaceable></funcparams><funcparams>size_t</funcparams></paramdef>
+        <paramdef>void
+        *<funcparams>*<replaceable>secure_realloc_function</replaceable></funcparams><funcparams>void *, size_t</funcparams></paramdef>
+        <paramdef>void <funcparams>*<replaceable>secure_free_function</replaceable></funcparams><funcparams>void
+        *, size_t</funcparams></paramdef>
+      </funcprototype>
+      <funcprototype>
+        <funcdef>int <function>pws_generate_uuid</function></funcdef>
+        <paramdef>unsigned char [static PWS3_UUID_SIZE]</paramdef>
+      </funcprototype>
+    </funcsynopsis>
+    <synopsis>
+<constant>LIBPWS_VERSION_MAJOR</constant>
+
+<constant>LIBPWS_VERSION_MINOR</constant>
+
+<constant>LIBPWS_VERSION_MICRO</constant>
+    </synopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>Description</title>
+    <para>The <function>pws_init()</function> function initializes
+    <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    and must be called before any other function from this library.</para>
+    <para>The <function>pws_finalize()</function> function deinitializes
+    <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    after which no other function from this library may be called.</para>
+    <para>The <function>pws_set_alloc_functions()</function> function specifies
+    the functions which are used by
+    <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    to allocate, reallocate or free memory allowing for the use of custom
+    allocators. <function>pws_secure_alloc</function>,
+    <function>pws_secure_realloc</function>, and
+    <function>pws_secure_free</function> are used to allocate, reallocate, and
+    free memory containing potentially sensitive information such as passwords,
+    this e.g. allows for wrapping the acutal allocation using operating system
+    specific facilities to prevent memory from being paged to the swap area or
+    to overwrite memory before deallocating it. Any argument set to
+    <constant>NULL</constant> will result in the default function being used,
+    these are <function>malloc</function>, <function>realloc</function>, and a
+    wrapper around <function>free</function>. This function must be called
+    after <function>pws_init</function> and before calling any other function
+    from this library. It is not reentrant.</para>
+    <para>The <function>pws_uuid_create()</function> function generates a new
+    random UUID following RFC4122 and places it in the array passed to
+    it.</para>
+    <para>The macros <constant>LIBPWS_VERSION_MAJOR</constant>,
+    <constant>LIBPWS_VERSION_MINOR</constant>, and
+    <constant>LIBPWS_VERSION_MICRO</constant> can be used to check the major,
+    minor, and micro version of the library.</para>
+  </refsect1>
+  <refsect1>
+    <title>Return Values</title>
+    <para>The <function>pws_init()</function> function returns
+    <returnvalue>0</returnvalue> if the library was initialized successfully and
+    <returnvalue>-1</returnvalue> on failure.</para>
+    <para>The <function>pws_generate_uuid()</function> returns
+    <returnvalue>0</returnvalue> if a new random UUID has been generated and
+    <returnvalue>-1</returnvalue> on failure.</para>
+  </refsect1>
+  <refsect1>
+    <title>See Also</title>
+    <para><citerefentry><refentrytitle>libpws</refentrytitle>
+    <manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>pws3_file_create</refentrytitle>
+    <manvolnum>3</manvolnum></citerefentry>, RFC4122</para>
+  </refsect1>
+</refentry>