projects/libpws

changeset 1:e1309515d111

Add README file and manpages
author Guido Berhoerster <guido+libpws@berhoerster.name>
date Wed Mar 25 17:10:23 2015 +0100 (2015-03-25)
parents d541e748cfd8
children 97097b4b6bfb
files Makefile README docbook-update-source-data.xsl libpws.3.xml pws3_file_create.3.xml pws_init.3.xml
line diff
     1.1 --- a/Makefile	Tue Feb 10 11:29:54 2015 +0100
     1.2 +++ b/Makefile	Wed Mar 25 17:10:23 2015 +0100
     1.3 @@ -45,6 +45,45 @@
     1.4  PAX :=		pax
     1.5  GZIP :=		gzip
     1.6  SED :=		sed
     1.7 +XSLTPROC :=	xsltproc
     1.8 +DOCBOOK5_MANPAGES_STYLESHEET =	http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
     1.9 +DOCBOOK5_MANPAGES_FLAGS =	--stringparam funcsynopsis.style 'ansi' \
    1.10 +				--stringparam man.authors.section.enabled 0 \
    1.11 +				--stringparam man.copyright.section.enabled 0
    1.12 +DOCBOOK5_XHTML_STYLESHEET =	http://docbook.sourceforge.net/release/xsl-ns/current/xhtml/docbook.xsl
    1.13 +DOCBOOK5_XHTML_FLAGS =		--stringparam funcsynopsis.style 'ansi' \
    1.14 +				--stringparam generate.consistent.ids 1 \
    1.15 +				--stringparam refentry.generate.name 1 \
    1.16 +				--stringparam refentry.generate.title 0 \
    1.17 +				--stringparam refentry.xref.manvolnum 1 \
    1.18 +				--stringparam generate.id.attributes 1 \
    1.19 +				--stringparam make.valid.html 1 \
    1.20 +				--stringparam make.clean.html 1 \
    1.21 +				--stringparam html.cleanup 1 \
    1.22 +				--stringparam html.longdesc 0 \
    1.23 +				--stringparam ulink.target '' \
    1.24 +				--stringparam docbook.css.source '' \
    1.25 +				--stringparam css.decoration 0 \
    1.26 +				--stringparam default.table.width '100%'
    1.27 +
    1.28 +define generate-manpage-rule =
    1.29 +$(addsuffix .%,$(basename $1)): $(addsuffix .%.xml,$(basename $(firstword $1))) docbook-update-source-data.xsl
    1.30 +	$$(XSLTPROC) \
    1.31 +	    --xinclude \
    1.32 +	    --stringparam package $$(PACKAGE) \
    1.33 +	    --stringparam version $$(VERSION) \
    1.34 +	    docbook-update-source-data.xsl $$< | \
    1.35 +	    $$(XSLTPROC) \
    1.36 +	    --xinclude \
    1.37 +	    --output $(firstword $1) \
    1.38 +	    $$(DOCBOOK5_MANPAGES_FLAGS) \
    1.39 +	    $$(DOCBOOK5_MANPAGES_STYLESHEET) \
    1.40 +	    -
    1.41 +	$$(SED) 's,^\.HP \\w.*$$$$,.HP 4n,' $$@ >$$(@).tmp && mv $$(@).tmp $$@
    1.42 +	for alias in $(wordlist 2,$(words $1),$1); do \
    1.43 +	    ln -sf $(notdir $(firstword $1)) $$$$alias; \
    1.44 +	done
    1.45 +endef
    1.46  
    1.47  DESTDIR ?=
    1.48  prefix ?=	/usr/local
    1.49 @@ -104,11 +143,78 @@
    1.50  
    1.51  OBJS =			$(LIBPWS_OBJS)
    1.52  
    1.53 +LIBPWS_MANPAGES =	libpws.3
    1.54 +
    1.55 +PWS_INIT_MANPAGES =	pws_init.3 \
    1.56 +			pws_finalize.3 \
    1.57 +			pws_set_alloc_functions.3 \
    1.58 +			pws_generate_uuid.3
    1.59 +
    1.60 +PWS3_FILE_CREATE_MANPAGES = pws3_file_create.3 \
    1.61 +			pws3_file_destroy.3 \
    1.62 +			pws3_file_get_error_code.3 \
    1.63 +			pws3_file_get_error_message.3 \
    1.64 +			pws3_file_read_mem.3 \
    1.65 +			pws3_file_read_stream.3 \
    1.66 +			pws3_file_write_mem.3 \
    1.67 +			pws3_file_write_stream.3 \
    1.68 +			pws3_file_set_header_field.3 \
    1.69 +			pws3_file_get_header_field.3 \
    1.70 +			pws3_file_remove_header_field.3 \
    1.71 +			pws3_file_insert_empty_group.3 \
    1.72 +			pws3_file_get_empty_group.3 \
    1.73 +			pws3_file_remove_empty_group.3 \
    1.74 +			pws3_file_first_empty_group.3 \
    1.75 +			pws3_file_last_empty_group.3 \
    1.76 +			pws3_file_next_empty_group.3 \
    1.77 +			pws3_file_prev_empty_group.3 \
    1.78 +			pws3_file_insert_record.3 \
    1.79 +			pws3_file_get_record.3 \
    1.80 +			pws3_file_remove_record.3 \
    1.81 +			pws3_file_first_record.3 \
    1.82 +			pws3_file_last_record.3 \
    1.83 +			pws3_file_next_record.3 \
    1.84 +			pws3_file_prev_record.3 \
    1.85 +			pws3_field_create.3 \
    1.86 +			pws3_field_destroy.3 \
    1.87 +			pws3_field_is_header.3 \
    1.88 +			pws3_field_get_type.3 \
    1.89 +			pws3_field_get_data_type.3 \
    1.90 +			pws3_field_set_uuid.3 \
    1.91 +			pws3_field_set_text.3 \
    1.92 +			pws3_field_set_time.3 \
    1.93 +			pws3_field_set_uint8.3 \
    1.94 +			pws3_field_set_uint16.3 \
    1.95 +			pws3_field_set_uint32.3 \
    1.96 +			pws3_field_set_bytes.3 \
    1.97 +			pws3_field_get_uuid.3 \
    1.98 +			pws3_field_get_text.3 \
    1.99 +			pws3_field_get_time.3 \
   1.100 +			pws3_field_get_uint8.3 \
   1.101 +			pws3_field_get_uint16.3 \
   1.102 +			pws3_field_get_uint32.3 \
   1.103 +			pws3_field_get_bytes.3 \
   1.104 +			pws3_record_create.3 \
   1.105 +			pws3_record_destroy.3 \
   1.106 +			pws3_record_set_field.3 \
   1.107 +			pws3_record_get_field.3 \
   1.108 +			pws3_record_remove_field.3
   1.109 +
   1.110 +MANPAGES =		$(LIBPWS_MANPAGES) \
   1.111 +			$(PWS_INIT_MANPAGES) \
   1.112 +			$(PWS3_FILE_CREATE_MANPAGES)
   1.113 +
   1.114 +XHTML_DOCUMENTATION =	$(addsuffix .xhtml,$(firstword $(LIBPWS_MANPAGES)) \
   1.115 +			$(firstword $(PWS_INIT_MANPAGES)) \
   1.116 +			$(firstword $(PWS3_FILE_CREATE_MANPAGES)))
   1.117 +
   1.118  .DEFAULT_TARGET = all
   1.119  
   1.120  .PHONY: all clean clobber dist install
   1.121  
   1.122 -all: $(LIBPWS_LIB)
   1.123 +all: $(LIBPWS_LIB) $(MANPAGES)
   1.124 +
   1.125 +doc: $(MANPAGES) $(XHTML_DOCUMENTATION)
   1.126  
   1.127  XCPPFLAGS = -Iinclude
   1.128  ifeq ($(HAVE_ARC4RANDOM),1)
   1.129 @@ -146,6 +252,12 @@
   1.130  
   1.131  $(LIBPWS_LIB): $(LIBPWS_LIB_MEMBERS)
   1.132  
   1.133 +$(eval $(call generate-manpage-rule,$(LIBPWS_MANPAGES)))
   1.134 +
   1.135 +$(eval $(call generate-manpage-rule,$(PWS_INIT_MANPAGES)))
   1.136 +
   1.137 +$(eval $(call generate-manpage-rule,$(PWS3_FILE_CREATE_MANPAGES)))
   1.138 +
   1.139  %.o: %.c
   1.140  	$(MAKEDEPEND.c) $< | $(SED) -f deps.sed >$*.d
   1.141  	$(COMPILE.c) -o $@ $<
   1.142 @@ -154,16 +266,39 @@
   1.143  	$(AR) $(ARFLAGS) $@ $<
   1.144  	$(RANLIB) $@
   1.145  
   1.146 +%.xhtml: %.xml docbook-update-source-data.xsl
   1.147 +	$(XSLTPROC) \
   1.148 +	    --xinclude \
   1.149 +	    --stringparam package $(PACKAGE) \
   1.150 +	    --stringparam version $(VERSION) \
   1.151 +	    docbook-update-source-data.xsl $< | \
   1.152 +	    $(XSLTPROC) \
   1.153 +	    --xinclude \
   1.154 +	    --output $@ \
   1.155 +	    $(DOCBOOK5_XHTML_FLAGS) \
   1.156 +	    $(DOCBOOK5_XHTML_STYLESHEET) \
   1.157 +	    -
   1.158 +
   1.159  install:
   1.160  	for header in include/*.h; do \
   1.161  	    $(INSTALL.data) $${header} \
   1.162 -	        "$(DESTDIR)$(includedir)/$(PACKAGE)/$${header##*/}"; \
   1.163 +	        "$(DESTDIR)$(includedir)/$${header##*/}"; \
   1.164  	done
   1.165  	$(INSTALL.lib) $(LIBPWS_LIB) \
   1.166  	    "$(DESTDIR)$(libdir)/$(notdir $(LIBPWS_LIB))"
   1.167 +	for manpage in $(MANPAGES); do \
   1.168 +	    if [ -L $${manpage} ]; then \
   1.169 +	        $(INSTALL.link) $${manpage} \
   1.170 +	            "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
   1.171 +	    else \
   1.172 +	        $(INSTALL.data) $${manpage} \
   1.173 +	            "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
   1.174 +	    fi \
   1.175 +	done
   1.176  
   1.177  clean:
   1.178 -	rm -f $(LIBPWS_LIB) $(LIBPWS_OBJS)
   1.179 +	rm -f $(LIBPWS_LIB) $(LIBPWS_OBJS) $(MANPAGES) \
   1.180 +	    $(XHTML_DOCUMENTATION)
   1.181  
   1.182  clobber: clean
   1.183  	rm -f $(patsubst %.o,%.d,$(OBJS))
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/README	Wed Mar 25 17:10:23 2015 +0100
     2.3 @@ -0,0 +1,103 @@
     2.4 +libpws
     2.5 +=======
     2.6 +
     2.7 +Description
     2.8 +-----------
     2.9 +
    2.10 +libpws provides an API for creating, reading, manipulating and writing
    2.11 +Password Safe files, it currently supports version 3 of the Password Safe file
    2.12 +format.
    2.13 +
    2.14 +Build Instructions
    2.15 +------------------
    2.16 +
    2.17 +libpws requires a POSIX:2004 compatible operating system, it has been tested
    2.18 +to work on Linux distributions, FreeBSD, Solaris and Illumos-derived
    2.19 +distributions.  The following tools and shared libraries are required to build
    2.20 +libpws:
    2.21 +
    2.22 +- GNU make >= 3.81
    2.23 +- GNU or BSD install
    2.24 +- Nettle
    2.25 +
    2.26 +Rebuilding the man pages additionally requires the xsltproc tool from libxml2.
    2.27 +
    2.28 +Before building libpws check the commented macros in the Makefile for any
    2.29 +macros you may need to override depending on the used toolchain and operating
    2.30 +system.
    2.31 +
    2.32 +By default, all files will be installed under the "/usr/local" directory, a
    2.33 +different installation path prefix can be set via the `prefix` macro.  In
    2.34 +addition, a second path prefix can be specified via the `DESTDIR` macro which
    2.35 +will be prepended to any path, incuding the `prefix` macro path prefix.  In
    2.36 +contrast to `prefix`, the path specified via the `DESTDIR` macro will only be
    2.37 +prepended to paths during installation and not be used for constructing
    2.38 +internal paths.
    2.39 +
    2.40 +The following instructions assume that `make` is GNU make, on some platforms
    2.41 +it may be installed under a different name or a non-default path.  In order to
    2.42 +start the build process run `make all`.  After a successful build, run `make
    2.43 +install` to install the program, any associated data files and the
    2.44 +documentation.
    2.45 +
    2.46 +Previously built binaries, object files, generated data files and
    2.47 +documentation can be removed by running `make clean`, any additional,
    2.48 +generated files which are not removed by the `clean` target can be removed by
    2.49 +running `make clobber`.
    2.50 +
    2.51 +Contact
    2.52 +-------
    2.53 +
    2.54 +Please send any feedback, translations or bug reports via email to
    2.55 +<guido+libpws@berhoerster.name>.
    2.56 +
    2.57 +Bug Reports
    2.58 +-----------
    2.59 +
    2.60 +When sending bug reports, please always mention the exact version of libpws
    2.61 +with which the issue occurs as well as the version of the operating system you
    2.62 +are using and make sure that you provide sufficient information to reproduce
    2.63 +the issue and include any input, output, any error messages.
    2.64 +
    2.65 +In case of build issues, please also specify the implementations and versions
    2.66 +of the tools and shared libraries used to build the program, in particular the
    2.67 +compiler.
    2.68 +
    2.69 +In case of crashes, please generate a stack trace with a suitable debugger
    2.70 +such as gdb, lldb, dbx, or debug after a crash has occurred either by
    2.71 +examining the resulting core file or by running the program from the debugger
    2.72 +and attach it to the bug report.  In order to generate a meaningful stack
    2.73 +trace the program as well as any dynamically linked libraries need to be built
    2.74 +with debugging information, see the documentation of the used compiler for the
    2.75 +required compiler flags.  If any of the dynamically linked shared libraries do
    2.76 +not contain debugging information, please either install debugging information
    2.77 +for these libraries using mechanisms provided by your operating system or
    2.78 +rebuild the libraries accordingly.  Please refer to the documentation of the
    2.79 +debugger for detailed instructions on generating backtraces.
    2.80 +
    2.81 +License
    2.82 +-------
    2.83 +
    2.84 +Except otherwise noted, all files are Copyright (C) 2015 Guido Berhoerster and
    2.85 +distributed under the following license terms:
    2.86 +
    2.87 +Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
    2.88 +
    2.89 +Permission is hereby granted, free of charge, to any person obtaining
    2.90 +a copy of this software and associated documentation files (the
    2.91 +"Software"), to deal in the Software without restriction, including
    2.92 +without limitation the rights to use, copy, modify, merge, publish,
    2.93 +distribute, sublicense, and/or sell copies of the Software, and to
    2.94 +permit persons to whom the Software is furnished to do so, subject to
    2.95 +the following conditions:
    2.96 +
    2.97 +The above copyright notice and this permission notice shall be included
    2.98 +in all copies or substantial portions of the Software.
    2.99 +
   2.100 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   2.101 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   2.102 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   2.103 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   2.104 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   2.105 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
   2.106 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/docbook-update-source-data.xsl	Wed Mar 25 17:10:23 2015 +0100
     3.3 @@ -0,0 +1,29 @@
     3.4 +<?xml version="1.0"?>
     3.5 +<xsl:stylesheet
     3.6 +  version="1.0"
     3.7 +  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     3.8 +  xmlns:db="http://docbook.org/ns/docbook"
     3.9 +  xmlns="http://docbook.org/ns/docbook"
    3.10 +  exclude-result-prefixes="xsl db">
    3.11 +
    3.12 +  <xsl:param name="package" select="''" />
    3.13 +  <xsl:param name="version" select="''" />
    3.14 +
    3.15 +  <xsl:template match="db:refmeta/db:refmiscinfo[@class = 'source' or
    3.16 +    @class = 'version']"/>
    3.17 +
    3.18 +  <xsl:template match="db:refmeta">
    3.19 +    <xsl:copy>
    3.20 +      <xsl:apply-templates/>
    3.21 +      <refmiscinfo class="source"><xsl:value-of select="$package"/></refmiscinfo>
    3.22 +      <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
    3.23 +    </xsl:copy>
    3.24 +  </xsl:template>
    3.25 +
    3.26 +  <xsl:template match="@*|node()">
    3.27 +    <xsl:copy>
    3.28 +      <xsl:apply-templates select="@*|node()"/>
    3.29 +    </xsl:copy>
    3.30 +  </xsl:template>
    3.31 +
    3.32 +</xsl:stylesheet>
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/libpws.3.xml	Wed Mar 25 17:10:23 2015 +0100
     4.3 @@ -0,0 +1,213 @@
     4.4 +<?xml version="1.0"?>
     4.5 +<!--
     4.6 +
     4.7 +Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
     4.8 +
     4.9 +Permission is hereby granted, free of charge, to any person obtaining
    4.10 +a copy of this software and associated documentation files (the
    4.11 +"Software"), to deal in the Software without restriction, including
    4.12 +without limitation the rights to use, copy, modify, merge, publish,
    4.13 +distribute, sublicense, and/or sell copies of the Software, and to
    4.14 +permit persons to whom the Software is furnished to do so, subject to
    4.15 +the following conditions:
    4.16 +
    4.17 +The above copyright notice and this permission notice shall be included
    4.18 +in all copies or substantial portions of the Software.
    4.19 +
    4.20 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    4.21 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    4.22 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    4.23 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    4.24 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    4.25 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    4.26 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    4.27 +
    4.28 +-->
    4.29 +<refentry xmlns="http://docbook.org/ns/docbook"
    4.30 +  xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
    4.31 +  <info>
    4.32 +    <author>
    4.33 +      <personname>
    4.34 +        <firstname>Guido</firstname>
    4.35 +        <surname>Berhoerster</surname>
    4.36 +      </personname>
    4.37 +      <email>guido+libpws@berhoerster.name</email>
    4.38 +      <personblurb/>
    4.39 +    </author>
    4.40 +    <date>21 March, 2015</date>
    4.41 +  </info>
    4.42 +  <refmeta>
    4.43 +    <refentrytitle>libpws</refentrytitle>
    4.44 +    <manvolnum>3</manvolnum>
    4.45 +    <refmiscinfo class="source"/>
    4.46 +    <refmiscinfo class="version"/>
    4.47 +    <refmiscinfo class="manual">Library Functions</refmiscinfo>
    4.48 +  </refmeta>
    4.49 +  <refnamediv>
    4.50 +    <refname>libpws</refname>
    4.51 +    <refpurpose>library for creating and manipulating Password Safe files</refpurpose>
    4.52 +  </refnamediv>
    4.53 +  <refsynopsisdiv>
    4.54 +    <cmdsynopsis>
    4.55 +      <command>cc</command>
    4.56 +      <arg choice="opt" rep="repeat">
    4.57 +        <option>flag</option>
    4.58 +      </arg>
    4.59 +      <arg choice="plain" rep="repeat">
    4.60 +        <option>file</option>
    4.61 +      </arg>
    4.62 +      <arg choice="plain">
    4.63 +        <option>-lpws</option>
    4.64 +      </arg>
    4.65 +      <arg choice="plain">
    4.66 +        <option>-lnettle</option>
    4.67 +      </arg>
    4.68 +      <arg choice="opt" rep="repeat">
    4.69 +        <option>library</option>
    4.70 +      </arg>
    4.71 +    </cmdsynopsis>
    4.72 +    <funcsynopsis>
    4.73 +      <funcsynopsisinfo>
    4.74 +#include &lt;pws.h&gt;
    4.75 +</funcsynopsisinfo>
    4.76 +    </funcsynopsis>
    4.77 +  </refsynopsisdiv>
    4.78 +  <refsect1>
    4.79 +    <title>Description</title>
    4.80 +    <para>libpws provides an API for creating, reading, manipulating and
    4.81 +    writing Password Safe files. The Password Safe file format is intended
    4.82 +    for the platform-independent secure storage of passwords and associated
    4.83 +    metadata and offers protection from unauthorized access to the file by
    4.84 +    encrypting it using a key derived from a master password. Its design
    4.85 +    ensures both confidentiality and integrity of its contents.</para>
    4.86 +    <para>libpws currently supports version 3 of the Password Safe file
    4.87 +    format.</para>
    4.88 +    <para>The <literal>&lt;<filename
    4.89 +    class="header">pws.h</filename>&gt;</literal> header provides type and
    4.90 +    function declarations for all library services.</para>
    4.91 +    <para>With the exception of <function>pws_set_alloc_functions</function>
    4.92 +    all functions are reentrant. Functions operating on a Password Safe file
    4.93 +    structure, a header field structure, a record field structure, and a record
    4.94 +    structure provide no locking. A multithreaded application must either
    4.95 +    provide its own synchronization mechanisms or restrict operations on any of
    4.96 +    the above structures to a single thread.</para>
    4.97 +  </refsect1>
    4.98 +  <refsect1>
    4.99 +    <title>Interfaces</title>
   4.100 +    <para>The static library <filename class="libraryfile">libpws.a</filename>
   4.101 +    provides following the public interfaces:
   4.102 +    <simplelist type="vert" columns="2">
   4.103 +      <member><function>pws_init</function></member>
   4.104 +      <member><function>pws_finalize</function></member>
   4.105 +      <member><function>pws_set_alloc_functions</function></member>
   4.106 +      <member><function>pws_generate_uuid</function></member>
   4.107 +      <member><function>pws3_field_create</function></member>
   4.108 +      <member><function>pws3_field_destroy</function></member>
   4.109 +      <member><function>pws3_field_is_header</function></member>
   4.110 +      <member><function>pws3_field_get_type</function></member>
   4.111 +      <member><function>pws3_field_get_data_type</function></member>
   4.112 +      <member><function>pws3_field_set_uuid</function></member>
   4.113 +      <member><function>pws3_field_set_text</function></member>
   4.114 +      <member><function>pws3_field_set_time</function></member>
   4.115 +      <member><function>pws3_field_set_uint8</function></member>
   4.116 +      <member><function>pws3_field_set_uint16</function></member>
   4.117 +      <member><function>pws3_field_set_uint32</function></member>
   4.118 +      <member><function>pws3_field_set_bytes</function></member>
   4.119 +      <member><function>pws3_field_get_uuid</function></member>
   4.120 +      <member><function>pws3_field_get_text</function></member>
   4.121 +      <member><function>pws3_field_get_time</function></member>
   4.122 +      <member><function>pws3_field_get_uint8</function></member>
   4.123 +      <member><function>pws3_field_get_uint16</function></member>
   4.124 +      <member><function>pws3_field_get_uint32</function></member>
   4.125 +      <member><function>pws3_field_get_bytes</function></member>
   4.126 +      <member><function>pws3_file_create</function></member>
   4.127 +      <member><function>pws3_file_destroy</function></member>
   4.128 +      <member><function>pws3_file_get_error_code</function></member>
   4.129 +      <member><function>pws3_file_get_error_message</function></member>
   4.130 +      <member><function>pws3_file_read_mem</function></member>
   4.131 +      <member><function>pws3_file_read_stream</function></member>
   4.132 +      <member><function>pws3_file_write_mem</function></member>
   4.133 +      <member><function>pws3_file_write_stream</function></member>
   4.134 +      <member><function>pws3_file_set_header_field</function></member>
   4.135 +      <member><function>pws3_file_get_header_field</function></member>
   4.136 +      <member><function>pws3_file_remove_header_field</function></member>
   4.137 +      <member><function>pws3_file_insert_empty_group</function></member>
   4.138 +      <member><function>pws3_file_get_empty_group</function></member>
   4.139 +      <member><function>pws3_file_remove_empty_group</function></member>
   4.140 +      <member><function>pws3_file_first_empty_group</function></member>
   4.141 +      <member><function>pws3_file_last_empty_group</function></member>
   4.142 +      <member><function>pws3_file_next_empty_group</function></member>
   4.143 +      <member><function>pws3_file_prev_empty_group</function></member>
   4.144 +      <member><function>pws3_file_insert_record</function></member>
   4.145 +      <member><function>pws3_file_get_record</function></member>
   4.146 +      <member><function>pws3_file_remove_record</function></member>
   4.147 +      <member><function>pws3_file_first_record</function></member>
   4.148 +      <member><function>pws3_file_last_record</function></member>
   4.149 +      <member><function>pws3_file_next_record</function></member>
   4.150 +      <member><function>pws3_file_prev_record</function></member>
   4.151 +    </simplelist></para>
   4.152 +    <para>It defines the following C preprocessor macros which are documented
   4.153 +        in the
   4.154 +        <citerefentry><refentrytitle>pws_init</refentrytitle><manvolnum>3</manvolnum></citerefentry>
   4.155 +        manual page:
   4.156 +    <simplelist type="vert">
   4.157 +      <member><function>LIBPWS_VERSION_MAJOR</function></member>
   4.158 +      <member><function>LIBPWS_VERSION_MINOR</function></member>
   4.159 +      <member><function>LIBPWS_VERSION_MICRO</function></member>
   4.160 +      <member><function>PWS3_VERSION</function></member>
   4.161 +      <member><function>PWS3_MAX_FIELD_SIZE</function></member>
   4.162 +      <member><function>PWS3_MAX_PASSWORD_LEN</function></member>
   4.163 +      <member><function>PWS3_UUID_SIZE</function></member>
   4.164 +    </simplelist></para>
   4.165 +  </refsect1>
   4.166 +  <refsect1>
   4.167 +    <title>Types</title>
   4.168 +    <para>libpws provides the following data structures:
   4.169 +    <variablelist>
   4.170 +      <varlistentry>
   4.171 +        <term>struct pws3_file</term>
   4.172 +        <listitem>
   4.173 +          <para>Opaque data structure representing a Password Safe version 3
   4.174 +          file.</para>
   4.175 +        </listitem>
   4.176 +      </varlistentry>
   4.177 +      <varlistentry>
   4.178 +        <term>struct pws3_record</term>
   4.179 +        <listitem>
   4.180 +          <para>Opaque data structure representing a Password Safe version 3
   4.181 +          record.</para>
   4.182 +        </listitem>
   4.183 +      </varlistentry>
   4.184 +      <varlistentry>
   4.185 +        <term>struct pws3_field</term>
   4.186 +        <listitem>
   4.187 +          <para>Opaque data structure representing a Password Safe version 3
   4.188 +            typed field belonging to the header or a record, depending on the
   4.189 +            type it may hold a UUID, string, time, 8-bit, 16-bit, or 32-bit
   4.190 +            wide unsigned integer or raw data.</para>
   4.191 +        </listitem>
   4.192 +      </varlistentry>
   4.193 +    </variablelist></para>
   4.194 +  </refsect1>
   4.195 +  <refsect1>
   4.196 +    <title>Security</title>
   4.197 +    <para>The aforementioned protection of confidentiality and integrity of
   4.198 +    the file contents only applies to the stored file. When reading a Password
   4.199 +    Safe file using libpws, the file contents are decrypted and stored in
   4.200 +    memory where they might be compromised, e.g. by a malicious application or
   4.201 +    a privileged user. Furthermore, parts of the process memory may be paged to
   4.202 +    the swap area by the operating system.</para>
   4.203 +    <para>libpws provides hooks for allocating and freeing memory used to
   4.204 +    store sensitive information which may be used to mitigate such issues
   4.205 +    using operating system specific facilities.</para>
   4.206 +    <para>libpws has not been formally audited, use at your own risk.</para>
   4.207 +  </refsect1>
   4.208 +  <refsect1>
   4.209 +    <title>See Also</title>
   4.210 +    <para><citerefentry><refentrytitle>pws_init</refentrytitle>
   4.211 +      <manvolnum>3</manvolnum></citerefentry>,
   4.212 +      <citerefentry><refentrytitle>pws3_file_create</refentrytitle>
   4.213 +      <manvolnum>3</manvolnum></citerefentry>, <link
   4.214 +      xlink:href="https://pwsafe.org/"/></para>
   4.215 +  </refsect1>
   4.216 +</refentry>
     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/pws3_file_create.3.xml	Wed Mar 25 17:10:23 2015 +0100
     5.3 @@ -0,0 +1,1400 @@
     5.4 +<?xml version="1.0"?>
     5.5 +<!--
     5.6 +
     5.7 +Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
     5.8 +
     5.9 +Permission is hereby granted, free of charge, to any person obtaining
    5.10 +a copy of this software and associated documentation files (the
    5.11 +"Software"), to deal in the Software without restriction, including
    5.12 +without limitation the rights to use, copy, modify, merge, publish,
    5.13 +distribute, sublicense, and/or sell copies of the Software, and to
    5.14 +permit persons to whom the Software is furnished to do so, subject to
    5.15 +the following conditions:
    5.16 +
    5.17 +The above copyright notice and this permission notice shall be included
    5.18 +in all copies or substantial portions of the Software.
    5.19 +
    5.20 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    5.21 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    5.22 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    5.23 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    5.24 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    5.25 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    5.26 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    5.27 +
    5.28 +-->
    5.29 +<refentry xmlns="http://docbook.org/ns/docbook"
    5.30 +  xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
    5.31 +  <info>
    5.32 +    <author>
    5.33 +      <personname>
    5.34 +        <firstname>Guido</firstname>
    5.35 +        <surname>Berhoerster</surname>
    5.36 +      </personname>
    5.37 +      <email>guido+libpws@berhoerster.name</email>
    5.38 +      <personblurb/>
    5.39 +    </author>
    5.40 +    <date>21 March, 2015</date>
    5.41 +  </info>
    5.42 +  <refmeta>
    5.43 +    <refentrytitle>libpws</refentrytitle>
    5.44 +    <manvolnum>3</manvolnum>
    5.45 +    <refmiscinfo class="source"/>
    5.46 +    <refmiscinfo class="version"/>
    5.47 +    <refmiscinfo class="manual">Library Functions</refmiscinfo>
    5.48 +  </refmeta>
    5.49 +  <refnamediv>
    5.50 +    <refname>pws3_file_create</refname>
    5.51 +    <refname>pws3_file_destroy</refname>
    5.52 +    <refname>pws3_file_get_error_code</refname>
    5.53 +    <refname>pws3_file_get_error_message</refname>
    5.54 +    <refname>pws3_file_read_mem</refname>
    5.55 +    <refname>pws3_file_read_stream</refname>
    5.56 +    <refname>pws3_file_write_mem</refname>
    5.57 +    <refname>pws3_file_write_stream</refname>
    5.58 +    <refname>pws3_file_set_header_field</refname>
    5.59 +    <refname>pws3_file_get_header_field</refname>
    5.60 +    <refname>pws3_file_remove_header_field</refname>
    5.61 +    <refname>pws3_file_insert_empty_group</refname>
    5.62 +    <refname>pws3_file_get_empty_group</refname>
    5.63 +    <refname>pws3_file_remove_empty_group</refname>
    5.64 +    <refname>pws3_file_first_empty_group</refname>
    5.65 +    <refname>pws3_file_last_empty_group</refname>
    5.66 +    <refname>pws3_file_next_empty_group</refname>
    5.67 +    <refname>pws3_file_prev_empty_group</refname>
    5.68 +    <refname>pws3_file_insert_record</refname>
    5.69 +    <refname>pws3_file_get_record</refname>
    5.70 +    <refname>pws3_file_remove_record</refname>
    5.71 +    <refname>pws3_file_first_record</refname>
    5.72 +    <refname>pws3_file_last_record</refname>
    5.73 +    <refname>pws3_file_next_record</refname>
    5.74 +    <refname>pws3_file_prev_record</refname>
    5.75 +    <refname>pws3_field_create</refname>
    5.76 +    <refname>pws3_field_destroy</refname>
    5.77 +    <refname>pws3_field_is_header</refname>
    5.78 +    <refname>pws3_field_get_type</refname>
    5.79 +    <refname>pws3_field_get_data_type</refname>
    5.80 +    <refname>pws3_field_set_uuid</refname>
    5.81 +    <refname>pws3_field_set_text</refname>
    5.82 +    <refname>pws3_field_set_time</refname>
    5.83 +    <refname>pws3_field_set_uint8</refname>
    5.84 +    <refname>pws3_field_set_uint16</refname>
    5.85 +    <refname>pws3_field_set_uint32</refname>
    5.86 +    <refname>pws3_field_set_bytes</refname>
    5.87 +    <refname>pws3_field_get_uuid</refname>
    5.88 +    <refname>pws3_field_get_text</refname>
    5.89 +    <refname>pws3_field_get_time</refname>
    5.90 +    <refname>pws3_field_get_uint8</refname>
    5.91 +    <refname>pws3_field_get_uint16</refname>
    5.92 +    <refname>pws3_field_get_uint32</refname>
    5.93 +    <refname>pws3_field_get_bytes</refname>
    5.94 +    <refname>pws3_record_create</refname>
    5.95 +    <refname>pws3_record_destroy</refname>
    5.96 +    <refname>pws3_record_set_field</refname>
    5.97 +    <refname>pws3_record_get_field</refname>
    5.98 +    <refname>pws3_record_remove_field</refname>
    5.99 +    <refpurpose>create and manipulate Password Safe File Version 3
   5.100 +    files</refpurpose>
   5.101 +  </refnamediv>
   5.102 +  <refsynopsisdiv>
   5.103 +    <cmdsynopsis>
   5.104 +      <command>cc</command>
   5.105 +      <arg choice="opt" rep="repeat">
   5.106 +        <option>flag</option>
   5.107 +      </arg>
   5.108 +      <arg choice="plain" rep="repeat">
   5.109 +        <option>file</option>
   5.110 +      </arg>
   5.111 +      <arg choice="plain">
   5.112 +        <option>-lpws</option>
   5.113 +      </arg>
   5.114 +      <arg choice="plain">
   5.115 +        <option>-lnettle</option>
   5.116 +      </arg>
   5.117 +      <arg choice="opt" rep="repeat">
   5.118 +        <option>library</option>
   5.119 +      </arg>
   5.120 +    </cmdsynopsis>
   5.121 +    <funcsynopsis>
   5.122 +      <funcsynopsisinfo>
   5.123 +#include &lt;pws.h&gt;
   5.124 +</funcsynopsisinfo>
   5.125 +      <funcprototype>
   5.126 +        <funcdef>struct pws3_file
   5.127 +        *<function>pws3_file_create</function></funcdef>
   5.128 +        <void/>
   5.129 +      </funcprototype>
   5.130 +      <funcprototype>
   5.131 +        <funcdef>void <function>pws3_file_destroy</function></funcdef>
   5.132 +        <paramdef>struct pws3_file
   5.133 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.134 +      </funcprototype>
   5.135 +      <funcprototype>
   5.136 +        <funcdef>enum pws_error_code
   5.137 +        <function>pws3_file_get_error_code</function></funcdef>
   5.138 +        <paramdef>struct pws3_file
   5.139 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.140 +      </funcprototype>
   5.141 +      <funcprototype>
   5.142 +        <funcdef>const char *
   5.143 +        <function>pws3_file_get_error_message</function></funcdef>
   5.144 +        <paramdef>struct pws3_file
   5.145 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.146 +      </funcprototype>
   5.147 +      <funcprototype>
   5.148 +        <funcdef>int <function>pws3_file_read_mem</function></funcdef>
   5.149 +        <paramdef>struct pws3_file
   5.150 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.151 +        <paramdef>const char
   5.152 +        *<parameter><replaceable>password</replaceable></parameter></paramdef>
   5.153 +        <paramdef>unsigned char
   5.154 +        *<parameter><replaceable>s</replaceable></parameter></paramdef>
   5.155 +        <paramdef>size_t
   5.156 +        <parameter><replaceable>n</replaceable></parameter></paramdef>
   5.157 +      </funcprototype>
   5.158 +      <funcprototype>
   5.159 +        <funcdef>int <function>pws3_file_read_stream</function></funcdef>
   5.160 +        <paramdef>struct pws3_file
   5.161 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.162 +        <paramdef>const char
   5.163 +        *<parameter><replaceable>password</replaceable></parameter></paramdef>
   5.164 +        <paramdef>FILE
   5.165 +        *<parameter><replaceable>fp</replaceable></parameter></paramdef>
   5.166 +      </funcprototype>
   5.167 +      <funcprototype>
   5.168 +        <funcdef>int <function>pws3_file_write_mem</function></funcdef>
   5.169 +        <paramdef>struct pws3_file
   5.170 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.171 +        <paramdef>const char
   5.172 +        *<parameter><replaceable>password</replaceable></parameter></paramdef>
   5.173 +        <paramdef>uint32_t
   5.174 +        <parameter><replaceable>n_iter</replaceable></parameter></paramdef>
   5.175 +        <paramdef>unsigned char
   5.176 +        **<parameter><replaceable>memp</replaceable></parameter></paramdef>
   5.177 +        <paramdef>size_t
   5.178 +        *<parameter><replaceable>mem_sizep</replaceable></parameter></paramdef>
   5.179 +      </funcprototype>
   5.180 +      <funcprototype>
   5.181 +        <funcdef>int <function>pws3_file_write_stream</function></funcdef>
   5.182 +        <paramdef>struct pws3_file
   5.183 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.184 +        <paramdef>const char
   5.185 +        *<parameter><replaceable>password</replaceable></parameter></paramdef>
   5.186 +        <paramdef>uint32_t
   5.187 +        <parameter><replaceable>n_iter</replaceable></parameter></paramdef>
   5.188 +      </funcprototype>
   5.189 +      <funcprototype>
   5.190 +        <funcdef>void <function>pws3_file_set_header_field</function></funcdef>
   5.191 +        <paramdef>struct pws3_file
   5.192 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.193 +        <paramdef>struct pws3_field
   5.194 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.195 +      </funcprototype>
   5.196 +      <funcprototype>
   5.197 +        <funcdef>struct pws3_field *
   5.198 +        <function>pws3_file_get_header_field</function></funcdef>
   5.199 +        <paramdef>struct pws3_file
   5.200 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.201 +        <paramdef>uint8_t
   5.202 +        <parameter><replaceable>field_type</replaceable></parameter></paramdef>
   5.203 +      </funcprototype>
   5.204 +      <funcprototype>
   5.205 +        <funcdef>struct pws3_field *
   5.206 +        <function>pws3_file_remove_header_field</function></funcdef>
   5.207 +        <paramdef>struct pws3_file
   5.208 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.209 +        <paramdef>uint8_t
   5.210 +        <parameter><replaceable>field_type</replaceable></parameter></paramdef>
   5.211 +      </funcprototype>
   5.212 +      <funcprototype>
   5.213 +        <funcdef>void
   5.214 +        <function>pws3_file_insert_empty_group</function></funcdef>
   5.215 +        <paramdef>struct pws3_file
   5.216 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.217 +        <paramdef>struct pws3_field
   5.218 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.219 +      </funcprototype>
   5.220 +      <funcprototype>
   5.221 +        <funcdef>struct pws3_field *
   5.222 +        <function>pws3_file_get_empty_group</function></funcdef>
   5.223 +        <paramdef>struct pws3_file
   5.224 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.225 +        <paramdef>const char
   5.226 +        *<parameter><replaceable>group_name</replaceable></parameter></paramdef>
   5.227 +      </funcprototype>
   5.228 +      <funcprototype>
   5.229 +        <funcdef>struct pws3_field *
   5.230 +        <function>pws3_file_remove_empty_group</function></funcdef>
   5.231 +        <paramdef>struct pws3_file
   5.232 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.233 +        <paramdef>const char
   5.234 +        *<parameter><replaceable>group_name</replaceable></parameter></paramdef>
   5.235 +      </funcprototype>
   5.236 +      <funcprototype>
   5.237 +        <funcdef>struct pws3_field *
   5.238 +        <function>pws3_file_first_empty_group</function></funcdef>
   5.239 +        <paramdef>struct pws3_file
   5.240 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.241 +      </funcprototype>
   5.242 +      <funcprototype>
   5.243 +        <funcdef>struct pws3_field *
   5.244 +        <function>pws3_file_last_empty_group</function></funcdef>
   5.245 +        <paramdef>struct pws3_file
   5.246 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.247 +      </funcprototype>
   5.248 +      <funcprototype>
   5.249 +        <funcdef>struct pws3_field *
   5.250 +        <function>pws3_file_next_empty_group</function></funcdef>
   5.251 +        <paramdef>struct pws3_file
   5.252 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.253 +        <paramdef>struct pws3_field
   5.254 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.255 +      </funcprototype>
   5.256 +      <funcprototype>
   5.257 +        <funcdef>struct pws3_field *
   5.258 +        <function>pws3_file_prev_empty_group</function></funcdef>
   5.259 +        <paramdef>struct pws3_file
   5.260 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.261 +        <paramdef>struct pws3_field
   5.262 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.263 +      </funcprototype>
   5.264 +      <funcprototype>
   5.265 +        <funcdef>void <function>pws3_file_insert_record</function></funcdef>
   5.266 +        <paramdef>struct pws3_file
   5.267 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.268 +        <paramdef>struct pws3_record
   5.269 +        *<parameter><replaceable>record</replaceable></parameter></paramdef>
   5.270 +      </funcprototype>
   5.271 +      <funcprototype>
   5.272 +        <funcdef>struct pws3_record *
   5.273 +        <function>pws3_file_get_record</function></funcdef>
   5.274 +        <paramdef>struct pws3_file
   5.275 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.276 +        <paramdef>const unsigned char
   5.277 +        <parameter><replaceable>uuid</replaceable>[static
   5.278 +        PWS3_UUID_SIZE]</parameter></paramdef>
   5.279 +      </funcprototype>
   5.280 +      <funcprototype>
   5.281 +        <funcdef>struct pws3_record *
   5.282 +        <function>pws3_file_remove_record</function></funcdef>
   5.283 +        <paramdef>struct pws3_file
   5.284 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.285 +        <paramdef>const unsigned char
   5.286 +        <parameter><replaceable>uuid</replaceable>[static
   5.287 +        PWS3_UUID_SIZE]</parameter></paramdef>
   5.288 +      </funcprototype>
   5.289 +      <funcprototype>
   5.290 +        <funcdef>struct pws3_record *
   5.291 +        <function>pws3_file_first_record</function></funcdef>
   5.292 +        <paramdef>struct pws3_file
   5.293 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.294 +      </funcprototype>
   5.295 +      <funcprototype>
   5.296 +        <funcdef>struct pws3_record *
   5.297 +        <function>pws3_file_last_record</function></funcdef>
   5.298 +        <paramdef>struct pws3_file
   5.299 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.300 +      </funcprototype>
   5.301 +      <funcprototype>
   5.302 +        <funcdef>struct pws3_record *
   5.303 +        <function>pws3_file_next_record</function></funcdef>
   5.304 +        <paramdef>struct pws3_file
   5.305 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.306 +        <paramdef>struct pws3_record
   5.307 +        *<parameter><replaceable>record</replaceable></parameter></paramdef>
   5.308 +      </funcprototype>
   5.309 +      <funcprototype>
   5.310 +        <funcdef>struct pws3_record *
   5.311 +        <function>pws3_file_prev_record</function></funcdef>
   5.312 +        <paramdef>struct pws3_file
   5.313 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   5.314 +        <paramdef>struct pws3_record
   5.315 +        *<parameter><replaceable>record</replaceable></parameter></paramdef>
   5.316 +      </funcprototype>
   5.317 +      <funcprototype>
   5.318 +        <funcdef>struct pws3_field *
   5.319 +        <function>pws3_field_create</function></funcdef>
   5.320 +        <paramdef>int
   5.321 +        <parameter><replaceable>is_header</replaceable></parameter></paramdef>
   5.322 +        <paramdef>uint8_t
   5.323 +        <parameter><replaceable>field_type</replaceable></parameter></paramdef>
   5.324 +      </funcprototype>
   5.325 +      <funcprototype>
   5.326 +        <funcdef>void <function>pws3_field_destroy</function></funcdef>
   5.327 +        <paramdef>struct pws3_field
   5.328 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.329 +      </funcprototype>
   5.330 +      <funcprototype>
   5.331 +        <funcdef>int
   5.332 +        <function>pws3_field_is_header</function></funcdef>
   5.333 +        <paramdef>struct pws3_field
   5.334 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.335 +      </funcprototype>
   5.336 +      <funcprototype>
   5.337 +        <funcdef>uint8_t *
   5.338 +        <function>pws3_field_get_type</function></funcdef>
   5.339 +        <paramdef>struct pws3_field
   5.340 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.341 +      </funcprototype>
   5.342 +      <funcprototype>
   5.343 +        <funcdef>enum pws_data_type *
   5.344 +        <function>pws3_field_get_data_type</function></funcdef>
   5.345 +        <paramdef>struct pws3_field
   5.346 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.347 +      </funcprototype>
   5.348 +      <funcprototype>
   5.349 +        <funcdef>int <function>pws3_field_set_uuid</function></funcdef>
   5.350 +        <paramdef>struct pws3_field
   5.351 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.352 +        <paramdef>const unsigned char
   5.353 +        <parameter><replaceable>uuid</replaceable>[static
   5.354 +        PWS3_UUID_SIZE]</parameter></paramdef>
   5.355 +      </funcprototype>
   5.356 +      <funcprototype>
   5.357 +        <funcdef>int <function>pws3_field_set_text</function></funcdef>
   5.358 +        <paramdef>struct pws3_field
   5.359 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.360 +        <paramdef>const char
   5.361 +        <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef>
   5.362 +      </funcprototype>
   5.363 +      <funcprototype>
   5.364 +        <funcdef>int <function>pws3_field_set_time</function></funcdef>
   5.365 +        <paramdef>struct pws3_field
   5.366 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.367 +        <paramdef>time_t
   5.368 +        <parameter><replaceable>time</replaceable></parameter></paramdef>
   5.369 +      </funcprototype>
   5.370 +      <funcprototype>
   5.371 +        <funcdef>int <function>pws3_field_set_uint8</function></funcdef>
   5.372 +        <paramdef>struct pws3_field
   5.373 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.374 +        <paramdef>uint8_t
   5.375 +        <parameter><replaceable>u8</replaceable></parameter></paramdef>
   5.376 +      </funcprototype>
   5.377 +      <funcprototype>
   5.378 +        <funcdef>int <function>pws3_field_set_uint16</function></funcdef>
   5.379 +        <paramdef>struct pws3_field
   5.380 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.381 +        <paramdef>uint16_t
   5.382 +        <parameter><replaceable>u16</replaceable></parameter></paramdef>
   5.383 +      </funcprototype>
   5.384 +      <funcprototype>
   5.385 +        <funcdef>int <function>pws3_field_set_uint32</function></funcdef>
   5.386 +        <paramdef>struct pws3_field
   5.387 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.388 +        <paramdef>uint32_t
   5.389 +        <parameter><replaceable>u32</replaceable></parameter></paramdef>
   5.390 +      </funcprototype>
   5.391 +      <funcprototype>
   5.392 +        <funcdef>int <function>pws3_field_set_bytes</function></funcdef>
   5.393 +        <paramdef>struct pws3_field
   5.394 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.395 +        <paramdef>const unsigned char
   5.396 +        <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef>
   5.397 +        <paramdef>size_t
   5.398 +        <parameter><replaceable>n</replaceable></parameter></paramdef>
   5.399 +      </funcprototype>
   5.400 +      <funcprototype>
   5.401 +        <funcdef>const unsigned char *
   5.402 +        <function>pws3_field_get_uuid</function></funcdef>
   5.403 +        <paramdef>struct pws3_field
   5.404 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.405 +      </funcprototype>
   5.406 +      <funcprototype>
   5.407 +        <funcdef>const char *
   5.408 +        <function>pws3_field_get_text</function></funcdef>
   5.409 +        <paramdef>struct pws3_field
   5.410 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.411 +      </funcprototype>
   5.412 +      <funcprototype>
   5.413 +        <funcdef>time_t
   5.414 +        <function>pws3_field_get_time</function></funcdef>
   5.415 +        <paramdef>struct pws3_field
   5.416 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.417 +      </funcprototype>
   5.418 +      <funcprototype>
   5.419 +        <funcdef>uint8_t
   5.420 +        <function>pws3_field_get_uint8</function></funcdef>
   5.421 +        <paramdef>struct pws3_field
   5.422 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.423 +      </funcprototype>
   5.424 +      <funcprototype>
   5.425 +        <funcdef>uint16_t
   5.426 +        <function>pws3_field_get_uint16</function></funcdef>
   5.427 +        <paramdef>struct pws3_field
   5.428 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.429 +      </funcprototype>
   5.430 +      <funcprototype>
   5.431 +        <funcdef>uint32_t
   5.432 +        <function>pws3_field_get_uint32</function></funcdef>
   5.433 +        <paramdef>struct pws3_field
   5.434 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.435 +      </funcprototype>
   5.436 +      <funcprototype>
   5.437 +        <funcdef>void <function>pws3_field_get_bytes</function></funcdef>
   5.438 +        <paramdef>struct pws3_field
   5.439 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   5.440 +        <paramdef>const unsigned char
   5.441 +        **<parameter><replaceable>pp</replaceable></parameter></paramdef>
   5.442 +        <paramdef>size_t
   5.443 +        *<parameter><replaceable>np</replaceable></parameter></paramdef>
   5.444 +      </funcprototype>
   5.445 +    </funcsynopsis>
   5.446 +    <synopsis>
   5.447 +<constant>PWS3_VERSION</constant>
   5.448 +
   5.449 +<constant>PWS3_MAX_FIELD_LEN</constant>
   5.450 +
   5.451 +<constant>PWS3_MAX_PASSWORD_LEN</constant>
   5.452 +
   5.453 +<constant>PWS3_UUID_SIZE</constant>
   5.454 +
   5.455 +struct pws3_field;
   5.456 +
   5.457 +struct pws3_record;
   5.458 +
   5.459 +struct pws3_file;
   5.460 +
   5.461 +enum pws_error_code;
   5.462 +
   5.463 +enum pws_data_type;
   5.464 +
   5.465 +enum pws3_header_field_type;
   5.466 +
   5.467 +enum pws3_record_field_type;
   5.468 +</synopsis>
   5.469 +  </refsynopsisdiv>
   5.470 +  <refsect1>
   5.471 +    <title>Description</title>
   5.472 +    <refsect2>
   5.473 +      <title>Introduction</title>
   5.474 +      <para>The <function>pws3_*()</function> family of functions allows
   5.475 +      creating, reading, writing, and manipulating Password Safe version 3
   5.476 +      files. Password Safe version 3 files consist of a header and a body part.
   5.477 +      The header is comprised of both mandatory and optional typed header
   5.478 +      fields which hold file-wide metadata. The body consists of records which
   5.479 +      in turn hold passwords and associated metadata in typed record
   5.480 +      fields.</para>
   5.481 +      <para>A header or record field value can be of one of seven basic data
   5.482 +      types defined below:
   5.483 +      <table xml:id="table-data-types">
   5.484 +        <title>Header and Record Field Value Data Types</title>
   5.485 +        <tgroup cols="3" align="left" colsep="1" rowsep="1">
   5.486 +          <thead>
   5.487 +            <row>
   5.488 +              <entry>Data Type</entry>
   5.489 +              <entry>C Type</entry>
   5.490 +              <entry>Description</entry>
   5.491 +            </row>
   5.492 +          </thead>
   5.493 +          <tbody>
   5.494 +            <row>
   5.495 +              <entry><constant>PWS_DATA_TYPE_UUID</constant></entry>
   5.496 +              <entry><code>unsigned char [PWS3_UUID_SIZE]</code></entry>
   5.497 +              <entry>UUID</entry>
   5.498 +            </row>
   5.499 +            <row>
   5.500 +              <entry><constant>PWS_DATA_TYPE_TEXT</constant></entry>
   5.501 +              <entry><code>char *</code></entry>
   5.502 +              <entry>NUL-delimited UTF-8 encoded string</entry>
   5.503 +            </row>
   5.504 +            <row>
   5.505 +              <entry><constant>PWS_DATA_TYPE_TIME</constant></entry>
   5.506 +              <entry><code>time_t</code></entry>
   5.507 +              <entry>system-specific representation of time</entry>
   5.508 +            </row>
   5.509 +            <row>
   5.510 +              <entry><constant>PWS_DATA_TYPE_UINT8</constant></entry>
   5.511 +              <entry><code>uint8_t</code></entry>
   5.512 +              <entry>8-bit wide unsigned integer</entry>
   5.513 +            </row>
   5.514 +            <row>
   5.515 +              <entry><constant>PWS_DATA_TYPE_UINT16</constant></entry>
   5.516 +              <entry><code>uint16_t</code></entry>
   5.517 +              <entry>16-bit wide unsigned integer</entry>
   5.518 +            </row>
   5.519 +            <row>
   5.520 +              <entry><constant>PWS_DATA_TYPE_UINT32</constant></entry>
   5.521 +              <entry><code>uint32_t</code></entry>
   5.522 +              <entry>32-bit wide unsigned integer</entry>
   5.523 +            </row>
   5.524 +            <row>
   5.525 +              <entry><constant>PWS_DATA_TYPE_BYTES</constant></entry>
   5.526 +              <entry><code>unsigned char *</code></entry>
   5.527 +              <entry>array of bytes</entry>
   5.528 +            </row>
   5.529 +          </tbody>
   5.530 +        </tgroup>
   5.531 +      </table>
   5.532 +      </para>
   5.533 +      <para>The data type of each header field is defined in
   5.534 +      <xref linkend="table-header-fields"/> and the data type of each record
   5.535 +      field is defined in <xref linkend="table-record-fields"/>. Each header
   5.536 +      field, with the exception of the empty groups header field, can only
   5.537 +      occur once. The version header field
   5.538 +      (<constant>PWS3_HEADER_FIELD_VERSION</constant>) is mandatory and must
   5.539 +      not be removed. When reading a file its value is checked and an error is
   5.540 +      returned if the file format version newer than the one supported by
   5.541 +      <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
   5.542 +      The supported version is defined by the <constant>PWS3_VERSION</constant>
   5.543 +      macro, when creating a new file structure the version header field will be
   5.544 +      set to its value by default. Non-standard header and record fields will
   5.545 +      be preserved when a file is read and subsequently written again, they may
   5.546 +      be read and manipulated as if they had
   5.547 +      <constant>PWS_DATA_TYPE_BYTES</constant> data type. All strings are
   5.548 +      expected to be in UTF-8 encoding.</para>
   5.549 +      <para>The only mandatory record field is the UUID field which uniquely
   5.550 +      identifies a record in the file.</para>
   5.551 +      <para>The complete and authoritative specification of the file format is
   5.552 +      included with the original Password Safe application available from <link
   5.553 +      xlink:href="https://pwsafe.org/"/>.</para>
   5.554 +    </refsect2>
   5.555 +    <refsect2>
   5.556 +      <title>Password Safe File Data Structure</title>
   5.557 +      <para>The <function>pws3_file_create()</function> function allocates and
   5.558 +      intializes a Password Safe file data structure representing a Password
   5.559 +      Safe version 3 file. It automatically creates the mandatory version header
   5.560 +      field and initializes it to the value of the
   5.561 +      <constant>PWS3_VERSION</constant> macro.</para>
   5.562 +      <para>The <function>pws3_file_destroy()</function> function deallocates
   5.563 +      all header fields and records of the file structure passed to it and then
   5.564 +      deallocates the file structure itself.</para>
   5.565 +      <para>The <function>pws3_file_read_mem()</function> and
   5.566 +      <function>pws3_file_read_stream()</function> functions read and parse a
   5.567 +      Password Safe file into the given data structure passed via the
   5.568 +      <parameter>pws_file</parameter> argument, replacing any existing header
   5.569 +      fields and records. The key used to decrypt the file is derived from the
   5.570 +      given <parameter>password</parameter> parameter. The
   5.571 +      <function>pws3_file_read_mem()</function> function reads the file from a
   5.572 +      block of memory <parameter>s</parameter> with the size of
   5.573 +      <parameter>n</parameter> bytes. The
   5.574 +      <function>pws3_file_read_stream()</function> reads the file from the
   5.575 +      stream of the <parameter>fp</parameter> file pointer.</para>
   5.576 +      <para>The <function>pws3_file_write_mem()</function> and
   5.577 +      <function>pws3_file_write_stream()</function> functions write a new
   5.578 +      Password Safe file from the given datat structure. The key used to
   5.579 +      encrypt the file is derived from the <parameter>password</parameter>
   5.580 +      argument using the number of iterations to stretch the key determined by
   5.581 +      the <parameter>n_iter</parameter> argument. The
   5.582 +      <function>pws3_file_write_mem()</function> will allocate and place the
   5.583 +      file contents into memory and return the location and size to the
   5.584 +      locations <parameter>sp</parameter> and <parameter>np</parameter>
   5.585 +      point to. The <function>pws3_file_write_stream()</function> will write the
   5.586 +      file contents to the stream of the <parameter>fp</parameter> file
   5.587 +      pointer.</para>
   5.588 +    </refsect2>
   5.589 +    <refsect2>
   5.590 +      <title>Fields</title>
   5.591 +      <para>Both header and record fields are stored in
   5.592 +      <varname>pws3_field</varname> structures which are allocated and
   5.593 +      initialized with the <function>pws3_field_create()</function> function.
   5.594 +      Depending on whether <parameter>is_header</parameter> is non-zero either
   5.595 +      a header field or a record field data structure of the given field type
   5.596 +      will be created.</para>
   5.597 +      <para>The <function>pws3_field_destroy()</function> function
   5.598 +      deallocates the given field data structure and its content.</para>
   5.599 +      <para>The <function>pws3_field_is_header()</function> function
   5.600 +      can be used to test whether the given field data structure refers to a
   5.601 +      header field or a record field.</para>
   5.602 +      <para>The <function>pws3_field_get_type()</function> function
   5.603 +      returns the field type of the given field data structure.</para>
   5.604 +      <para>The <function>pws3_field_get_data_type()</function> function
   5.605 +      returns the data type of the given field structure.</para>
   5.606 +      <para>The <function>pws3_field_set_uuid()</function>,
   5.607 +      <function>pws3_field_set_text()</function>,
   5.608 +      <function>pws3_field_set_time()</function>,
   5.609 +      <function>pws3_field_set_uint8()</function>,
   5.610 +      <function>pws3_field_set_uint16()</function>,
   5.611 +      <function>pws3_field_set_uint32()</function>, and
   5.612 +      <function>pws3_field_set_bytes()</function> functions set the
   5.613 +      content of the given field. The given data is always copied and
   5.614 +      existing content is replaced. The data type used by the function must
   5.615 +      match the data type of the field specified in <xref
   5.616 +      linkend="table-header-fields"/> in case of header fields or that in <xref
   5.617 +      linkend="table-record-fields"/> in case of record fields.</para>
   5.618 +      <para>The <function>pws3_field_get_time()</function>,
   5.619 +      <function>pws3_field_get_uint8()</function>,
   5.620 +      <function>pws3_field_get_uint16()</function>, and
   5.621 +      <function>pws3_field_get_uint32()</function> functions return the
   5.622 +      value of the given field. The
   5.623 +      <function>pws3_field_get_uuid()</function>,
   5.624 +      <function>pws3_field_get_text()</function>, and
   5.625 +      <function>pws3_field_get_bytes()</function> functions return a
   5.626 +      pointer to the data of the given field if it has been set. The data type
   5.627 +      used by the function must match the data type of the field specified in
   5.628 +      <xref linkend="table-header-fields"/> in case of header fields and that
   5.629 +      in <xref linkend="table-record-fields"/> in case of record fields.
   5.630 +      Returned pointers are only valid until a field is modified or
   5.631 +      deallocated.</para>
   5.632 +    </refsect2>
   5.633 +    <refsect2>
   5.634 +      <title>Header Fields</title>
   5.635 +      <para>Header fields are used to store metadata for the whole file, each
   5.636 +      type of header field with the exception of the empty groups header field
   5.637 +      only occurs once. The following header fields are supported:
   5.638 +      <table xml:id="table-header-fields">
   5.639 +        <title>Header Fields</title>
   5.640 +        <tgroup cols="4" align="left" colsep="1" rowsep="1">
   5.641 +          <thead>
   5.642 +            <row>
   5.643 +              <entry>Header Field Type</entry>
   5.644 +              <entry>Numeric Value</entry>
   5.645 +              <entry>Data Type</entry>
   5.646 +              <entry>Description</entry>
   5.647 +            </row>
   5.648 +          </thead>
   5.649 +          <tbody>
   5.650 +            <row>
   5.651 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;VERSION</constant></entry>
   5.652 +              <entry><literal>0x00</literal></entry>
   5.653 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT16</constant></entry>
   5.654 +              <entry>file format version</entry>
   5.655 +            </row>
   5.656 +            <row>
   5.657 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;UUID</constant></entry>
   5.658 +              <entry><literal>0x01</literal></entry>
   5.659 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
   5.660 +              <entry>UUID</entry>
   5.661 +            </row>
   5.662 +            <row>
   5.663 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;NON_&#8203;DEFAULT_&#8203;PREFERENCES</constant></entry>
   5.664 +              <entry><literal>0x02</literal></entry>
   5.665 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.666 +              <entry>non-default preferences</entry>
   5.667 +            </row>
   5.668 +            <row>
   5.669 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;TREE_&#8203;DISPLAY_&#8203;STATUS</constant></entry>
   5.670 +              <entry><literal>0x03</literal></entry>
   5.671 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.672 +              <entry>expandended/&#8203;collapsed state of the tree of groups</entry>
   5.673 +            </row>
   5.674 +            <row>
   5.675 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;TIMESTAMP</constant></entry>
   5.676 +              <entry><literal>0x04</literal></entry>
   5.677 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   5.678 +              <entry>time when the file was last saved</entry>
   5.679 +            </row>
   5.680 +            <row>
   5.681 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;USER_&#8203;HOST</constant></entry>
   5.682 +              <entry><literal>0x05</literal></entry>
   5.683 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.684 +              <entry>name of the user who last saved the file and name of the host where the file was saved</entry>
   5.685 +            </row>
   5.686 +            <row>
   5.687 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;APPLICATION</constant></entry>
   5.688 +              <entry><literal>0x06</literal></entry>
   5.689 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.690 +              <entry>name of the application used to save the file</entry>
   5.691 +            </row>
   5.692 +            <row>
   5.693 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;USER</constant></entry>
   5.694 +              <entry><literal>0x07</literal></entry>
   5.695 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.696 +              <entry>name of the user who last saved the file</entry>
   5.697 +            </row>
   5.698 +            <row>
   5.699 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;HOST</constant></entry>
   5.700 +              <entry><literal>0x08</literal></entry>
   5.701 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.702 +              <entry>name of the host where the file was last saved</entry>
   5.703 +            </row>
   5.704 +            <row>
   5.705 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;NAME</constant></entry>
   5.706 +              <entry><literal>0x09</literal></entry>
   5.707 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.708 +              <entry>logical name for referring to the file</entry>
   5.709 +            </row>
   5.710 +            <row>
   5.711 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;DESCRIPTION</constant></entry>
   5.712 +              <entry><literal>0x0a</literal></entry>
   5.713 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.714 +              <entry>description of the file</entry>
   5.715 +            </row>
   5.716 +            <row>
   5.717 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;FILTERS</constant></entry>
   5.718 +              <entry><literal>0x0b</literal></entry>
   5.719 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.720 +              <entry>filters for this file</entry>
   5.721 +            </row>
   5.722 +            <row>
   5.723 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
   5.724 +              <entry><literal>0x0c</literal></entry>
   5.725 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   5.726 +              <entry>reserved</entry>
   5.727 +            </row>
   5.728 +            <row>
   5.729 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;2</constant></entry>
   5.730 +              <entry><literal>0x0d</literal></entry>
   5.731 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   5.732 +              <entry>reserved</entry>
   5.733 +            </row>
   5.734 +            <row>
   5.735 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;3</constant></entry>
   5.736 +              <entry><literal>0x0e</literal></entry>
   5.737 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   5.738 +              <entry>reseved</entry>
   5.739 +            </row>
   5.740 +            <row>
   5.741 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RECENTLY_&#8203;USED_&#8203;ENTRIES</constant></entry>
   5.742 +              <entry><literal>0x0f</literal></entry>
   5.743 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.744 +              <entry>list of recently used entries</entry>
   5.745 +            </row>
   5.746 +            <row>
   5.747 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;NAMED_&#8203;PASSWORD_&#8203;POLICIES</constant></entry>
   5.748 +              <entry><literal>0x10</literal></entry>
   5.749 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.750 +              <entry>named password policies</entry>
   5.751 +            </row>
   5.752 +            <row>
   5.753 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;EMPTY_&#8203;GROUPS</constant></entry>
   5.754 +              <entry><literal>0x11</literal></entry>
   5.755 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.756 +              <entry>empty groups which contain no entries</entry>
   5.757 +            </row>
   5.758 +            <row>
   5.759 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;YUBICO</constant></entry>
   5.760 +              <entry><literal>0x12</literal></entry>
   5.761 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.762 +              <entry>reserved</entry>
   5.763 +            </row>
   5.764 +          </tbody>
   5.765 +        </tgroup>
   5.766 +      </table>
   5.767 +      </para>
   5.768 +      <para>The <function>pws3_file_set_header_field()</function> function sets
   5.769 +      the header field on the given file. An existing field of the same type is
   5.770 +      replaced with the exception of fields of type
   5.771 +      <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> for which
   5.772 +      <function>pws3_file_set_header_field()</function> has the same effect as
   5.773 +      calling the <function>pws3_file_insert_empty_group()</function>
   5.774 +      function.</para>
   5.775 +      <para>The <function>pws3_file_get_header_field()</function> function
   5.776 +      returns a pointer to the header field data structure of the given header
   5.777 +      field type. In case of the
   5.778 +      <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type a pointer
   5.779 +      to the first empty group field is returned.</para>
   5.780 +      <para>The <function>pws3_file_remove_header_field()</function> function
   5.781 +      removes the header field from the given file and returns a pointer to it.
   5.782 +      It is the responsibility of the caller to deallocate the header field
   5.783 +      data structure. In case of the
   5.784 +      <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type the first
   5.785 +      empty group is removed.</para>
   5.786 +      <para>The <function>pws3_file_insert_empty_group()</function> function
   5.787 +      inserts the given empty groups field into the file, an existing field for
   5.788 +      a group of the same name is replaced.</para>
   5.789 +      <para>The <function>pws3_file_get_empty_group()</function> function
   5.790 +      returns a pointer to the header field datat structure representing an
   5.791 +      empty group of the given name.</para>
   5.792 +      <para>The <function>pws3_file_remove_empty_group()</function> function
   5.793 +      removes the field representing the empty group of the given name from the
   5.794 +      file and returns a pointer to the header field data structure. It is the
   5.795 +      responsibility of the caller to deallocate the header field data
   5.796 +      structure.</para>
   5.797 +      <para>The <function>pws3_file_first_empty_group()</function> function
   5.798 +      returns a pointer to the first empty group header field.</para>
   5.799 +      <para>The <function>pws3_file_last_empty_group()</function> function
   5.800 +      returns a pointer to the last empty group header field.</para>
   5.801 +      <para>The <function>pws3_file_next_empty_group()</function> function
   5.802 +      returns a pointer to the next empty group header filed data structure
   5.803 +      following the given <parameter>field</parameter>.</para>
   5.804 +      <para>The <function>pws3_file_prev_empty_groupious()</function> function
   5.805 +      returns a pointer to the previous empty group header filed data structure
   5.806 +      preceding the given <parameter>field</parameter>.</para>
   5.807 +    </refsect2>
   5.808 +    <refsect2>
   5.809 +      <title>Records</title>
   5.810 +      <para>Records consist of at least one or more typed fields, they are
   5.811 +      identified by an UUID which is the only mandatory field and must not be
   5.812 +      removed. For presentational purposes records may be organized in
   5.813 +      hierarchical groups. The following record fields are supported:
   5.814 +      <table xml:id="table-record-fields">
   5.815 +        <title>Record Fields</title>
   5.816 +        <tgroup cols="4" align="left" colsep="1" rowsep="1">
   5.817 +          <thead>
   5.818 +            <row>
   5.819 +              <entry>Record Field Type</entry>
   5.820 +              <entry>Numeric Value</entry>
   5.821 +              <entry>Data Type</entry>
   5.822 +              <entry>Description</entry>
   5.823 +            </row>
   5.824 +          </thead>
   5.825 +          <tbody>
   5.826 +            <row>
   5.827 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;UUID</constant></entry>
   5.828 +              <entry><literal>0x01</literal></entry>
   5.829 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
   5.830 +              <entry>UUID identifying the record</entry>
   5.831 +            </row>
   5.832 +            <row>
   5.833 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;GROUP</constant></entry>
   5.834 +              <entry><literal>0x02</literal></entry>
   5.835 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.836 +              <entry>group name the record is a member of</entry>
   5.837 +            </row>
   5.838 +            <row>
   5.839 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;TITLE</constant></entry>
   5.840 +              <entry><literal>0x03</literal></entry>
   5.841 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.842 +              <entry>title</entry>
   5.843 +            </row>
   5.844 +            <row>
   5.845 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;USERNAME</constant></entry>
   5.846 +              <entry><literal>0x04</literal></entry>
   5.847 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.848 +              <entry>username</entry>
   5.849 +            </row>
   5.850 +            <row>
   5.851 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;NOTES</constant></entry>
   5.852 +              <entry><literal>0x05</literal></entry>
   5.853 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.854 +              <entry>notes</entry>
   5.855 +            </row>
   5.856 +            <row>
   5.857 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD</constant></entry>
   5.858 +              <entry><literal>0x06</literal></entry>
   5.859 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.860 +              <entry>password</entry>
   5.861 +            </row>
   5.862 +            <row>
   5.863 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREATION_&#8203;TIME</constant></entry>
   5.864 +              <entry><literal>0x07</literal></entry>
   5.865 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   5.866 +              <entry>time when the record was created</entry>
   5.867 +            </row>
   5.868 +            <row>
   5.869 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
   5.870 +              <entry><literal>0x08</literal></entry>
   5.871 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   5.872 +              <entry>time when the password was last modified</entry>
   5.873 +            </row>
   5.874 +            <row>
   5.875 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ACCESS_&#8203;TIME</constant></entry>
   5.876 +              <entry><literal>0x09</literal></entry>
   5.877 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   5.878 +              <entry>time when the record was last accessed</entry>
   5.879 +            </row>
   5.880 +            <row>
   5.881 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;TIME</constant></entry>
   5.882 +              <entry><literal>0x0a</literal></entry>
   5.883 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   5.884 +              <entry>time when the password expires</entry>
   5.885 +            </row>
   5.886 +            <row>
   5.887 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
   5.888 +              <entry><literal>0x0b</literal></entry>
   5.889 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   5.890 +              <entry>reserved</entry>
   5.891 +            </row>
   5.892 +            <row>
   5.893 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
   5.894 +              <entry><literal>0x0c</literal></entry>
   5.895 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   5.896 +              <entry>time at whcih the record was last modified</entry>
   5.897 +            </row>
   5.898 +            <row>
   5.899 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;URL</constant></entry>
   5.900 +              <entry><literal>0x0d</literal></entry>
   5.901 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.902 +              <entry>URL</entry>
   5.903 +            </row>
   5.904 +            <row>
   5.905 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;AUTOTYPE</constant></entry>
   5.906 +              <entry><literal>0x0e</literal></entry>
   5.907 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.908 +              <entry>text to be typed when using the autotype feature</entry>
   5.909 +            </row>
   5.910 +            <row>
   5.911 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;HISTORY</constant></entry>
   5.912 +              <entry><literal>0x0f</literal></entry>
   5.913 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.914 +              <entry>creation time and values of previously used passwords</entry>
   5.915 +            </row>
   5.916 +            <row>
   5.917 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY</constant></entry>
   5.918 +              <entry><literal>0x10</literal></entry>
   5.919 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.920 +              <entry>password policy</entry>
   5.921 +            </row>
   5.922 +            <row>
   5.923 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;INTERVAL</constant></entry>
   5.924 +              <entry><literal>0x11</literal></entry>
   5.925 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT32</constant></entry>
   5.926 +              <entry>days until the password expires</entry>
   5.927 +            </row>
   5.928 +            <row>
   5.929 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RUN_&#8203;COMMAND</constant></entry>
   5.930 +              <entry><literal>0x12</literal></entry>
   5.931 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.932 +              <entry>command</entry>
   5.933 +            </row>
   5.934 +            <row>
   5.935 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
   5.936 +              <entry><literal>0x13</literal></entry>
   5.937 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   5.938 +              <entry>action on double clicking</entry>
   5.939 +            </row>
   5.940 +            <row>
   5.941 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;EMAIL_&#8203;ADDRESS</constant></entry>
   5.942 +              <entry><literal>0x14</literal></entry>
   5.943 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.944 +              <entry>email address</entry>
   5.945 +            </row>
   5.946 +            <row>
   5.947 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PROTECTED</constant></entry>
   5.948 +              <entry><literal>0x15</literal></entry>
   5.949 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT8</constant></entry>
   5.950 +              <entry>flag whether the record is protected from modification</entry>
   5.951 +            </row>
   5.952 +            <row>
   5.953 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ALLOWED_&#8203;PASSWORD_&#8203;SYMBOLS</constant></entry>
   5.954 +              <entry><literal>0x16</literal></entry>
   5.955 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.956 +              <entry>allowed symbols for generating passwords</entry>
   5.957 +            </row>
   5.958 +            <row>
   5.959 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;SHIFT_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
   5.960 +              <entry><literal>0x17</literal></entry>
   5.961 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   5.962 +              <entry>action on pressing shift and double clicking</entry>
   5.963 +            </row>
   5.964 +            <row>
   5.965 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY_&#8203;NAME</constant></entry>
   5.966 +              <entry><literal>0x18</literal></entry>
   5.967 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   5.968 +              <entry>name of password policy saved in the header</entry>
   5.969 +            </row>
   5.970 +            <row>
   5.971 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;KEYBOARD_&#8203;SHORTCUT</constant></entry>
   5.972 +              <entry><literal>0x19</literal></entry>
   5.973 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   5.974 +              <entry>keyboard shortcut</entry>
   5.975 +            </row>
   5.976 +          </tbody>
   5.977 +        </tgroup>
   5.978 +      </table>
   5.979 +      </para>
   5.980 +      <para>The <function>pws3_record_create()</function> function allocates
   5.981 +      and creates a record data structure, generates an UUID record field and
   5.982 +      adds it to the record.</para>
   5.983 +      <para>The <function>pws3_record_destroy()</function> function deallocates
   5.984 +      the given record data structure and all its record fields.</para>
   5.985 +      <para>The <function>pws3_file_record_field_set()</function> function sets
   5.986 +      the record field on the given record, replacing an existing field of the
   5.987 +      same type.</para>
   5.988 +      <para>The <function>pws3_file_record_field_get()</function> function
   5.989 +      returns a pointer to the record field data structure of the given record
   5.990 +      field type.</para>
   5.991 +      <para>The <function>pws3_file_record_field_remove()</function> function
   5.992 +      removes the record field from the given record and returns a pointer to
   5.993 +      it. It is the responsibility of the caller to deallocate the record field
   5.994 +      data structure.</para>
   5.995 +      <para>The <function>pws3_file_insert_record()</function> function inserts
   5.996 +      the given record into the file, an existing record with the same UUID is
   5.997 +      replaced.</para>
   5.998 +      <para>The <function>pws3_file_get_record()</function> function returns a
   5.999 +      pointer to the record structure representing a record with the given
  5.1000 +      UUID.</para>
  5.1001 +      <para>The <function>pws3_file_remove_record()</function> function removes
  5.1002 +      the record with the given UUID from the file and returns a pointer to the
  5.1003 +      record data structure. It is the responsibility of the caller to
  5.1004 +      deallocate the record data structure.</para>
  5.1005 +      <para>The <function>pws3_file_first_record()</function> function returns a
  5.1006 +      pointer to the first record.</para>
  5.1007 +      <para>The <function>pws3_file_last_record()</function> function returns a
  5.1008 +      pointer to the last record.</para>
  5.1009 +      <para>The <function>pws3_file_next_record()</function> function returns a
  5.1010 +      pointer to the next record following the given
  5.1011 +      <parameter>record</parameter>.</para>
  5.1012 +      <para>The <function>pws3_file_prev_record()</function>
  5.1013 +      function returns a pointer to the previous group preceding the given
  5.1014 +      <parameter>record</parameter>.</para>
  5.1015 +    </refsect2>
  5.1016 +    <refsect2>
  5.1017 +      <title>Macros</title>
  5.1018 +      <para>The macro <constant>PWS3_VERSION</constant> contains the supported
  5.1019 +      version of the Password Safe version 3 file format.</para>
  5.1020 +      <para>The macro <constant>PWS3_MAX_FIELD_SIZE</constant> contains the
  5.1021 +      maxium size for header and record fields in bytes and
  5.1022 +      <constant>PWS3_MAX_PASSWORD_LEN</constant> contains the maxium password
  5.1023 +      length in bytes.</para>
  5.1024 +      <para>The macro <constant>PWS3_UUID_SIZE</constant> contains the size of
  5.1025 +      UUIDs in bytes.</para>
  5.1026 +    </refsect2>
  5.1027 +  </refsect1>
  5.1028 +  <refsect1>
  5.1029 +    <title>Return Values</title>
  5.1030 +    <para>The <function>pws3_file_create()</function> function returns a
  5.1031 +    pointer to a Password Safe file data structure if successful and
  5.1032 +    <constant>NULL</constant> in case of an error.</para>
  5.1033 +    <para>The <function>pws3_file_read_mem()</function>,
  5.1034 +    <function>pws3_file_read_stream()</function>,
  5.1035 +    <function>pws3_file_write_mem()</function>, and
  5.1036 +    <function>pws3_file_write_stream()</function> functions return
  5.1037 +    <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
  5.1038 +    to indicate an error.</para>
  5.1039 +    <para>The <function>pws3_file_get_header_field()</function> function
  5.1040 +    returns a pointer to the header field data structure of the requested type
  5.1041 +    and <constant>NULL</constant> if such a field does not exist.</para>
  5.1042 +    <para>The <function>pws3_file_remove_header_field()</function> function
  5.1043 +    returns a pointer to the header field data structure which was removed from
  5.1044 +    the file or <constant>NULL</constant> if such a field does not exist.</para>
  5.1045 +    <para>The <function>pws3_file_get_empty_group()</function> function returns
  5.1046 +    a pointer to the header field data structure corresponding to the requested
  5.1047 +    empty group and <constant>NULL</constant> if a group of that name does not
  5.1048 +    exist.</para>
  5.1049 +    <para>The <function>pws3_file_remove_empty_group()</function> function
  5.1050 +    returns a pointer to the header field data structure of the empty group
  5.1051 +    which was removed from the file or <constant>NULL</constant> if a group of
  5.1052 +    that name does not exist.</para>
  5.1053 +    <para>The <function>pws3_file_first_empty_group()</function> function
  5.1054 +    returns a pointer to the first of the empty group header fields or
  5.1055 +    <constant>NULL</constant> if there are no such fields.</para>
  5.1056 +    <para>The <function>pws3_file_last_empty_group()</function> function
  5.1057 +    returns a pointer to the last of the empty group header fields or
  5.1058 +    <constant>NULL</constant> if there are no such fields.</para>
  5.1059 +    <para>The <function>pws3_file_next_empty_group()</function> function
  5.1060 +    returns a pointer to the next empty group header field or
  5.1061 +    <constant>NULL</constant> if there are no more such fields.</para>
  5.1062 +    <para>The <function>pws3_file_prev_empty_group()</function> function
  5.1063 +    returns a pointer to the previous empty group header field or
  5.1064 +    <constant>NULL</constant> if there are no more such fields.</para>
  5.1065 +    <para>The <function>pws3_file_get_record()</function> function returns a
  5.1066 +    pointer to the record data structure of the requested record or
  5.1067 +    <constant>NULL</constant> if that record does not exist.</para>
  5.1068 +    <para>The <function>pws3_file_remove_record()</function> function returns a
  5.1069 +    pointer to the record data structure which was removed from the file or
  5.1070 +    <constant>NULL</constant> if no such record exists.</para>
  5.1071 +    <para>The <function>pws3_file_first_record()</function> function returns a
  5.1072 +    pointer to the record data structure of the first record or
  5.1073 +    <constant>NULL</constant> if no records exist.</para>
  5.1074 +    <para>The <function>pws3_file_last_record()</function> function returns a
  5.1075 +    pointer to the record data structure of the last record or
  5.1076 +    <constant>NULL</constant> if no records exist.</para>
  5.1077 +    <para>The <function>pws3_file_next_record()</function> function returns a
  5.1078 +    pointer to the record data structure of the next record or
  5.1079 +    <constant>NULL</constant> if no records exist.</para>
  5.1080 +    <para>The <function>pws3_file_prev_record()</function> function returns a
  5.1081 +    pointer to the record data structure of the previous record or
  5.1082 +    <constant>NULL</constant> if no records exist.</para>
  5.1083 +    <para>The <function>pws3_field_create()</function> function returns a
  5.1084 +    pointer to the new header field data structure on success and
  5.1085 +    <constant>NULL</constant> on failure.</para>
  5.1086 +    <para>The <function>pws3_field_get_type()</function> function returns
  5.1087 +    the field type of the header field structure.</para>
  5.1088 +    <para>The <function>pws3_field_get_data_type()</function> function
  5.1089 +    returns the data type of the header field structure.</para>
  5.1090 +    <para>The <function>pws3_field_set_uuid()</function>,
  5.1091 +    <function>pws3_field_set_text()</function>,
  5.1092 +    <function>pws3_field_set_time()</function>,
  5.1093 +    <function>pws3_field_set_uint8()</function>,
  5.1094 +    <function>pws3_field_set_uint16()</function>,
  5.1095 +    <function>pws3_field_set_uint32()</function>, and
  5.1096 +    <function>pws3_field_set_bytes()</function> functions return
  5.1097 +    <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
  5.1098 +    on failure.</para>
  5.1099 +    <para>The <function>pws3_field_get_time()</function>,
  5.1100 +    <function>pws3_field_get_uint8()</function>,
  5.1101 +    <function>pws3_field_get_uint16()</function>, and
  5.1102 +    <function>pws3_field_get_uint32()</function> functions return a
  5.1103 +    value of the type corresponding to the type of header field.</para>
  5.1104 +    <para>The <function>pws3_field_get_uuid()</function> function
  5.1105 +    returns a pointer to a UUID.</para>
  5.1106 +    <para>The <function>pws3_field_get_text()</function> function
  5.1107 +    returns a pointer to a string or <constant>NULL</constant> if no value has
  5.1108 +    been set.</para>
  5.1109 +    <para>The <function>pws3_record_create()</function> function returns a
  5.1110 +    pointer to a record data structure if successful and
  5.1111 +    <constant>NULL</constant> on failure.</para>
  5.1112 +    <para>The <function>pws3_record_get_field()</function> function returns a
  5.1113 +    pointer to the record field data structure of the requested type or
  5.1114 +    <constant>NULL</constant> if such a field does not exist.</para>
  5.1115 +    <para>The <function>pws3_record_remove_field()</function> function returns
  5.1116 +    a pointer to the record field data structure which was removed from the
  5.1117 +    record or <constant>NULL</constant> if such a field does not exist.</para>
  5.1118 +  </refsect1>
  5.1119 +  <refsect1>
  5.1120 +    <title>Errors</title>
  5.1121 +    <para>If the <function>pws3_file_read_mem()</function>,
  5.1122 +    <function>pws3_file_read_stream()</function>,
  5.1123 +    <function>pws3_file_write_mem()</function>, and
  5.1124 +    <function>pws3_file_write_stream()</function> functions fail, an error code
  5.1125 +    indicating the nature of the error may be obtained using the
  5.1126 +    <function>pws3_file_get_error_code()</function> function and a pointer to a
  5.1127 +    detailed error message may be retrieved using the
  5.1128 +    <function>pws3_file_get_error_message()</function> function. The above
  5.1129 +    functions may fail if:</para>
  5.1130 +    <variablelist>
  5.1131 +      <varlistentry>
  5.1132 +        <term><errorname>PWS_ERR_GENERIC_ERROR</errorname></term>
  5.1133 +        <listitem>
  5.1134 +          <para>An unknown error occurred.</para>
  5.1135 +        </listitem>
  5.1136 +      </varlistentry>
  5.1137 +      <varlistentry>
  5.1138 +        <term><errorname>PWS_ERR_NO_MEMORY</errorname></term>
  5.1139 +        <listitem>
  5.1140 +          <para>There was not enough space to allocate memory.</para>
  5.1141 +        </listitem>
  5.1142 +      </varlistentry>
  5.1143 +      <varlistentry>
  5.1144 +        <term><errorname>PWS_ERR_IO_ERROR</errorname></term>
  5.1145 +        <listitem>
  5.1146 +          <para>An I/O error occurred.</para>
  5.1147 +        </listitem>
  5.1148 +      </varlistentry>
  5.1149 +      <varlistentry>
  5.1150 +        <term><errorname>PWS_ERR_TRUNCATED_FILE</errorname></term>
  5.1151 +        <listitem>
  5.1152 +          <para>The file appears to be truncated.</para>
  5.1153 +        </listitem>
  5.1154 +      </varlistentry>
  5.1155 +      <varlistentry>
  5.1156 +        <term><errorname>PWS_ERR_INVALID_CHECKSUM</errorname></term>
  5.1157 +        <listitem>
  5.1158 +          <para>The calculated checksum does not match the checksum of the
  5.1159 +          file.</para>
  5.1160 +        </listitem>
  5.1161 +      </varlistentry>
  5.1162 +      <varlistentry>
  5.1163 +        <term><errorname>PWS_ERR_INVALID_RECORD</errorname></term>
  5.1164 +        <listitem>
  5.1165 +          <para>A record is invalid.</para>
  5.1166 +        </listitem>
  5.1167 +      </varlistentry>
  5.1168 +      <varlistentry>
  5.1169 +        <term><errorname>PWS_ERR_INVALID_HEADER</errorname></term>
  5.1170 +        <listitem>
  5.1171 +          <para>A header is invalid.</para>
  5.1172 +        </listitem>
  5.1173 +      </varlistentry>
  5.1174 +      <varlistentry>
  5.1175 +        <term><errorname>PWS_ERR_UNSUPPORTED_VERSION</errorname></term>
  5.1176 +        <listitem>
  5.1177 +          <para>The file format version is not supported.</para>
  5.1178 +        </listitem>
  5.1179 +      </varlistentry>
  5.1180 +    </variablelist>
  5.1181 +  </refsect1>
  5.1182 +  <refsect1>
  5.1183 +    <title>Examples</title>
  5.1184 +    <example>
  5.1185 +      <title>Creating a Password Safe file</title>
  5.1186 +      <para>The following code creates a new Password Safe file and sets the
  5.1187 +      save application header field:</para>
  5.1188 +      <programlisting>
  5.1189 +<![CDATA[
  5.1190 +#include <pws.h>
  5.1191 +
  5.1192 +/* ... */
  5.1193 +
  5.1194 +struct pws3_file *file;
  5.1195 +struct pws3_field *application_field;
  5.1196 +
  5.1197 +/* ... */
  5.1198 +
  5.1199 +/* initialize libpws */
  5.1200 +if (pws_init() != 0) {
  5.1201 +	/* handle error */
  5.1202 +}
  5.1203 +
  5.1204 +/* ... */
  5.1205 +
  5.1206 +/* create a new empty file structure */
  5.1207 +file = pws3_file_create();
  5.1208 +if (file == NULL) {
  5.1209 +	/* handle error */
  5.1210 +}
  5.1211 +/* create new empty save application field */
  5.1212 +application_field = pws3_field_create(1, PWS3_HEADER_FIELD_SAVE_APPLICATION);
  5.1213 +if (application_field == NULL) {
  5.1214 +	/* handle error */
  5.1215 +}
  5.1216 +/* set the value of the field */
  5.1217 +if (pws3_field_set_text(application_field, "PasswordManager 2.0") != 0) {
  5.1218 +	/* handle error */
  5.1219 +}
  5.1220 +/* set the header save application field in the file to the new field */
  5.1221 +pws3_file_set_field(file, application_field);
  5.1222 +]]>
  5.1223 +</programlisting>
  5.1224 +    </example>
  5.1225 +    <example>
  5.1226 +      <title>Print the title of each record</title>
  5.1227 +      <para>The following code loops over each record of an existing Password
  5.1228 +      Safe file and prints the content of the title field if it exists:</para>
  5.1229 +      <programlisting>
  5.1230 +<![CDATA[
  5.1231 +#include <stdio.h>
  5.1232 +#include <pws.h>
  5.1233 +
  5.1234 +/* ... */
  5.1235 +
  5.1236 +struct pws3_file *file;
  5.1237 +struct pws3_record *record;
  5.1238 +struct pws3_field *title_field;
  5.1239 +
  5.1240 +/* ... */
  5.1241 +
  5.1242 +/* interate over each record */
  5.1243 +for (record = pws3_file_first_record(file); record != NULL;
  5.1244 +    record = pws3_file_next_record(file, record)) {
  5.1245 +	/* retrieve title field */
  5.1246 +	title_field = pws3_record_get_field(record, PWS3_RECORD_FIELD_TITLE);
  5.1247 +	/* print the title field or "No title" if it does not exitst */
  5.1248 +	printf("Title: %s\n", (title_field != NULL) ?
  5.1249 +	    pws3_record_field_get_text(PWS3_RECORD_FIELD_TITLE) : "No title");
  5.1250 +}
  5.1251 +]]>
  5.1252 +</programlisting>
  5.1253 +    </example>
  5.1254 +    <example>
  5.1255 +      <title>Add a new record to a file</title>
  5.1256 +      <para>The following code creates a new record with a password field, a
  5.1257 +      title field, and a creation time field and adds it to an existing
  5.1258 +      Password Safe file:</para>
  5.1259 +      <programlisting>
  5.1260 +<![CDATA[
  5.1261 +#include <time.h>
  5.1262 +#include <pws.h>
  5.1263 +
  5.1264 +/* ... */
  5.1265 +
  5.1266 +struct pws3_file *file;
  5.1267 +struct pws3_record *record;
  5.1268 +struct pws3_field *password_field;
  5.1269 +struct pws3_field *title_field;
  5.1270 +struct pws3_field *ctime_field;
  5.1271 +time_t		now;
  5.1272 +
  5.1273 +/* ... */
  5.1274 +
  5.1275 +/* create new record */
  5.1276 +record = pws3_record_create();
  5.1277 +if (record == NULL) {
  5.1278 +	/* handle error */
  5.1279 +}
  5.1280 +
  5.1281 +/* create a password field */
  5.1282 +password_field = pws3_record_field_create(PWS3_RECORD_FIELD_PASSWORD);
  5.1283 +if (password_field == NULL) {
  5.1284 +	/* handle error */
  5.1285 +}
  5.1286 +/* set the value of the password field to "PaSsWoRd" */
  5.1287 +if (pws3_record_field_set_text(password_field, "PaSsWoRd") != 0) {
  5.1288 +	/* handle error */
  5.1289 +}
  5.1290 +/* set the password field of the record to the new field */
  5.1291 +pws3_record_set_field(record, password_field);
  5.1292 +
  5.1293 +/* create a title field */
  5.1294 +title_field = pws3_record_field_create(PWS3_RECORD_FIELD_TITLE);
  5.1295 +if (title_field == NULL) {
  5.1296 +	/* handle error */
  5.1297 +}
  5.1298 +/* set the value of the title field to "Foo Bar" */
  5.1299 +if (pws3_record_field_set_text(title_field, "Foo Bar") != 0) {
  5.1300 +	/* handle error */
  5.1301 +}
  5.1302 +/* set the title field of the record to the new field */
  5.1303 +pws3_record_set_field(record, title_field);
  5.1304 +
  5.1305 +/* create a new creation time field */
  5.1306 +ctime_field = pws3_record_field_create(PWS3_RECORD_FIELD_CREATION_TIME);
  5.1307 +if (ctime_field == NULL) {
  5.1308 +	/* handle error */
  5.1309 +}
  5.1310 +/* set the value of the creation time field to the current time */
  5.1311 +pws3_record_field_set_time(ctime_field, time(NULL));
  5.1312 +/* set the creation time field of the record to the new field */
  5.1313 +pws3_record_set_field(record, ctime_field);
  5.1314 +
  5.1315 +/* insert the new record into the file */
  5.1316 +pws3_file_insert_record(file, record);
  5.1317 +]]>
  5.1318 +</programlisting>
  5.1319 +    </example>
  5.1320 +    <example>
  5.1321 +      <title>Reading a Password Safe file</title>
  5.1322 +      <para>The following code opens a Password Safe file named
  5.1323 +      <filename>example.pwsafe3</filename> and parses it:</para>
  5.1324 +      <programlisting>
  5.1325 +<![CDATA[
  5.1326 +#include <stdio.h>
  5.1327 +#include <pws.h>
  5.1328 +
  5.1329 +/* ... */
  5.1330 +
  5.1331 +FILE		*fp;
  5.1332 +struct pws3_file *file;
  5.1333 +
  5.1334 +/* ... */
  5.1335 +
  5.1336 +/* initialize libpws */
  5.1337 +if (pws_init() != 0) {
  5.1338 +	/* handle error */
  5.1339 +}
  5.1340 +
  5.1341 +/* ... */
  5.1342 +
  5.1343 +/* create a new empty file structure */
  5.1344 +file = pws3_file_create();
  5.1345 +if (file == NULL) {
  5.1346 +	/* handle error */
  5.1347 +}
  5.1348 +
  5.1349 +/* open the file */
  5.1350 +fp = fopen("example.pwsafe3", "r");
  5.1351 +if (fp == NULL) {
  5.1352 +	/* handle error */
  5.1353 +}
  5.1354 +
  5.1355 +/* read and parse the file contents into the file structure */
  5.1356 +if (pws3_file_read_stream(file, "PaSsWoRd", fp) != 0) {
  5.1357 +	fprintf(stderr, "error: %s\n",
  5.1358 +	   pws3_file_get_error_message(file));
  5.1359 +	/* handle error */
  5.1360 +}
  5.1361 +]]>
  5.1362 +</programlisting>
  5.1363 +    </example>
  5.1364 +    <example>
  5.1365 +      <title>Writing a Password Safe file</title>
  5.1366 +      <para>The following code writes a Password Safe file to a file
  5.1367 +      named <filename>example.pwsafe3</filename>:</para>
  5.1368 +      <programlisting>
  5.1369 +<![CDATA[
  5.1370 +#include <stdio.h>
  5.1371 +#include <pws.h>
  5.1372 +
  5.1373 +/* ... */
  5.1374 +
  5.1375 +FILE		*fp;
  5.1376 +struct pws3_file *file;
  5.1377 +
  5.1378 +/* ... */
  5.1379 +
  5.1380 +fp = fopen("example.pwsafe3", "w");
  5.1381 +if (fp == NULL) {
  5.1382 +	/* handle error */
  5.1383 +}
  5.1384 +
  5.1385 +if (pws3_file_write_stream(file, "FoOBaR", 10000, fp) != 0) {
  5.1386 +	/* handle error */
  5.1387 +}
  5.1388 +
  5.1389 +fflush(fp);
  5.1390 +fclose(fp);
  5.1391 +]]>
  5.1392 +</programlisting>
  5.1393 +    </example>
  5.1394 +  </refsect1>
  5.1395 +  <refsect1>
  5.1396 +    <title>See Also</title>
  5.1397 +    <para><citerefentry><refentrytitle>libpws</refentrytitle>
  5.1398 +    <manvolnum>3</manvolnum></citerefentry>,
  5.1399 +    <citerefentry><refentrytitle>pws_init</refentrytitle>
  5.1400 +    <manvolnum>3</manvolnum></citerefentry>,
  5.1401 +    <link xlink:href="https://pwsafe.org/"/></para>
  5.1402 +  </refsect1>
  5.1403 +</refentry>
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/pws_init.3.xml	Wed Mar 25 17:10:23 2015 +0100
     6.3 @@ -0,0 +1,159 @@
     6.4 +<?xml version="1.0"?>
     6.5 +<!--
     6.6 +
     6.7 +Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
     6.8 +
     6.9 +Permission is hereby granted, free of charge, to any person obtaining
    6.10 +a copy of this software and associated documentation files (the
    6.11 +"Software"), to deal in the Software without restriction, including
    6.12 +without limitation the rights to use, copy, modify, merge, publish,
    6.13 +distribute, sublicense, and/or sell copies of the Software, and to
    6.14 +permit persons to whom the Software is furnished to do so, subject to
    6.15 +the following conditions:
    6.16 +
    6.17 +The above copyright notice and this permission notice shall be included
    6.18 +in all copies or substantial portions of the Software.
    6.19 +
    6.20 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    6.21 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    6.22 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    6.23 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    6.24 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    6.25 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    6.26 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    6.27 +
    6.28 +-->
    6.29 +<refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
    6.30 +  <info>
    6.31 +    <author>
    6.32 +      <personname>
    6.33 +        <firstname>Guido</firstname>
    6.34 +        <surname>Berhoerster</surname>
    6.35 +      </personname>
    6.36 +      <email>guido+libpws@berhoerster.name</email>
    6.37 +      <personblurb/>
    6.38 +    </author>
    6.39 +    <date>21 March, 2015</date>
    6.40 +  </info>
    6.41 +  <refmeta>
    6.42 +    <refentrytitle>libpws</refentrytitle>
    6.43 +    <manvolnum>3</manvolnum>
    6.44 +    <refmiscinfo class="source"/>
    6.45 +    <refmiscinfo class="version"/>
    6.46 +    <refmiscinfo class="manual">Library Functions</refmiscinfo>
    6.47 +  </refmeta>
    6.48 +  <refnamediv>
    6.49 +    <refname>pws_init</refname>
    6.50 +    <refname>pws_finalize</refname>
    6.51 +    <refname>pws_set_alloc_functions</refname>
    6.52 +    <refname>pws_generate_uuid</refname>
    6.53 +    <refpurpose>initalize and deinitialize libpws</refpurpose>
    6.54 +  </refnamediv>
    6.55 +  <refsynopsisdiv>
    6.56 +    <cmdsynopsis>
    6.57 +      <command>cc</command>
    6.58 +      <arg choice="opt" rep="repeat">
    6.59 +        <option>flag</option>
    6.60 +      </arg>
    6.61 +      <arg choice="plain" rep="repeat">
    6.62 +        <option>file</option>
    6.63 +      </arg>
    6.64 +      <arg choice="plain">
    6.65 +        <option>-lpws</option>
    6.66 +      </arg>
    6.67 +      <arg choice="plain">
    6.68 +        <option>-lnettle</option>
    6.69 +      </arg>
    6.70 +      <arg choice="opt" rep="repeat">
    6.71 +        <option>library</option>
    6.72 +      </arg>
    6.73 +    </cmdsynopsis>
    6.74 +    <funcsynopsis>
    6.75 +      <funcsynopsisinfo>
    6.76 +#include &lt;pws.h&gt;
    6.77 +</funcsynopsisinfo>
    6.78 +      <funcprototype>
    6.79 +        <funcdef>int <function>pws_init</function></funcdef>
    6.80 +        <void/>
    6.81 +      </funcprototype>
    6.82 +      <funcprototype>
    6.83 +        <funcdef>void <function>pws_finalize</function></funcdef>
    6.84 +        <void/>
    6.85 +      </funcprototype>
    6.86 +      <funcprototype>
    6.87 +        <funcdef>void <function>pws_set_alloc_functions</function></funcdef>
    6.88 +        <paramdef>void
    6.89 +        *<funcparams>*<replaceable>alloc_function</replaceable></funcparams><funcparams>size_t</funcparams></paramdef>
    6.90 +        <paramdef>void
    6.91 +        *<funcparams>*<replaceable>realloc_function</replaceable></funcparams><funcparams>void *, size_t</funcparams></paramdef>
    6.92 +        <paramdef>void <funcparams>*<replaceable>free_function</replaceable></funcparams><funcparams>void
    6.93 +        *, size_t</funcparams></paramdef>
    6.94 +        <paramdef>void
    6.95 +        *<funcparams>*<replaceable>secure_alloc_function</replaceable></funcparams><funcparams>size_t</funcparams></paramdef>
    6.96 +        <paramdef>void
    6.97 +        *<funcparams>*<replaceable>secure_realloc_function</replaceable></funcparams><funcparams>void *, size_t</funcparams></paramdef>
    6.98 +        <paramdef>void <funcparams>*<replaceable>secure_free_function</replaceable></funcparams><funcparams>void
    6.99 +        *, size_t</funcparams></paramdef>
   6.100 +      </funcprototype>
   6.101 +      <funcprototype>
   6.102 +        <funcdef>int <function>pws_generate_uuid</function></funcdef>
   6.103 +        <paramdef>unsigned char [static PWS3_UUID_SIZE]</paramdef>
   6.104 +      </funcprototype>
   6.105 +    </funcsynopsis>
   6.106 +    <synopsis>
   6.107 +<constant>LIBPWS_VERSION_MAJOR</constant>
   6.108 +
   6.109 +<constant>LIBPWS_VERSION_MINOR</constant>
   6.110 +
   6.111 +<constant>LIBPWS_VERSION_MICRO</constant>
   6.112 +    </synopsis>
   6.113 +  </refsynopsisdiv>
   6.114 +  <refsect1>
   6.115 +    <title>Description</title>
   6.116 +    <para>The <function>pws_init()</function> function initializes
   6.117 +    <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>
   6.118 +    and must be called before any other function from this library.</para>
   6.119 +    <para>The <function>pws_finalize()</function> function deinitializes
   6.120 +    <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>
   6.121 +    after which no other function from this library may be called.</para>
   6.122 +    <para>The <function>pws_set_alloc_functions()</function> function specifies
   6.123 +    the functions which are used by
   6.124 +    <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>
   6.125 +    to allocate, reallocate or free memory allowing for the use of custom
   6.126 +    allocators. <function>pws_secure_alloc</function>,
   6.127 +    <function>pws_secure_realloc</function>, and
   6.128 +    <function>pws_secure_free</function> are used to allocate, reallocate, and
   6.129 +    free memory containing potentially sensitive information such as passwords,
   6.130 +    this e.g. allows for wrapping the acutal allocation using operating system
   6.131 +    specific facilities to prevent memory from being paged to the swap area or
   6.132 +    to overwrite memory before deallocating it. Any argument set to
   6.133 +    <constant>NULL</constant> will result in the default function being used,
   6.134 +    these are <function>malloc</function>, <function>realloc</function>, and a
   6.135 +    wrapper around <function>free</function>. This function must be called
   6.136 +    after <function>pws_init</function> and before calling any other function
   6.137 +    from this library. It is not reentrant.</para>
   6.138 +    <para>The <function>pws_uuid_create()</function> function generates a new
   6.139 +    random UUID following RFC4122 and places it in the array passed to
   6.140 +    it.</para>
   6.141 +    <para>The macros <constant>LIBPWS_VERSION_MAJOR</constant>,
   6.142 +    <constant>LIBPWS_VERSION_MINOR</constant>, and
   6.143 +    <constant>LIBPWS_VERSION_MICRO</constant> can be used to check the major,
   6.144 +    minor, and micro version of the library.</para>
   6.145 +  </refsect1>
   6.146 +  <refsect1>
   6.147 +    <title>Return Values</title>
   6.148 +    <para>The <function>pws_init()</function> function returns
   6.149 +    <returnvalue>0</returnvalue> if the library was initialized successfully and
   6.150 +    <returnvalue>-1</returnvalue> on failure.</para>
   6.151 +    <para>The <function>pws_generate_uuid()</function> returns
   6.152 +    <returnvalue>0</returnvalue> if a new random UUID has been generated and
   6.153 +    <returnvalue>-1</returnvalue> on failure.</para>
   6.154 +  </refsect1>
   6.155 +  <refsect1>
   6.156 +    <title>See Also</title>
   6.157 +    <para><citerefentry><refentrytitle>libpws</refentrytitle>
   6.158 +    <manvolnum>3</manvolnum></citerefentry>,
   6.159 +    <citerefentry><refentrytitle>pws3_file_create</refentrytitle>
   6.160 +    <manvolnum>3</manvolnum></citerefentry>, RFC4122</para>
   6.161 +  </refsect1>
   6.162 +</refentry>