projects/libpws

diff pws3_file_create.3.xml @ 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
children b3fc9f7e2b43
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/pws3_file_create.3.xml	Wed Mar 25 17:10:23 2015 +0100
     1.3 @@ -0,0 +1,1400 @@
     1.4 +<?xml version="1.0"?>
     1.5 +<!--
     1.6 +
     1.7 +Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
     1.8 +
     1.9 +Permission is hereby granted, free of charge, to any person obtaining
    1.10 +a copy of this software and associated documentation files (the
    1.11 +"Software"), to deal in the Software without restriction, including
    1.12 +without limitation the rights to use, copy, modify, merge, publish,
    1.13 +distribute, sublicense, and/or sell copies of the Software, and to
    1.14 +permit persons to whom the Software is furnished to do so, subject to
    1.15 +the following conditions:
    1.16 +
    1.17 +The above copyright notice and this permission notice shall be included
    1.18 +in all copies or substantial portions of the Software.
    1.19 +
    1.20 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    1.21 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    1.22 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    1.23 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    1.24 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    1.25 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    1.26 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    1.27 +
    1.28 +-->
    1.29 +<refentry xmlns="http://docbook.org/ns/docbook"
    1.30 +  xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
    1.31 +  <info>
    1.32 +    <author>
    1.33 +      <personname>
    1.34 +        <firstname>Guido</firstname>
    1.35 +        <surname>Berhoerster</surname>
    1.36 +      </personname>
    1.37 +      <email>guido+libpws@berhoerster.name</email>
    1.38 +      <personblurb/>
    1.39 +    </author>
    1.40 +    <date>21 March, 2015</date>
    1.41 +  </info>
    1.42 +  <refmeta>
    1.43 +    <refentrytitle>libpws</refentrytitle>
    1.44 +    <manvolnum>3</manvolnum>
    1.45 +    <refmiscinfo class="source"/>
    1.46 +    <refmiscinfo class="version"/>
    1.47 +    <refmiscinfo class="manual">Library Functions</refmiscinfo>
    1.48 +  </refmeta>
    1.49 +  <refnamediv>
    1.50 +    <refname>pws3_file_create</refname>
    1.51 +    <refname>pws3_file_destroy</refname>
    1.52 +    <refname>pws3_file_get_error_code</refname>
    1.53 +    <refname>pws3_file_get_error_message</refname>
    1.54 +    <refname>pws3_file_read_mem</refname>
    1.55 +    <refname>pws3_file_read_stream</refname>
    1.56 +    <refname>pws3_file_write_mem</refname>
    1.57 +    <refname>pws3_file_write_stream</refname>
    1.58 +    <refname>pws3_file_set_header_field</refname>
    1.59 +    <refname>pws3_file_get_header_field</refname>
    1.60 +    <refname>pws3_file_remove_header_field</refname>
    1.61 +    <refname>pws3_file_insert_empty_group</refname>
    1.62 +    <refname>pws3_file_get_empty_group</refname>
    1.63 +    <refname>pws3_file_remove_empty_group</refname>
    1.64 +    <refname>pws3_file_first_empty_group</refname>
    1.65 +    <refname>pws3_file_last_empty_group</refname>
    1.66 +    <refname>pws3_file_next_empty_group</refname>
    1.67 +    <refname>pws3_file_prev_empty_group</refname>
    1.68 +    <refname>pws3_file_insert_record</refname>
    1.69 +    <refname>pws3_file_get_record</refname>
    1.70 +    <refname>pws3_file_remove_record</refname>
    1.71 +    <refname>pws3_file_first_record</refname>
    1.72 +    <refname>pws3_file_last_record</refname>
    1.73 +    <refname>pws3_file_next_record</refname>
    1.74 +    <refname>pws3_file_prev_record</refname>
    1.75 +    <refname>pws3_field_create</refname>
    1.76 +    <refname>pws3_field_destroy</refname>
    1.77 +    <refname>pws3_field_is_header</refname>
    1.78 +    <refname>pws3_field_get_type</refname>
    1.79 +    <refname>pws3_field_get_data_type</refname>
    1.80 +    <refname>pws3_field_set_uuid</refname>
    1.81 +    <refname>pws3_field_set_text</refname>
    1.82 +    <refname>pws3_field_set_time</refname>
    1.83 +    <refname>pws3_field_set_uint8</refname>
    1.84 +    <refname>pws3_field_set_uint16</refname>
    1.85 +    <refname>pws3_field_set_uint32</refname>
    1.86 +    <refname>pws3_field_set_bytes</refname>
    1.87 +    <refname>pws3_field_get_uuid</refname>
    1.88 +    <refname>pws3_field_get_text</refname>
    1.89 +    <refname>pws3_field_get_time</refname>
    1.90 +    <refname>pws3_field_get_uint8</refname>
    1.91 +    <refname>pws3_field_get_uint16</refname>
    1.92 +    <refname>pws3_field_get_uint32</refname>
    1.93 +    <refname>pws3_field_get_bytes</refname>
    1.94 +    <refname>pws3_record_create</refname>
    1.95 +    <refname>pws3_record_destroy</refname>
    1.96 +    <refname>pws3_record_set_field</refname>
    1.97 +    <refname>pws3_record_get_field</refname>
    1.98 +    <refname>pws3_record_remove_field</refname>
    1.99 +    <refpurpose>create and manipulate Password Safe File Version 3
   1.100 +    files</refpurpose>
   1.101 +  </refnamediv>
   1.102 +  <refsynopsisdiv>
   1.103 +    <cmdsynopsis>
   1.104 +      <command>cc</command>
   1.105 +      <arg choice="opt" rep="repeat">
   1.106 +        <option>flag</option>
   1.107 +      </arg>
   1.108 +      <arg choice="plain" rep="repeat">
   1.109 +        <option>file</option>
   1.110 +      </arg>
   1.111 +      <arg choice="plain">
   1.112 +        <option>-lpws</option>
   1.113 +      </arg>
   1.114 +      <arg choice="plain">
   1.115 +        <option>-lnettle</option>
   1.116 +      </arg>
   1.117 +      <arg choice="opt" rep="repeat">
   1.118 +        <option>library</option>
   1.119 +      </arg>
   1.120 +    </cmdsynopsis>
   1.121 +    <funcsynopsis>
   1.122 +      <funcsynopsisinfo>
   1.123 +#include &lt;pws.h&gt;
   1.124 +</funcsynopsisinfo>
   1.125 +      <funcprototype>
   1.126 +        <funcdef>struct pws3_file
   1.127 +        *<function>pws3_file_create</function></funcdef>
   1.128 +        <void/>
   1.129 +      </funcprototype>
   1.130 +      <funcprototype>
   1.131 +        <funcdef>void <function>pws3_file_destroy</function></funcdef>
   1.132 +        <paramdef>struct pws3_file
   1.133 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.134 +      </funcprototype>
   1.135 +      <funcprototype>
   1.136 +        <funcdef>enum pws_error_code
   1.137 +        <function>pws3_file_get_error_code</function></funcdef>
   1.138 +        <paramdef>struct pws3_file
   1.139 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.140 +      </funcprototype>
   1.141 +      <funcprototype>
   1.142 +        <funcdef>const char *
   1.143 +        <function>pws3_file_get_error_message</function></funcdef>
   1.144 +        <paramdef>struct pws3_file
   1.145 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.146 +      </funcprototype>
   1.147 +      <funcprototype>
   1.148 +        <funcdef>int <function>pws3_file_read_mem</function></funcdef>
   1.149 +        <paramdef>struct pws3_file
   1.150 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.151 +        <paramdef>const char
   1.152 +        *<parameter><replaceable>password</replaceable></parameter></paramdef>
   1.153 +        <paramdef>unsigned char
   1.154 +        *<parameter><replaceable>s</replaceable></parameter></paramdef>
   1.155 +        <paramdef>size_t
   1.156 +        <parameter><replaceable>n</replaceable></parameter></paramdef>
   1.157 +      </funcprototype>
   1.158 +      <funcprototype>
   1.159 +        <funcdef>int <function>pws3_file_read_stream</function></funcdef>
   1.160 +        <paramdef>struct pws3_file
   1.161 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.162 +        <paramdef>const char
   1.163 +        *<parameter><replaceable>password</replaceable></parameter></paramdef>
   1.164 +        <paramdef>FILE
   1.165 +        *<parameter><replaceable>fp</replaceable></parameter></paramdef>
   1.166 +      </funcprototype>
   1.167 +      <funcprototype>
   1.168 +        <funcdef>int <function>pws3_file_write_mem</function></funcdef>
   1.169 +        <paramdef>struct pws3_file
   1.170 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.171 +        <paramdef>const char
   1.172 +        *<parameter><replaceable>password</replaceable></parameter></paramdef>
   1.173 +        <paramdef>uint32_t
   1.174 +        <parameter><replaceable>n_iter</replaceable></parameter></paramdef>
   1.175 +        <paramdef>unsigned char
   1.176 +        **<parameter><replaceable>memp</replaceable></parameter></paramdef>
   1.177 +        <paramdef>size_t
   1.178 +        *<parameter><replaceable>mem_sizep</replaceable></parameter></paramdef>
   1.179 +      </funcprototype>
   1.180 +      <funcprototype>
   1.181 +        <funcdef>int <function>pws3_file_write_stream</function></funcdef>
   1.182 +        <paramdef>struct pws3_file
   1.183 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.184 +        <paramdef>const char
   1.185 +        *<parameter><replaceable>password</replaceable></parameter></paramdef>
   1.186 +        <paramdef>uint32_t
   1.187 +        <parameter><replaceable>n_iter</replaceable></parameter></paramdef>
   1.188 +      </funcprototype>
   1.189 +      <funcprototype>
   1.190 +        <funcdef>void <function>pws3_file_set_header_field</function></funcdef>
   1.191 +        <paramdef>struct pws3_file
   1.192 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.193 +        <paramdef>struct pws3_field
   1.194 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.195 +      </funcprototype>
   1.196 +      <funcprototype>
   1.197 +        <funcdef>struct pws3_field *
   1.198 +        <function>pws3_file_get_header_field</function></funcdef>
   1.199 +        <paramdef>struct pws3_file
   1.200 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.201 +        <paramdef>uint8_t
   1.202 +        <parameter><replaceable>field_type</replaceable></parameter></paramdef>
   1.203 +      </funcprototype>
   1.204 +      <funcprototype>
   1.205 +        <funcdef>struct pws3_field *
   1.206 +        <function>pws3_file_remove_header_field</function></funcdef>
   1.207 +        <paramdef>struct pws3_file
   1.208 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.209 +        <paramdef>uint8_t
   1.210 +        <parameter><replaceable>field_type</replaceable></parameter></paramdef>
   1.211 +      </funcprototype>
   1.212 +      <funcprototype>
   1.213 +        <funcdef>void
   1.214 +        <function>pws3_file_insert_empty_group</function></funcdef>
   1.215 +        <paramdef>struct pws3_file
   1.216 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.217 +        <paramdef>struct pws3_field
   1.218 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.219 +      </funcprototype>
   1.220 +      <funcprototype>
   1.221 +        <funcdef>struct pws3_field *
   1.222 +        <function>pws3_file_get_empty_group</function></funcdef>
   1.223 +        <paramdef>struct pws3_file
   1.224 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.225 +        <paramdef>const char
   1.226 +        *<parameter><replaceable>group_name</replaceable></parameter></paramdef>
   1.227 +      </funcprototype>
   1.228 +      <funcprototype>
   1.229 +        <funcdef>struct pws3_field *
   1.230 +        <function>pws3_file_remove_empty_group</function></funcdef>
   1.231 +        <paramdef>struct pws3_file
   1.232 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.233 +        <paramdef>const char
   1.234 +        *<parameter><replaceable>group_name</replaceable></parameter></paramdef>
   1.235 +      </funcprototype>
   1.236 +      <funcprototype>
   1.237 +        <funcdef>struct pws3_field *
   1.238 +        <function>pws3_file_first_empty_group</function></funcdef>
   1.239 +        <paramdef>struct pws3_file
   1.240 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.241 +      </funcprototype>
   1.242 +      <funcprototype>
   1.243 +        <funcdef>struct pws3_field *
   1.244 +        <function>pws3_file_last_empty_group</function></funcdef>
   1.245 +        <paramdef>struct pws3_file
   1.246 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.247 +      </funcprototype>
   1.248 +      <funcprototype>
   1.249 +        <funcdef>struct pws3_field *
   1.250 +        <function>pws3_file_next_empty_group</function></funcdef>
   1.251 +        <paramdef>struct pws3_file
   1.252 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.253 +        <paramdef>struct pws3_field
   1.254 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.255 +      </funcprototype>
   1.256 +      <funcprototype>
   1.257 +        <funcdef>struct pws3_field *
   1.258 +        <function>pws3_file_prev_empty_group</function></funcdef>
   1.259 +        <paramdef>struct pws3_file
   1.260 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.261 +        <paramdef>struct pws3_field
   1.262 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.263 +      </funcprototype>
   1.264 +      <funcprototype>
   1.265 +        <funcdef>void <function>pws3_file_insert_record</function></funcdef>
   1.266 +        <paramdef>struct pws3_file
   1.267 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.268 +        <paramdef>struct pws3_record
   1.269 +        *<parameter><replaceable>record</replaceable></parameter></paramdef>
   1.270 +      </funcprototype>
   1.271 +      <funcprototype>
   1.272 +        <funcdef>struct pws3_record *
   1.273 +        <function>pws3_file_get_record</function></funcdef>
   1.274 +        <paramdef>struct pws3_file
   1.275 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.276 +        <paramdef>const unsigned char
   1.277 +        <parameter><replaceable>uuid</replaceable>[static
   1.278 +        PWS3_UUID_SIZE]</parameter></paramdef>
   1.279 +      </funcprototype>
   1.280 +      <funcprototype>
   1.281 +        <funcdef>struct pws3_record *
   1.282 +        <function>pws3_file_remove_record</function></funcdef>
   1.283 +        <paramdef>struct pws3_file
   1.284 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.285 +        <paramdef>const unsigned char
   1.286 +        <parameter><replaceable>uuid</replaceable>[static
   1.287 +        PWS3_UUID_SIZE]</parameter></paramdef>
   1.288 +      </funcprototype>
   1.289 +      <funcprototype>
   1.290 +        <funcdef>struct pws3_record *
   1.291 +        <function>pws3_file_first_record</function></funcdef>
   1.292 +        <paramdef>struct pws3_file
   1.293 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.294 +      </funcprototype>
   1.295 +      <funcprototype>
   1.296 +        <funcdef>struct pws3_record *
   1.297 +        <function>pws3_file_last_record</function></funcdef>
   1.298 +        <paramdef>struct pws3_file
   1.299 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.300 +      </funcprototype>
   1.301 +      <funcprototype>
   1.302 +        <funcdef>struct pws3_record *
   1.303 +        <function>pws3_file_next_record</function></funcdef>
   1.304 +        <paramdef>struct pws3_file
   1.305 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.306 +        <paramdef>struct pws3_record
   1.307 +        *<parameter><replaceable>record</replaceable></parameter></paramdef>
   1.308 +      </funcprototype>
   1.309 +      <funcprototype>
   1.310 +        <funcdef>struct pws3_record *
   1.311 +        <function>pws3_file_prev_record</function></funcdef>
   1.312 +        <paramdef>struct pws3_file
   1.313 +        *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
   1.314 +        <paramdef>struct pws3_record
   1.315 +        *<parameter><replaceable>record</replaceable></parameter></paramdef>
   1.316 +      </funcprototype>
   1.317 +      <funcprototype>
   1.318 +        <funcdef>struct pws3_field *
   1.319 +        <function>pws3_field_create</function></funcdef>
   1.320 +        <paramdef>int
   1.321 +        <parameter><replaceable>is_header</replaceable></parameter></paramdef>
   1.322 +        <paramdef>uint8_t
   1.323 +        <parameter><replaceable>field_type</replaceable></parameter></paramdef>
   1.324 +      </funcprototype>
   1.325 +      <funcprototype>
   1.326 +        <funcdef>void <function>pws3_field_destroy</function></funcdef>
   1.327 +        <paramdef>struct pws3_field
   1.328 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.329 +      </funcprototype>
   1.330 +      <funcprototype>
   1.331 +        <funcdef>int
   1.332 +        <function>pws3_field_is_header</function></funcdef>
   1.333 +        <paramdef>struct pws3_field
   1.334 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.335 +      </funcprototype>
   1.336 +      <funcprototype>
   1.337 +        <funcdef>uint8_t *
   1.338 +        <function>pws3_field_get_type</function></funcdef>
   1.339 +        <paramdef>struct pws3_field
   1.340 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.341 +      </funcprototype>
   1.342 +      <funcprototype>
   1.343 +        <funcdef>enum pws_data_type *
   1.344 +        <function>pws3_field_get_data_type</function></funcdef>
   1.345 +        <paramdef>struct pws3_field
   1.346 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.347 +      </funcprototype>
   1.348 +      <funcprototype>
   1.349 +        <funcdef>int <function>pws3_field_set_uuid</function></funcdef>
   1.350 +        <paramdef>struct pws3_field
   1.351 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.352 +        <paramdef>const unsigned char
   1.353 +        <parameter><replaceable>uuid</replaceable>[static
   1.354 +        PWS3_UUID_SIZE]</parameter></paramdef>
   1.355 +      </funcprototype>
   1.356 +      <funcprototype>
   1.357 +        <funcdef>int <function>pws3_field_set_text</function></funcdef>
   1.358 +        <paramdef>struct pws3_field
   1.359 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.360 +        <paramdef>const char
   1.361 +        <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef>
   1.362 +      </funcprototype>
   1.363 +      <funcprototype>
   1.364 +        <funcdef>int <function>pws3_field_set_time</function></funcdef>
   1.365 +        <paramdef>struct pws3_field
   1.366 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.367 +        <paramdef>time_t
   1.368 +        <parameter><replaceable>time</replaceable></parameter></paramdef>
   1.369 +      </funcprototype>
   1.370 +      <funcprototype>
   1.371 +        <funcdef>int <function>pws3_field_set_uint8</function></funcdef>
   1.372 +        <paramdef>struct pws3_field
   1.373 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.374 +        <paramdef>uint8_t
   1.375 +        <parameter><replaceable>u8</replaceable></parameter></paramdef>
   1.376 +      </funcprototype>
   1.377 +      <funcprototype>
   1.378 +        <funcdef>int <function>pws3_field_set_uint16</function></funcdef>
   1.379 +        <paramdef>struct pws3_field
   1.380 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.381 +        <paramdef>uint16_t
   1.382 +        <parameter><replaceable>u16</replaceable></parameter></paramdef>
   1.383 +      </funcprototype>
   1.384 +      <funcprototype>
   1.385 +        <funcdef>int <function>pws3_field_set_uint32</function></funcdef>
   1.386 +        <paramdef>struct pws3_field
   1.387 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.388 +        <paramdef>uint32_t
   1.389 +        <parameter><replaceable>u32</replaceable></parameter></paramdef>
   1.390 +      </funcprototype>
   1.391 +      <funcprototype>
   1.392 +        <funcdef>int <function>pws3_field_set_bytes</function></funcdef>
   1.393 +        <paramdef>struct pws3_field
   1.394 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.395 +        <paramdef>const unsigned char
   1.396 +        <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef>
   1.397 +        <paramdef>size_t
   1.398 +        <parameter><replaceable>n</replaceable></parameter></paramdef>
   1.399 +      </funcprototype>
   1.400 +      <funcprototype>
   1.401 +        <funcdef>const unsigned char *
   1.402 +        <function>pws3_field_get_uuid</function></funcdef>
   1.403 +        <paramdef>struct pws3_field
   1.404 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.405 +      </funcprototype>
   1.406 +      <funcprototype>
   1.407 +        <funcdef>const char *
   1.408 +        <function>pws3_field_get_text</function></funcdef>
   1.409 +        <paramdef>struct pws3_field
   1.410 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.411 +      </funcprototype>
   1.412 +      <funcprototype>
   1.413 +        <funcdef>time_t
   1.414 +        <function>pws3_field_get_time</function></funcdef>
   1.415 +        <paramdef>struct pws3_field
   1.416 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.417 +      </funcprototype>
   1.418 +      <funcprototype>
   1.419 +        <funcdef>uint8_t
   1.420 +        <function>pws3_field_get_uint8</function></funcdef>
   1.421 +        <paramdef>struct pws3_field
   1.422 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.423 +      </funcprototype>
   1.424 +      <funcprototype>
   1.425 +        <funcdef>uint16_t
   1.426 +        <function>pws3_field_get_uint16</function></funcdef>
   1.427 +        <paramdef>struct pws3_field
   1.428 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.429 +      </funcprototype>
   1.430 +      <funcprototype>
   1.431 +        <funcdef>uint32_t
   1.432 +        <function>pws3_field_get_uint32</function></funcdef>
   1.433 +        <paramdef>struct pws3_field
   1.434 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.435 +      </funcprototype>
   1.436 +      <funcprototype>
   1.437 +        <funcdef>void <function>pws3_field_get_bytes</function></funcdef>
   1.438 +        <paramdef>struct pws3_field
   1.439 +        *<parameter><replaceable>field</replaceable></parameter></paramdef>
   1.440 +        <paramdef>const unsigned char
   1.441 +        **<parameter><replaceable>pp</replaceable></parameter></paramdef>
   1.442 +        <paramdef>size_t
   1.443 +        *<parameter><replaceable>np</replaceable></parameter></paramdef>
   1.444 +      </funcprototype>
   1.445 +    </funcsynopsis>
   1.446 +    <synopsis>
   1.447 +<constant>PWS3_VERSION</constant>
   1.448 +
   1.449 +<constant>PWS3_MAX_FIELD_LEN</constant>
   1.450 +
   1.451 +<constant>PWS3_MAX_PASSWORD_LEN</constant>
   1.452 +
   1.453 +<constant>PWS3_UUID_SIZE</constant>
   1.454 +
   1.455 +struct pws3_field;
   1.456 +
   1.457 +struct pws3_record;
   1.458 +
   1.459 +struct pws3_file;
   1.460 +
   1.461 +enum pws_error_code;
   1.462 +
   1.463 +enum pws_data_type;
   1.464 +
   1.465 +enum pws3_header_field_type;
   1.466 +
   1.467 +enum pws3_record_field_type;
   1.468 +</synopsis>
   1.469 +  </refsynopsisdiv>
   1.470 +  <refsect1>
   1.471 +    <title>Description</title>
   1.472 +    <refsect2>
   1.473 +      <title>Introduction</title>
   1.474 +      <para>The <function>pws3_*()</function> family of functions allows
   1.475 +      creating, reading, writing, and manipulating Password Safe version 3
   1.476 +      files. Password Safe version 3 files consist of a header and a body part.
   1.477 +      The header is comprised of both mandatory and optional typed header
   1.478 +      fields which hold file-wide metadata. The body consists of records which
   1.479 +      in turn hold passwords and associated metadata in typed record
   1.480 +      fields.</para>
   1.481 +      <para>A header or record field value can be of one of seven basic data
   1.482 +      types defined below:
   1.483 +      <table xml:id="table-data-types">
   1.484 +        <title>Header and Record Field Value Data Types</title>
   1.485 +        <tgroup cols="3" align="left" colsep="1" rowsep="1">
   1.486 +          <thead>
   1.487 +            <row>
   1.488 +              <entry>Data Type</entry>
   1.489 +              <entry>C Type</entry>
   1.490 +              <entry>Description</entry>
   1.491 +            </row>
   1.492 +          </thead>
   1.493 +          <tbody>
   1.494 +            <row>
   1.495 +              <entry><constant>PWS_DATA_TYPE_UUID</constant></entry>
   1.496 +              <entry><code>unsigned char [PWS3_UUID_SIZE]</code></entry>
   1.497 +              <entry>UUID</entry>
   1.498 +            </row>
   1.499 +            <row>
   1.500 +              <entry><constant>PWS_DATA_TYPE_TEXT</constant></entry>
   1.501 +              <entry><code>char *</code></entry>
   1.502 +              <entry>NUL-delimited UTF-8 encoded string</entry>
   1.503 +            </row>
   1.504 +            <row>
   1.505 +              <entry><constant>PWS_DATA_TYPE_TIME</constant></entry>
   1.506 +              <entry><code>time_t</code></entry>
   1.507 +              <entry>system-specific representation of time</entry>
   1.508 +            </row>
   1.509 +            <row>
   1.510 +              <entry><constant>PWS_DATA_TYPE_UINT8</constant></entry>
   1.511 +              <entry><code>uint8_t</code></entry>
   1.512 +              <entry>8-bit wide unsigned integer</entry>
   1.513 +            </row>
   1.514 +            <row>
   1.515 +              <entry><constant>PWS_DATA_TYPE_UINT16</constant></entry>
   1.516 +              <entry><code>uint16_t</code></entry>
   1.517 +              <entry>16-bit wide unsigned integer</entry>
   1.518 +            </row>
   1.519 +            <row>
   1.520 +              <entry><constant>PWS_DATA_TYPE_UINT32</constant></entry>
   1.521 +              <entry><code>uint32_t</code></entry>
   1.522 +              <entry>32-bit wide unsigned integer</entry>
   1.523 +            </row>
   1.524 +            <row>
   1.525 +              <entry><constant>PWS_DATA_TYPE_BYTES</constant></entry>
   1.526 +              <entry><code>unsigned char *</code></entry>
   1.527 +              <entry>array of bytes</entry>
   1.528 +            </row>
   1.529 +          </tbody>
   1.530 +        </tgroup>
   1.531 +      </table>
   1.532 +      </para>
   1.533 +      <para>The data type of each header field is defined in
   1.534 +      <xref linkend="table-header-fields"/> and the data type of each record
   1.535 +      field is defined in <xref linkend="table-record-fields"/>. Each header
   1.536 +      field, with the exception of the empty groups header field, can only
   1.537 +      occur once. The version header field
   1.538 +      (<constant>PWS3_HEADER_FIELD_VERSION</constant>) is mandatory and must
   1.539 +      not be removed. When reading a file its value is checked and an error is
   1.540 +      returned if the file format version newer than the one supported by
   1.541 +      <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
   1.542 +      The supported version is defined by the <constant>PWS3_VERSION</constant>
   1.543 +      macro, when creating a new file structure the version header field will be
   1.544 +      set to its value by default. Non-standard header and record fields will
   1.545 +      be preserved when a file is read and subsequently written again, they may
   1.546 +      be read and manipulated as if they had
   1.547 +      <constant>PWS_DATA_TYPE_BYTES</constant> data type. All strings are
   1.548 +      expected to be in UTF-8 encoding.</para>
   1.549 +      <para>The only mandatory record field is the UUID field which uniquely
   1.550 +      identifies a record in the file.</para>
   1.551 +      <para>The complete and authoritative specification of the file format is
   1.552 +      included with the original Password Safe application available from <link
   1.553 +      xlink:href="https://pwsafe.org/"/>.</para>
   1.554 +    </refsect2>
   1.555 +    <refsect2>
   1.556 +      <title>Password Safe File Data Structure</title>
   1.557 +      <para>The <function>pws3_file_create()</function> function allocates and
   1.558 +      intializes a Password Safe file data structure representing a Password
   1.559 +      Safe version 3 file. It automatically creates the mandatory version header
   1.560 +      field and initializes it to the value of the
   1.561 +      <constant>PWS3_VERSION</constant> macro.</para>
   1.562 +      <para>The <function>pws3_file_destroy()</function> function deallocates
   1.563 +      all header fields and records of the file structure passed to it and then
   1.564 +      deallocates the file structure itself.</para>
   1.565 +      <para>The <function>pws3_file_read_mem()</function> and
   1.566 +      <function>pws3_file_read_stream()</function> functions read and parse a
   1.567 +      Password Safe file into the given data structure passed via the
   1.568 +      <parameter>pws_file</parameter> argument, replacing any existing header
   1.569 +      fields and records. The key used to decrypt the file is derived from the
   1.570 +      given <parameter>password</parameter> parameter. The
   1.571 +      <function>pws3_file_read_mem()</function> function reads the file from a
   1.572 +      block of memory <parameter>s</parameter> with the size of
   1.573 +      <parameter>n</parameter> bytes. The
   1.574 +      <function>pws3_file_read_stream()</function> reads the file from the
   1.575 +      stream of the <parameter>fp</parameter> file pointer.</para>
   1.576 +      <para>The <function>pws3_file_write_mem()</function> and
   1.577 +      <function>pws3_file_write_stream()</function> functions write a new
   1.578 +      Password Safe file from the given datat structure. The key used to
   1.579 +      encrypt the file is derived from the <parameter>password</parameter>
   1.580 +      argument using the number of iterations to stretch the key determined by
   1.581 +      the <parameter>n_iter</parameter> argument. The
   1.582 +      <function>pws3_file_write_mem()</function> will allocate and place the
   1.583 +      file contents into memory and return the location and size to the
   1.584 +      locations <parameter>sp</parameter> and <parameter>np</parameter>
   1.585 +      point to. The <function>pws3_file_write_stream()</function> will write the
   1.586 +      file contents to the stream of the <parameter>fp</parameter> file
   1.587 +      pointer.</para>
   1.588 +    </refsect2>
   1.589 +    <refsect2>
   1.590 +      <title>Fields</title>
   1.591 +      <para>Both header and record fields are stored in
   1.592 +      <varname>pws3_field</varname> structures which are allocated and
   1.593 +      initialized with the <function>pws3_field_create()</function> function.
   1.594 +      Depending on whether <parameter>is_header</parameter> is non-zero either
   1.595 +      a header field or a record field data structure of the given field type
   1.596 +      will be created.</para>
   1.597 +      <para>The <function>pws3_field_destroy()</function> function
   1.598 +      deallocates the given field data structure and its content.</para>
   1.599 +      <para>The <function>pws3_field_is_header()</function> function
   1.600 +      can be used to test whether the given field data structure refers to a
   1.601 +      header field or a record field.</para>
   1.602 +      <para>The <function>pws3_field_get_type()</function> function
   1.603 +      returns the field type of the given field data structure.</para>
   1.604 +      <para>The <function>pws3_field_get_data_type()</function> function
   1.605 +      returns the data type of the given field structure.</para>
   1.606 +      <para>The <function>pws3_field_set_uuid()</function>,
   1.607 +      <function>pws3_field_set_text()</function>,
   1.608 +      <function>pws3_field_set_time()</function>,
   1.609 +      <function>pws3_field_set_uint8()</function>,
   1.610 +      <function>pws3_field_set_uint16()</function>,
   1.611 +      <function>pws3_field_set_uint32()</function>, and
   1.612 +      <function>pws3_field_set_bytes()</function> functions set the
   1.613 +      content of the given field. The given data is always copied and
   1.614 +      existing content is replaced. The data type used by the function must
   1.615 +      match the data type of the field specified in <xref
   1.616 +      linkend="table-header-fields"/> in case of header fields or that in <xref
   1.617 +      linkend="table-record-fields"/> in case of record fields.</para>
   1.618 +      <para>The <function>pws3_field_get_time()</function>,
   1.619 +      <function>pws3_field_get_uint8()</function>,
   1.620 +      <function>pws3_field_get_uint16()</function>, and
   1.621 +      <function>pws3_field_get_uint32()</function> functions return the
   1.622 +      value of the given field. The
   1.623 +      <function>pws3_field_get_uuid()</function>,
   1.624 +      <function>pws3_field_get_text()</function>, and
   1.625 +      <function>pws3_field_get_bytes()</function> functions return a
   1.626 +      pointer to the data of the given field if it has been set. The data type
   1.627 +      used by the function must match the data type of the field specified in
   1.628 +      <xref linkend="table-header-fields"/> in case of header fields and that
   1.629 +      in <xref linkend="table-record-fields"/> in case of record fields.
   1.630 +      Returned pointers are only valid until a field is modified or
   1.631 +      deallocated.</para>
   1.632 +    </refsect2>
   1.633 +    <refsect2>
   1.634 +      <title>Header Fields</title>
   1.635 +      <para>Header fields are used to store metadata for the whole file, each
   1.636 +      type of header field with the exception of the empty groups header field
   1.637 +      only occurs once. The following header fields are supported:
   1.638 +      <table xml:id="table-header-fields">
   1.639 +        <title>Header Fields</title>
   1.640 +        <tgroup cols="4" align="left" colsep="1" rowsep="1">
   1.641 +          <thead>
   1.642 +            <row>
   1.643 +              <entry>Header Field Type</entry>
   1.644 +              <entry>Numeric Value</entry>
   1.645 +              <entry>Data Type</entry>
   1.646 +              <entry>Description</entry>
   1.647 +            </row>
   1.648 +          </thead>
   1.649 +          <tbody>
   1.650 +            <row>
   1.651 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;VERSION</constant></entry>
   1.652 +              <entry><literal>0x00</literal></entry>
   1.653 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT16</constant></entry>
   1.654 +              <entry>file format version</entry>
   1.655 +            </row>
   1.656 +            <row>
   1.657 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;UUID</constant></entry>
   1.658 +              <entry><literal>0x01</literal></entry>
   1.659 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
   1.660 +              <entry>UUID</entry>
   1.661 +            </row>
   1.662 +            <row>
   1.663 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;NON_&#8203;DEFAULT_&#8203;PREFERENCES</constant></entry>
   1.664 +              <entry><literal>0x02</literal></entry>
   1.665 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.666 +              <entry>non-default preferences</entry>
   1.667 +            </row>
   1.668 +            <row>
   1.669 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;TREE_&#8203;DISPLAY_&#8203;STATUS</constant></entry>
   1.670 +              <entry><literal>0x03</literal></entry>
   1.671 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.672 +              <entry>expandended/&#8203;collapsed state of the tree of groups</entry>
   1.673 +            </row>
   1.674 +            <row>
   1.675 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;TIMESTAMP</constant></entry>
   1.676 +              <entry><literal>0x04</literal></entry>
   1.677 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   1.678 +              <entry>time when the file was last saved</entry>
   1.679 +            </row>
   1.680 +            <row>
   1.681 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;USER_&#8203;HOST</constant></entry>
   1.682 +              <entry><literal>0x05</literal></entry>
   1.683 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.684 +              <entry>name of the user who last saved the file and name of the host where the file was saved</entry>
   1.685 +            </row>
   1.686 +            <row>
   1.687 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;APPLICATION</constant></entry>
   1.688 +              <entry><literal>0x06</literal></entry>
   1.689 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.690 +              <entry>name of the application used to save the file</entry>
   1.691 +            </row>
   1.692 +            <row>
   1.693 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;USER</constant></entry>
   1.694 +              <entry><literal>0x07</literal></entry>
   1.695 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.696 +              <entry>name of the user who last saved the file</entry>
   1.697 +            </row>
   1.698 +            <row>
   1.699 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;HOST</constant></entry>
   1.700 +              <entry><literal>0x08</literal></entry>
   1.701 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.702 +              <entry>name of the host where the file was last saved</entry>
   1.703 +            </row>
   1.704 +            <row>
   1.705 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;NAME</constant></entry>
   1.706 +              <entry><literal>0x09</literal></entry>
   1.707 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.708 +              <entry>logical name for referring to the file</entry>
   1.709 +            </row>
   1.710 +            <row>
   1.711 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;DESCRIPTION</constant></entry>
   1.712 +              <entry><literal>0x0a</literal></entry>
   1.713 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.714 +              <entry>description of the file</entry>
   1.715 +            </row>
   1.716 +            <row>
   1.717 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;FILTERS</constant></entry>
   1.718 +              <entry><literal>0x0b</literal></entry>
   1.719 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.720 +              <entry>filters for this file</entry>
   1.721 +            </row>
   1.722 +            <row>
   1.723 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
   1.724 +              <entry><literal>0x0c</literal></entry>
   1.725 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   1.726 +              <entry>reserved</entry>
   1.727 +            </row>
   1.728 +            <row>
   1.729 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;2</constant></entry>
   1.730 +              <entry><literal>0x0d</literal></entry>
   1.731 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   1.732 +              <entry>reserved</entry>
   1.733 +            </row>
   1.734 +            <row>
   1.735 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;3</constant></entry>
   1.736 +              <entry><literal>0x0e</literal></entry>
   1.737 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   1.738 +              <entry>reseved</entry>
   1.739 +            </row>
   1.740 +            <row>
   1.741 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RECENTLY_&#8203;USED_&#8203;ENTRIES</constant></entry>
   1.742 +              <entry><literal>0x0f</literal></entry>
   1.743 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.744 +              <entry>list of recently used entries</entry>
   1.745 +            </row>
   1.746 +            <row>
   1.747 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;NAMED_&#8203;PASSWORD_&#8203;POLICIES</constant></entry>
   1.748 +              <entry><literal>0x10</literal></entry>
   1.749 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.750 +              <entry>named password policies</entry>
   1.751 +            </row>
   1.752 +            <row>
   1.753 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;EMPTY_&#8203;GROUPS</constant></entry>
   1.754 +              <entry><literal>0x11</literal></entry>
   1.755 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.756 +              <entry>empty groups which contain no entries</entry>
   1.757 +            </row>
   1.758 +            <row>
   1.759 +              <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;YUBICO</constant></entry>
   1.760 +              <entry><literal>0x12</literal></entry>
   1.761 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.762 +              <entry>reserved</entry>
   1.763 +            </row>
   1.764 +          </tbody>
   1.765 +        </tgroup>
   1.766 +      </table>
   1.767 +      </para>
   1.768 +      <para>The <function>pws3_file_set_header_field()</function> function sets
   1.769 +      the header field on the given file. An existing field of the same type is
   1.770 +      replaced with the exception of fields of type
   1.771 +      <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> for which
   1.772 +      <function>pws3_file_set_header_field()</function> has the same effect as
   1.773 +      calling the <function>pws3_file_insert_empty_group()</function>
   1.774 +      function.</para>
   1.775 +      <para>The <function>pws3_file_get_header_field()</function> function
   1.776 +      returns a pointer to the header field data structure of the given header
   1.777 +      field type. In case of the
   1.778 +      <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type a pointer
   1.779 +      to the first empty group field is returned.</para>
   1.780 +      <para>The <function>pws3_file_remove_header_field()</function> function
   1.781 +      removes the header field from the given file and returns a pointer to it.
   1.782 +      It is the responsibility of the caller to deallocate the header field
   1.783 +      data structure. In case of the
   1.784 +      <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type the first
   1.785 +      empty group is removed.</para>
   1.786 +      <para>The <function>pws3_file_insert_empty_group()</function> function
   1.787 +      inserts the given empty groups field into the file, an existing field for
   1.788 +      a group of the same name is replaced.</para>
   1.789 +      <para>The <function>pws3_file_get_empty_group()</function> function
   1.790 +      returns a pointer to the header field datat structure representing an
   1.791 +      empty group of the given name.</para>
   1.792 +      <para>The <function>pws3_file_remove_empty_group()</function> function
   1.793 +      removes the field representing the empty group of the given name from the
   1.794 +      file and returns a pointer to the header field data structure. It is the
   1.795 +      responsibility of the caller to deallocate the header field data
   1.796 +      structure.</para>
   1.797 +      <para>The <function>pws3_file_first_empty_group()</function> function
   1.798 +      returns a pointer to the first empty group header field.</para>
   1.799 +      <para>The <function>pws3_file_last_empty_group()</function> function
   1.800 +      returns a pointer to the last empty group header field.</para>
   1.801 +      <para>The <function>pws3_file_next_empty_group()</function> function
   1.802 +      returns a pointer to the next empty group header filed data structure
   1.803 +      following the given <parameter>field</parameter>.</para>
   1.804 +      <para>The <function>pws3_file_prev_empty_groupious()</function> function
   1.805 +      returns a pointer to the previous empty group header filed data structure
   1.806 +      preceding the given <parameter>field</parameter>.</para>
   1.807 +    </refsect2>
   1.808 +    <refsect2>
   1.809 +      <title>Records</title>
   1.810 +      <para>Records consist of at least one or more typed fields, they are
   1.811 +      identified by an UUID which is the only mandatory field and must not be
   1.812 +      removed. For presentational purposes records may be organized in
   1.813 +      hierarchical groups. The following record fields are supported:
   1.814 +      <table xml:id="table-record-fields">
   1.815 +        <title>Record Fields</title>
   1.816 +        <tgroup cols="4" align="left" colsep="1" rowsep="1">
   1.817 +          <thead>
   1.818 +            <row>
   1.819 +              <entry>Record Field Type</entry>
   1.820 +              <entry>Numeric Value</entry>
   1.821 +              <entry>Data Type</entry>
   1.822 +              <entry>Description</entry>
   1.823 +            </row>
   1.824 +          </thead>
   1.825 +          <tbody>
   1.826 +            <row>
   1.827 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;UUID</constant></entry>
   1.828 +              <entry><literal>0x01</literal></entry>
   1.829 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
   1.830 +              <entry>UUID identifying the record</entry>
   1.831 +            </row>
   1.832 +            <row>
   1.833 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;GROUP</constant></entry>
   1.834 +              <entry><literal>0x02</literal></entry>
   1.835 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.836 +              <entry>group name the record is a member of</entry>
   1.837 +            </row>
   1.838 +            <row>
   1.839 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;TITLE</constant></entry>
   1.840 +              <entry><literal>0x03</literal></entry>
   1.841 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.842 +              <entry>title</entry>
   1.843 +            </row>
   1.844 +            <row>
   1.845 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;USERNAME</constant></entry>
   1.846 +              <entry><literal>0x04</literal></entry>
   1.847 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.848 +              <entry>username</entry>
   1.849 +            </row>
   1.850 +            <row>
   1.851 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;NOTES</constant></entry>
   1.852 +              <entry><literal>0x05</literal></entry>
   1.853 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.854 +              <entry>notes</entry>
   1.855 +            </row>
   1.856 +            <row>
   1.857 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD</constant></entry>
   1.858 +              <entry><literal>0x06</literal></entry>
   1.859 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.860 +              <entry>password</entry>
   1.861 +            </row>
   1.862 +            <row>
   1.863 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREATION_&#8203;TIME</constant></entry>
   1.864 +              <entry><literal>0x07</literal></entry>
   1.865 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   1.866 +              <entry>time when the record was created</entry>
   1.867 +            </row>
   1.868 +            <row>
   1.869 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
   1.870 +              <entry><literal>0x08</literal></entry>
   1.871 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   1.872 +              <entry>time when the password was last modified</entry>
   1.873 +            </row>
   1.874 +            <row>
   1.875 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ACCESS_&#8203;TIME</constant></entry>
   1.876 +              <entry><literal>0x09</literal></entry>
   1.877 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   1.878 +              <entry>time when the record was last accessed</entry>
   1.879 +            </row>
   1.880 +            <row>
   1.881 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;TIME</constant></entry>
   1.882 +              <entry><literal>0x0a</literal></entry>
   1.883 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   1.884 +              <entry>time when the password expires</entry>
   1.885 +            </row>
   1.886 +            <row>
   1.887 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
   1.888 +              <entry><literal>0x0b</literal></entry>
   1.889 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   1.890 +              <entry>reserved</entry>
   1.891 +            </row>
   1.892 +            <row>
   1.893 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
   1.894 +              <entry><literal>0x0c</literal></entry>
   1.895 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
   1.896 +              <entry>time at whcih the record was last modified</entry>
   1.897 +            </row>
   1.898 +            <row>
   1.899 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;URL</constant></entry>
   1.900 +              <entry><literal>0x0d</literal></entry>
   1.901 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.902 +              <entry>URL</entry>
   1.903 +            </row>
   1.904 +            <row>
   1.905 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;AUTOTYPE</constant></entry>
   1.906 +              <entry><literal>0x0e</literal></entry>
   1.907 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.908 +              <entry>text to be typed when using the autotype feature</entry>
   1.909 +            </row>
   1.910 +            <row>
   1.911 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;HISTORY</constant></entry>
   1.912 +              <entry><literal>0x0f</literal></entry>
   1.913 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.914 +              <entry>creation time and values of previously used passwords</entry>
   1.915 +            </row>
   1.916 +            <row>
   1.917 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY</constant></entry>
   1.918 +              <entry><literal>0x10</literal></entry>
   1.919 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.920 +              <entry>password policy</entry>
   1.921 +            </row>
   1.922 +            <row>
   1.923 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;INTERVAL</constant></entry>
   1.924 +              <entry><literal>0x11</literal></entry>
   1.925 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT32</constant></entry>
   1.926 +              <entry>days until the password expires</entry>
   1.927 +            </row>
   1.928 +            <row>
   1.929 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RUN_&#8203;COMMAND</constant></entry>
   1.930 +              <entry><literal>0x12</literal></entry>
   1.931 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.932 +              <entry>command</entry>
   1.933 +            </row>
   1.934 +            <row>
   1.935 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
   1.936 +              <entry><literal>0x13</literal></entry>
   1.937 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   1.938 +              <entry>action on double clicking</entry>
   1.939 +            </row>
   1.940 +            <row>
   1.941 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;EMAIL_&#8203;ADDRESS</constant></entry>
   1.942 +              <entry><literal>0x14</literal></entry>
   1.943 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.944 +              <entry>email address</entry>
   1.945 +            </row>
   1.946 +            <row>
   1.947 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PROTECTED</constant></entry>
   1.948 +              <entry><literal>0x15</literal></entry>
   1.949 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT8</constant></entry>
   1.950 +              <entry>flag whether the record is protected from modification</entry>
   1.951 +            </row>
   1.952 +            <row>
   1.953 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ALLOWED_&#8203;PASSWORD_&#8203;SYMBOLS</constant></entry>
   1.954 +              <entry><literal>0x16</literal></entry>
   1.955 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.956 +              <entry>allowed symbols for generating passwords</entry>
   1.957 +            </row>
   1.958 +            <row>
   1.959 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;SHIFT_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
   1.960 +              <entry><literal>0x17</literal></entry>
   1.961 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   1.962 +              <entry>action on pressing shift and double clicking</entry>
   1.963 +            </row>
   1.964 +            <row>
   1.965 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY_&#8203;NAME</constant></entry>
   1.966 +              <entry><literal>0x18</literal></entry>
   1.967 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
   1.968 +              <entry>name of password policy saved in the header</entry>
   1.969 +            </row>
   1.970 +            <row>
   1.971 +              <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;KEYBOARD_&#8203;SHORTCUT</constant></entry>
   1.972 +              <entry><literal>0x19</literal></entry>
   1.973 +              <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
   1.974 +              <entry>keyboard shortcut</entry>
   1.975 +            </row>
   1.976 +          </tbody>
   1.977 +        </tgroup>
   1.978 +      </table>
   1.979 +      </para>
   1.980 +      <para>The <function>pws3_record_create()</function> function allocates
   1.981 +      and creates a record data structure, generates an UUID record field and
   1.982 +      adds it to the record.</para>
   1.983 +      <para>The <function>pws3_record_destroy()</function> function deallocates
   1.984 +      the given record data structure and all its record fields.</para>
   1.985 +      <para>The <function>pws3_file_record_field_set()</function> function sets
   1.986 +      the record field on the given record, replacing an existing field of the
   1.987 +      same type.</para>
   1.988 +      <para>The <function>pws3_file_record_field_get()</function> function
   1.989 +      returns a pointer to the record field data structure of the given record
   1.990 +      field type.</para>
   1.991 +      <para>The <function>pws3_file_record_field_remove()</function> function
   1.992 +      removes the record field from the given record and returns a pointer to
   1.993 +      it. It is the responsibility of the caller to deallocate the record field
   1.994 +      data structure.</para>
   1.995 +      <para>The <function>pws3_file_insert_record()</function> function inserts
   1.996 +      the given record into the file, an existing record with the same UUID is
   1.997 +      replaced.</para>
   1.998 +      <para>The <function>pws3_file_get_record()</function> function returns a
   1.999 +      pointer to the record structure representing a record with the given
  1.1000 +      UUID.</para>
  1.1001 +      <para>The <function>pws3_file_remove_record()</function> function removes
  1.1002 +      the record with the given UUID from the file and returns a pointer to the
  1.1003 +      record data structure. It is the responsibility of the caller to
  1.1004 +      deallocate the record data structure.</para>
  1.1005 +      <para>The <function>pws3_file_first_record()</function> function returns a
  1.1006 +      pointer to the first record.</para>
  1.1007 +      <para>The <function>pws3_file_last_record()</function> function returns a
  1.1008 +      pointer to the last record.</para>
  1.1009 +      <para>The <function>pws3_file_next_record()</function> function returns a
  1.1010 +      pointer to the next record following the given
  1.1011 +      <parameter>record</parameter>.</para>
  1.1012 +      <para>The <function>pws3_file_prev_record()</function>
  1.1013 +      function returns a pointer to the previous group preceding the given
  1.1014 +      <parameter>record</parameter>.</para>
  1.1015 +    </refsect2>
  1.1016 +    <refsect2>
  1.1017 +      <title>Macros</title>
  1.1018 +      <para>The macro <constant>PWS3_VERSION</constant> contains the supported
  1.1019 +      version of the Password Safe version 3 file format.</para>
  1.1020 +      <para>The macro <constant>PWS3_MAX_FIELD_SIZE</constant> contains the
  1.1021 +      maxium size for header and record fields in bytes and
  1.1022 +      <constant>PWS3_MAX_PASSWORD_LEN</constant> contains the maxium password
  1.1023 +      length in bytes.</para>
  1.1024 +      <para>The macro <constant>PWS3_UUID_SIZE</constant> contains the size of
  1.1025 +      UUIDs in bytes.</para>
  1.1026 +    </refsect2>
  1.1027 +  </refsect1>
  1.1028 +  <refsect1>
  1.1029 +    <title>Return Values</title>
  1.1030 +    <para>The <function>pws3_file_create()</function> function returns a
  1.1031 +    pointer to a Password Safe file data structure if successful and
  1.1032 +    <constant>NULL</constant> in case of an error.</para>
  1.1033 +    <para>The <function>pws3_file_read_mem()</function>,
  1.1034 +    <function>pws3_file_read_stream()</function>,
  1.1035 +    <function>pws3_file_write_mem()</function>, and
  1.1036 +    <function>pws3_file_write_stream()</function> functions return
  1.1037 +    <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
  1.1038 +    to indicate an error.</para>
  1.1039 +    <para>The <function>pws3_file_get_header_field()</function> function
  1.1040 +    returns a pointer to the header field data structure of the requested type
  1.1041 +    and <constant>NULL</constant> if such a field does not exist.</para>
  1.1042 +    <para>The <function>pws3_file_remove_header_field()</function> function
  1.1043 +    returns a pointer to the header field data structure which was removed from
  1.1044 +    the file or <constant>NULL</constant> if such a field does not exist.</para>
  1.1045 +    <para>The <function>pws3_file_get_empty_group()</function> function returns
  1.1046 +    a pointer to the header field data structure corresponding to the requested
  1.1047 +    empty group and <constant>NULL</constant> if a group of that name does not
  1.1048 +    exist.</para>
  1.1049 +    <para>The <function>pws3_file_remove_empty_group()</function> function
  1.1050 +    returns a pointer to the header field data structure of the empty group
  1.1051 +    which was removed from the file or <constant>NULL</constant> if a group of
  1.1052 +    that name does not exist.</para>
  1.1053 +    <para>The <function>pws3_file_first_empty_group()</function> function
  1.1054 +    returns a pointer to the first of the empty group header fields or
  1.1055 +    <constant>NULL</constant> if there are no such fields.</para>
  1.1056 +    <para>The <function>pws3_file_last_empty_group()</function> function
  1.1057 +    returns a pointer to the last of the empty group header fields or
  1.1058 +    <constant>NULL</constant> if there are no such fields.</para>
  1.1059 +    <para>The <function>pws3_file_next_empty_group()</function> function
  1.1060 +    returns a pointer to the next empty group header field or
  1.1061 +    <constant>NULL</constant> if there are no more such fields.</para>
  1.1062 +    <para>The <function>pws3_file_prev_empty_group()</function> function
  1.1063 +    returns a pointer to the previous empty group header field or
  1.1064 +    <constant>NULL</constant> if there are no more such fields.</para>
  1.1065 +    <para>The <function>pws3_file_get_record()</function> function returns a
  1.1066 +    pointer to the record data structure of the requested record or
  1.1067 +    <constant>NULL</constant> if that record does not exist.</para>
  1.1068 +    <para>The <function>pws3_file_remove_record()</function> function returns a
  1.1069 +    pointer to the record data structure which was removed from the file or
  1.1070 +    <constant>NULL</constant> if no such record exists.</para>
  1.1071 +    <para>The <function>pws3_file_first_record()</function> function returns a
  1.1072 +    pointer to the record data structure of the first record or
  1.1073 +    <constant>NULL</constant> if no records exist.</para>
  1.1074 +    <para>The <function>pws3_file_last_record()</function> function returns a
  1.1075 +    pointer to the record data structure of the last record or
  1.1076 +    <constant>NULL</constant> if no records exist.</para>
  1.1077 +    <para>The <function>pws3_file_next_record()</function> function returns a
  1.1078 +    pointer to the record data structure of the next record or
  1.1079 +    <constant>NULL</constant> if no records exist.</para>
  1.1080 +    <para>The <function>pws3_file_prev_record()</function> function returns a
  1.1081 +    pointer to the record data structure of the previous record or
  1.1082 +    <constant>NULL</constant> if no records exist.</para>
  1.1083 +    <para>The <function>pws3_field_create()</function> function returns a
  1.1084 +    pointer to the new header field data structure on success and
  1.1085 +    <constant>NULL</constant> on failure.</para>
  1.1086 +    <para>The <function>pws3_field_get_type()</function> function returns
  1.1087 +    the field type of the header field structure.</para>
  1.1088 +    <para>The <function>pws3_field_get_data_type()</function> function
  1.1089 +    returns the data type of the header field structure.</para>
  1.1090 +    <para>The <function>pws3_field_set_uuid()</function>,
  1.1091 +    <function>pws3_field_set_text()</function>,
  1.1092 +    <function>pws3_field_set_time()</function>,
  1.1093 +    <function>pws3_field_set_uint8()</function>,
  1.1094 +    <function>pws3_field_set_uint16()</function>,
  1.1095 +    <function>pws3_field_set_uint32()</function>, and
  1.1096 +    <function>pws3_field_set_bytes()</function> functions return
  1.1097 +    <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
  1.1098 +    on failure.</para>
  1.1099 +    <para>The <function>pws3_field_get_time()</function>,
  1.1100 +    <function>pws3_field_get_uint8()</function>,
  1.1101 +    <function>pws3_field_get_uint16()</function>, and
  1.1102 +    <function>pws3_field_get_uint32()</function> functions return a
  1.1103 +    value of the type corresponding to the type of header field.</para>
  1.1104 +    <para>The <function>pws3_field_get_uuid()</function> function
  1.1105 +    returns a pointer to a UUID.</para>
  1.1106 +    <para>The <function>pws3_field_get_text()</function> function
  1.1107 +    returns a pointer to a string or <constant>NULL</constant> if no value has
  1.1108 +    been set.</para>
  1.1109 +    <para>The <function>pws3_record_create()</function> function returns a
  1.1110 +    pointer to a record data structure if successful and
  1.1111 +    <constant>NULL</constant> on failure.</para>
  1.1112 +    <para>The <function>pws3_record_get_field()</function> function returns a
  1.1113 +    pointer to the record field data structure of the requested type or
  1.1114 +    <constant>NULL</constant> if such a field does not exist.</para>
  1.1115 +    <para>The <function>pws3_record_remove_field()</function> function returns
  1.1116 +    a pointer to the record field data structure which was removed from the
  1.1117 +    record or <constant>NULL</constant> if such a field does not exist.</para>
  1.1118 +  </refsect1>
  1.1119 +  <refsect1>
  1.1120 +    <title>Errors</title>
  1.1121 +    <para>If the <function>pws3_file_read_mem()</function>,
  1.1122 +    <function>pws3_file_read_stream()</function>,
  1.1123 +    <function>pws3_file_write_mem()</function>, and
  1.1124 +    <function>pws3_file_write_stream()</function> functions fail, an error code
  1.1125 +    indicating the nature of the error may be obtained using the
  1.1126 +    <function>pws3_file_get_error_code()</function> function and a pointer to a
  1.1127 +    detailed error message may be retrieved using the
  1.1128 +    <function>pws3_file_get_error_message()</function> function. The above
  1.1129 +    functions may fail if:</para>
  1.1130 +    <variablelist>
  1.1131 +      <varlistentry>
  1.1132 +        <term><errorname>PWS_ERR_GENERIC_ERROR</errorname></term>
  1.1133 +        <listitem>
  1.1134 +          <para>An unknown error occurred.</para>
  1.1135 +        </listitem>
  1.1136 +      </varlistentry>
  1.1137 +      <varlistentry>
  1.1138 +        <term><errorname>PWS_ERR_NO_MEMORY</errorname></term>
  1.1139 +        <listitem>
  1.1140 +          <para>There was not enough space to allocate memory.</para>
  1.1141 +        </listitem>
  1.1142 +      </varlistentry>
  1.1143 +      <varlistentry>
  1.1144 +        <term><errorname>PWS_ERR_IO_ERROR</errorname></term>
  1.1145 +        <listitem>
  1.1146 +          <para>An I/O error occurred.</para>
  1.1147 +        </listitem>
  1.1148 +      </varlistentry>
  1.1149 +      <varlistentry>
  1.1150 +        <term><errorname>PWS_ERR_TRUNCATED_FILE</errorname></term>
  1.1151 +        <listitem>
  1.1152 +          <para>The file appears to be truncated.</para>
  1.1153 +        </listitem>
  1.1154 +      </varlistentry>
  1.1155 +      <varlistentry>
  1.1156 +        <term><errorname>PWS_ERR_INVALID_CHECKSUM</errorname></term>
  1.1157 +        <listitem>
  1.1158 +          <para>The calculated checksum does not match the checksum of the
  1.1159 +          file.</para>
  1.1160 +        </listitem>
  1.1161 +      </varlistentry>
  1.1162 +      <varlistentry>
  1.1163 +        <term><errorname>PWS_ERR_INVALID_RECORD</errorname></term>
  1.1164 +        <listitem>
  1.1165 +          <para>A record is invalid.</para>
  1.1166 +        </listitem>
  1.1167 +      </varlistentry>
  1.1168 +      <varlistentry>
  1.1169 +        <term><errorname>PWS_ERR_INVALID_HEADER</errorname></term>
  1.1170 +        <listitem>
  1.1171 +          <para>A header is invalid.</para>
  1.1172 +        </listitem>
  1.1173 +      </varlistentry>
  1.1174 +      <varlistentry>
  1.1175 +        <term><errorname>PWS_ERR_UNSUPPORTED_VERSION</errorname></term>
  1.1176 +        <listitem>
  1.1177 +          <para>The file format version is not supported.</para>
  1.1178 +        </listitem>
  1.1179 +      </varlistentry>
  1.1180 +    </variablelist>
  1.1181 +  </refsect1>
  1.1182 +  <refsect1>
  1.1183 +    <title>Examples</title>
  1.1184 +    <example>
  1.1185 +      <title>Creating a Password Safe file</title>
  1.1186 +      <para>The following code creates a new Password Safe file and sets the
  1.1187 +      save application header field:</para>
  1.1188 +      <programlisting>
  1.1189 +<![CDATA[
  1.1190 +#include <pws.h>
  1.1191 +
  1.1192 +/* ... */
  1.1193 +
  1.1194 +struct pws3_file *file;
  1.1195 +struct pws3_field *application_field;
  1.1196 +
  1.1197 +/* ... */
  1.1198 +
  1.1199 +/* initialize libpws */
  1.1200 +if (pws_init() != 0) {
  1.1201 +	/* handle error */
  1.1202 +}
  1.1203 +
  1.1204 +/* ... */
  1.1205 +
  1.1206 +/* create a new empty file structure */
  1.1207 +file = pws3_file_create();
  1.1208 +if (file == NULL) {
  1.1209 +	/* handle error */
  1.1210 +}
  1.1211 +/* create new empty save application field */
  1.1212 +application_field = pws3_field_create(1, PWS3_HEADER_FIELD_SAVE_APPLICATION);
  1.1213 +if (application_field == NULL) {
  1.1214 +	/* handle error */
  1.1215 +}
  1.1216 +/* set the value of the field */
  1.1217 +if (pws3_field_set_text(application_field, "PasswordManager 2.0") != 0) {
  1.1218 +	/* handle error */
  1.1219 +}
  1.1220 +/* set the header save application field in the file to the new field */
  1.1221 +pws3_file_set_field(file, application_field);
  1.1222 +]]>
  1.1223 +</programlisting>
  1.1224 +    </example>
  1.1225 +    <example>
  1.1226 +      <title>Print the title of each record</title>
  1.1227 +      <para>The following code loops over each record of an existing Password
  1.1228 +      Safe file and prints the content of the title field if it exists:</para>
  1.1229 +      <programlisting>
  1.1230 +<![CDATA[
  1.1231 +#include <stdio.h>
  1.1232 +#include <pws.h>
  1.1233 +
  1.1234 +/* ... */
  1.1235 +
  1.1236 +struct pws3_file *file;
  1.1237 +struct pws3_record *record;
  1.1238 +struct pws3_field *title_field;
  1.1239 +
  1.1240 +/* ... */
  1.1241 +
  1.1242 +/* interate over each record */
  1.1243 +for (record = pws3_file_first_record(file); record != NULL;
  1.1244 +    record = pws3_file_next_record(file, record)) {
  1.1245 +	/* retrieve title field */
  1.1246 +	title_field = pws3_record_get_field(record, PWS3_RECORD_FIELD_TITLE);
  1.1247 +	/* print the title field or "No title" if it does not exitst */
  1.1248 +	printf("Title: %s\n", (title_field != NULL) ?
  1.1249 +	    pws3_record_field_get_text(PWS3_RECORD_FIELD_TITLE) : "No title");
  1.1250 +}
  1.1251 +]]>
  1.1252 +</programlisting>
  1.1253 +    </example>
  1.1254 +    <example>
  1.1255 +      <title>Add a new record to a file</title>
  1.1256 +      <para>The following code creates a new record with a password field, a
  1.1257 +      title field, and a creation time field and adds it to an existing
  1.1258 +      Password Safe file:</para>
  1.1259 +      <programlisting>
  1.1260 +<![CDATA[
  1.1261 +#include <time.h>
  1.1262 +#include <pws.h>
  1.1263 +
  1.1264 +/* ... */
  1.1265 +
  1.1266 +struct pws3_file *file;
  1.1267 +struct pws3_record *record;
  1.1268 +struct pws3_field *password_field;
  1.1269 +struct pws3_field *title_field;
  1.1270 +struct pws3_field *ctime_field;
  1.1271 +time_t		now;
  1.1272 +
  1.1273 +/* ... */
  1.1274 +
  1.1275 +/* create new record */
  1.1276 +record = pws3_record_create();
  1.1277 +if (record == NULL) {
  1.1278 +	/* handle error */
  1.1279 +}
  1.1280 +
  1.1281 +/* create a password field */
  1.1282 +password_field = pws3_record_field_create(PWS3_RECORD_FIELD_PASSWORD);
  1.1283 +if (password_field == NULL) {
  1.1284 +	/* handle error */
  1.1285 +}
  1.1286 +/* set the value of the password field to "PaSsWoRd" */
  1.1287 +if (pws3_record_field_set_text(password_field, "PaSsWoRd") != 0) {
  1.1288 +	/* handle error */
  1.1289 +}
  1.1290 +/* set the password field of the record to the new field */
  1.1291 +pws3_record_set_field(record, password_field);
  1.1292 +
  1.1293 +/* create a title field */
  1.1294 +title_field = pws3_record_field_create(PWS3_RECORD_FIELD_TITLE);
  1.1295 +if (title_field == NULL) {
  1.1296 +	/* handle error */
  1.1297 +}
  1.1298 +/* set the value of the title field to "Foo Bar" */
  1.1299 +if (pws3_record_field_set_text(title_field, "Foo Bar") != 0) {
  1.1300 +	/* handle error */
  1.1301 +}
  1.1302 +/* set the title field of the record to the new field */
  1.1303 +pws3_record_set_field(record, title_field);
  1.1304 +
  1.1305 +/* create a new creation time field */
  1.1306 +ctime_field = pws3_record_field_create(PWS3_RECORD_FIELD_CREATION_TIME);
  1.1307 +if (ctime_field == NULL) {
  1.1308 +	/* handle error */
  1.1309 +}
  1.1310 +/* set the value of the creation time field to the current time */
  1.1311 +pws3_record_field_set_time(ctime_field, time(NULL));
  1.1312 +/* set the creation time field of the record to the new field */
  1.1313 +pws3_record_set_field(record, ctime_field);
  1.1314 +
  1.1315 +/* insert the new record into the file */
  1.1316 +pws3_file_insert_record(file, record);
  1.1317 +]]>
  1.1318 +</programlisting>
  1.1319 +    </example>
  1.1320 +    <example>
  1.1321 +      <title>Reading a Password Safe file</title>
  1.1322 +      <para>The following code opens a Password Safe file named
  1.1323 +      <filename>example.pwsafe3</filename> and parses it:</para>
  1.1324 +      <programlisting>
  1.1325 +<![CDATA[
  1.1326 +#include <stdio.h>
  1.1327 +#include <pws.h>
  1.1328 +
  1.1329 +/* ... */
  1.1330 +
  1.1331 +FILE		*fp;
  1.1332 +struct pws3_file *file;
  1.1333 +
  1.1334 +/* ... */
  1.1335 +
  1.1336 +/* initialize libpws */
  1.1337 +if (pws_init() != 0) {
  1.1338 +	/* handle error */
  1.1339 +}
  1.1340 +
  1.1341 +/* ... */
  1.1342 +
  1.1343 +/* create a new empty file structure */
  1.1344 +file = pws3_file_create();
  1.1345 +if (file == NULL) {
  1.1346 +	/* handle error */
  1.1347 +}
  1.1348 +
  1.1349 +/* open the file */
  1.1350 +fp = fopen("example.pwsafe3", "r");
  1.1351 +if (fp == NULL) {
  1.1352 +	/* handle error */
  1.1353 +}
  1.1354 +
  1.1355 +/* read and parse the file contents into the file structure */
  1.1356 +if (pws3_file_read_stream(file, "PaSsWoRd", fp) != 0) {
  1.1357 +	fprintf(stderr, "error: %s\n",
  1.1358 +	   pws3_file_get_error_message(file));
  1.1359 +	/* handle error */
  1.1360 +}
  1.1361 +]]>
  1.1362 +</programlisting>
  1.1363 +    </example>
  1.1364 +    <example>
  1.1365 +      <title>Writing a Password Safe file</title>
  1.1366 +      <para>The following code writes a Password Safe file to a file
  1.1367 +      named <filename>example.pwsafe3</filename>:</para>
  1.1368 +      <programlisting>
  1.1369 +<![CDATA[
  1.1370 +#include <stdio.h>
  1.1371 +#include <pws.h>
  1.1372 +
  1.1373 +/* ... */
  1.1374 +
  1.1375 +FILE		*fp;
  1.1376 +struct pws3_file *file;
  1.1377 +
  1.1378 +/* ... */
  1.1379 +
  1.1380 +fp = fopen("example.pwsafe3", "w");
  1.1381 +if (fp == NULL) {
  1.1382 +	/* handle error */
  1.1383 +}
  1.1384 +
  1.1385 +if (pws3_file_write_stream(file, "FoOBaR", 10000, fp) != 0) {
  1.1386 +	/* handle error */
  1.1387 +}
  1.1388 +
  1.1389 +fflush(fp);
  1.1390 +fclose(fp);
  1.1391 +]]>
  1.1392 +</programlisting>
  1.1393 +    </example>
  1.1394 +  </refsect1>
  1.1395 +  <refsect1>
  1.1396 +    <title>See Also</title>
  1.1397 +    <para><citerefentry><refentrytitle>libpws</refentrytitle>
  1.1398 +    <manvolnum>3</manvolnum></citerefentry>,
  1.1399 +    <citerefentry><refentrytitle>pws_init</refentrytitle>
  1.1400 +    <manvolnum>3</manvolnum></citerefentry>,
  1.1401 +    <link xlink:href="https://pwsafe.org/"/></para>
  1.1402 +  </refsect1>
  1.1403 +</refentry>