projects/libpws

annotate 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
rev   line source
guido+libpws@1 1 <?xml version="1.0"?>
guido+libpws@1 2 <!--
guido+libpws@1 3
guido+libpws@1 4 Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
guido+libpws@1 5
guido+libpws@1 6 Permission is hereby granted, free of charge, to any person obtaining
guido+libpws@1 7 a copy of this software and associated documentation files (the
guido+libpws@1 8 "Software"), to deal in the Software without restriction, including
guido+libpws@1 9 without limitation the rights to use, copy, modify, merge, publish,
guido+libpws@1 10 distribute, sublicense, and/or sell copies of the Software, and to
guido+libpws@1 11 permit persons to whom the Software is furnished to do so, subject to
guido+libpws@1 12 the following conditions:
guido+libpws@1 13
guido+libpws@1 14 The above copyright notice and this permission notice shall be included
guido+libpws@1 15 in all copies or substantial portions of the Software.
guido+libpws@1 16
guido+libpws@1 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
guido+libpws@1 18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
guido+libpws@1 19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
guido+libpws@1 20 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
guido+libpws@1 21 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
guido+libpws@1 22 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
guido+libpws@1 23 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
guido+libpws@1 24
guido+libpws@1 25 -->
guido+libpws@1 26 <refentry xmlns="http://docbook.org/ns/docbook"
guido+libpws@1 27 xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
guido+libpws@1 28 <info>
guido+libpws@1 29 <author>
guido+libpws@1 30 <personname>
guido+libpws@1 31 <firstname>Guido</firstname>
guido+libpws@1 32 <surname>Berhoerster</surname>
guido+libpws@1 33 </personname>
guido+libpws@1 34 <email>guido+libpws@berhoerster.name</email>
guido+libpws@1 35 <personblurb/>
guido+libpws@1 36 </author>
guido+libpws@1 37 <date>21 March, 2015</date>
guido+libpws@1 38 </info>
guido+libpws@1 39 <refmeta>
guido+libpws@1 40 <refentrytitle>libpws</refentrytitle>
guido+libpws@1 41 <manvolnum>3</manvolnum>
guido+libpws@1 42 <refmiscinfo class="source"/>
guido+libpws@1 43 <refmiscinfo class="version"/>
guido+libpws@1 44 <refmiscinfo class="manual">Library Functions</refmiscinfo>
guido+libpws@1 45 </refmeta>
guido+libpws@1 46 <refnamediv>
guido+libpws@1 47 <refname>pws3_file_create</refname>
guido+libpws@1 48 <refname>pws3_file_destroy</refname>
guido+libpws@1 49 <refname>pws3_file_get_error_code</refname>
guido+libpws@1 50 <refname>pws3_file_get_error_message</refname>
guido+libpws@1 51 <refname>pws3_file_read_mem</refname>
guido+libpws@1 52 <refname>pws3_file_read_stream</refname>
guido+libpws@1 53 <refname>pws3_file_write_mem</refname>
guido+libpws@1 54 <refname>pws3_file_write_stream</refname>
guido+libpws@1 55 <refname>pws3_file_set_header_field</refname>
guido+libpws@1 56 <refname>pws3_file_get_header_field</refname>
guido+libpws@1 57 <refname>pws3_file_remove_header_field</refname>
guido+libpws@1 58 <refname>pws3_file_insert_empty_group</refname>
guido+libpws@1 59 <refname>pws3_file_get_empty_group</refname>
guido+libpws@1 60 <refname>pws3_file_remove_empty_group</refname>
guido+libpws@1 61 <refname>pws3_file_first_empty_group</refname>
guido+libpws@1 62 <refname>pws3_file_last_empty_group</refname>
guido+libpws@1 63 <refname>pws3_file_next_empty_group</refname>
guido+libpws@1 64 <refname>pws3_file_prev_empty_group</refname>
guido+libpws@1 65 <refname>pws3_file_insert_record</refname>
guido+libpws@1 66 <refname>pws3_file_get_record</refname>
guido+libpws@1 67 <refname>pws3_file_remove_record</refname>
guido+libpws@1 68 <refname>pws3_file_first_record</refname>
guido+libpws@1 69 <refname>pws3_file_last_record</refname>
guido+libpws@1 70 <refname>pws3_file_next_record</refname>
guido+libpws@1 71 <refname>pws3_file_prev_record</refname>
guido+libpws@1 72 <refname>pws3_field_create</refname>
guido+libpws@1 73 <refname>pws3_field_destroy</refname>
guido+libpws@1 74 <refname>pws3_field_is_header</refname>
guido+libpws@1 75 <refname>pws3_field_get_type</refname>
guido+libpws@1 76 <refname>pws3_field_get_data_type</refname>
guido+libpws@1 77 <refname>pws3_field_set_uuid</refname>
guido+libpws@1 78 <refname>pws3_field_set_text</refname>
guido+libpws@1 79 <refname>pws3_field_set_time</refname>
guido+libpws@1 80 <refname>pws3_field_set_uint8</refname>
guido+libpws@1 81 <refname>pws3_field_set_uint16</refname>
guido+libpws@1 82 <refname>pws3_field_set_uint32</refname>
guido+libpws@1 83 <refname>pws3_field_set_bytes</refname>
guido+libpws@1 84 <refname>pws3_field_get_uuid</refname>
guido+libpws@1 85 <refname>pws3_field_get_text</refname>
guido+libpws@1 86 <refname>pws3_field_get_time</refname>
guido+libpws@1 87 <refname>pws3_field_get_uint8</refname>
guido+libpws@1 88 <refname>pws3_field_get_uint16</refname>
guido+libpws@1 89 <refname>pws3_field_get_uint32</refname>
guido+libpws@1 90 <refname>pws3_field_get_bytes</refname>
guido+libpws@1 91 <refname>pws3_record_create</refname>
guido+libpws@1 92 <refname>pws3_record_destroy</refname>
guido+libpws@1 93 <refname>pws3_record_set_field</refname>
guido+libpws@1 94 <refname>pws3_record_get_field</refname>
guido+libpws@1 95 <refname>pws3_record_remove_field</refname>
guido+libpws@1 96 <refpurpose>create and manipulate Password Safe File Version 3
guido+libpws@1 97 files</refpurpose>
guido+libpws@1 98 </refnamediv>
guido+libpws@1 99 <refsynopsisdiv>
guido+libpws@1 100 <cmdsynopsis>
guido+libpws@1 101 <command>cc</command>
guido+libpws@1 102 <arg choice="opt" rep="repeat">
guido+libpws@1 103 <option>flag</option>
guido+libpws@1 104 </arg>
guido+libpws@1 105 <arg choice="plain" rep="repeat">
guido+libpws@1 106 <option>file</option>
guido+libpws@1 107 </arg>
guido+libpws@1 108 <arg choice="plain">
guido+libpws@1 109 <option>-lpws</option>
guido+libpws@1 110 </arg>
guido+libpws@1 111 <arg choice="plain">
guido+libpws@1 112 <option>-lnettle</option>
guido+libpws@1 113 </arg>
guido+libpws@1 114 <arg choice="opt" rep="repeat">
guido+libpws@1 115 <option>library</option>
guido+libpws@1 116 </arg>
guido+libpws@1 117 </cmdsynopsis>
guido+libpws@1 118 <funcsynopsis>
guido+libpws@1 119 <funcsynopsisinfo>
guido+libpws@1 120 #include &lt;pws.h&gt;
guido+libpws@1 121 </funcsynopsisinfo>
guido+libpws@1 122 <funcprototype>
guido+libpws@1 123 <funcdef>struct pws3_file
guido+libpws@1 124 *<function>pws3_file_create</function></funcdef>
guido+libpws@1 125 <void/>
guido+libpws@1 126 </funcprototype>
guido+libpws@1 127 <funcprototype>
guido+libpws@1 128 <funcdef>void <function>pws3_file_destroy</function></funcdef>
guido+libpws@1 129 <paramdef>struct pws3_file
guido+libpws@1 130 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 131 </funcprototype>
guido+libpws@1 132 <funcprototype>
guido+libpws@1 133 <funcdef>enum pws_error_code
guido+libpws@1 134 <function>pws3_file_get_error_code</function></funcdef>
guido+libpws@1 135 <paramdef>struct pws3_file
guido+libpws@1 136 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 137 </funcprototype>
guido+libpws@1 138 <funcprototype>
guido+libpws@1 139 <funcdef>const char *
guido+libpws@1 140 <function>pws3_file_get_error_message</function></funcdef>
guido+libpws@1 141 <paramdef>struct pws3_file
guido+libpws@1 142 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 143 </funcprototype>
guido+libpws@1 144 <funcprototype>
guido+libpws@1 145 <funcdef>int <function>pws3_file_read_mem</function></funcdef>
guido+libpws@1 146 <paramdef>struct pws3_file
guido+libpws@1 147 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 148 <paramdef>const char
guido+libpws@1 149 *<parameter><replaceable>password</replaceable></parameter></paramdef>
guido+libpws@1 150 <paramdef>unsigned char
guido+libpws@1 151 *<parameter><replaceable>s</replaceable></parameter></paramdef>
guido+libpws@1 152 <paramdef>size_t
guido+libpws@1 153 <parameter><replaceable>n</replaceable></parameter></paramdef>
guido+libpws@1 154 </funcprototype>
guido+libpws@1 155 <funcprototype>
guido+libpws@1 156 <funcdef>int <function>pws3_file_read_stream</function></funcdef>
guido+libpws@1 157 <paramdef>struct pws3_file
guido+libpws@1 158 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 159 <paramdef>const char
guido+libpws@1 160 *<parameter><replaceable>password</replaceable></parameter></paramdef>
guido+libpws@1 161 <paramdef>FILE
guido+libpws@1 162 *<parameter><replaceable>fp</replaceable></parameter></paramdef>
guido+libpws@1 163 </funcprototype>
guido+libpws@1 164 <funcprototype>
guido+libpws@1 165 <funcdef>int <function>pws3_file_write_mem</function></funcdef>
guido+libpws@1 166 <paramdef>struct pws3_file
guido+libpws@1 167 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 168 <paramdef>const char
guido+libpws@1 169 *<parameter><replaceable>password</replaceable></parameter></paramdef>
guido+libpws@1 170 <paramdef>uint32_t
guido+libpws@1 171 <parameter><replaceable>n_iter</replaceable></parameter></paramdef>
guido+libpws@1 172 <paramdef>unsigned char
guido+libpws@1 173 **<parameter><replaceable>memp</replaceable></parameter></paramdef>
guido+libpws@1 174 <paramdef>size_t
guido+libpws@1 175 *<parameter><replaceable>mem_sizep</replaceable></parameter></paramdef>
guido+libpws@1 176 </funcprototype>
guido+libpws@1 177 <funcprototype>
guido+libpws@1 178 <funcdef>int <function>pws3_file_write_stream</function></funcdef>
guido+libpws@1 179 <paramdef>struct pws3_file
guido+libpws@1 180 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 181 <paramdef>const char
guido+libpws@1 182 *<parameter><replaceable>password</replaceable></parameter></paramdef>
guido+libpws@1 183 <paramdef>uint32_t
guido+libpws@1 184 <parameter><replaceable>n_iter</replaceable></parameter></paramdef>
guido+libpws@1 185 </funcprototype>
guido+libpws@1 186 <funcprototype>
guido+libpws@1 187 <funcdef>void <function>pws3_file_set_header_field</function></funcdef>
guido+libpws@1 188 <paramdef>struct pws3_file
guido+libpws@1 189 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 190 <paramdef>struct pws3_field
guido+libpws@1 191 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 192 </funcprototype>
guido+libpws@1 193 <funcprototype>
guido+libpws@1 194 <funcdef>struct pws3_field *
guido+libpws@1 195 <function>pws3_file_get_header_field</function></funcdef>
guido+libpws@1 196 <paramdef>struct pws3_file
guido+libpws@1 197 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 198 <paramdef>uint8_t
guido+libpws@1 199 <parameter><replaceable>field_type</replaceable></parameter></paramdef>
guido+libpws@1 200 </funcprototype>
guido+libpws@1 201 <funcprototype>
guido+libpws@1 202 <funcdef>struct pws3_field *
guido+libpws@1 203 <function>pws3_file_remove_header_field</function></funcdef>
guido+libpws@1 204 <paramdef>struct pws3_file
guido+libpws@1 205 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 206 <paramdef>uint8_t
guido+libpws@1 207 <parameter><replaceable>field_type</replaceable></parameter></paramdef>
guido+libpws@1 208 </funcprototype>
guido+libpws@1 209 <funcprototype>
guido+libpws@1 210 <funcdef>void
guido+libpws@1 211 <function>pws3_file_insert_empty_group</function></funcdef>
guido+libpws@1 212 <paramdef>struct pws3_file
guido+libpws@1 213 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 214 <paramdef>struct pws3_field
guido+libpws@1 215 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 216 </funcprototype>
guido+libpws@1 217 <funcprototype>
guido+libpws@1 218 <funcdef>struct pws3_field *
guido+libpws@1 219 <function>pws3_file_get_empty_group</function></funcdef>
guido+libpws@1 220 <paramdef>struct pws3_file
guido+libpws@1 221 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 222 <paramdef>const char
guido+libpws@1 223 *<parameter><replaceable>group_name</replaceable></parameter></paramdef>
guido+libpws@1 224 </funcprototype>
guido+libpws@1 225 <funcprototype>
guido+libpws@1 226 <funcdef>struct pws3_field *
guido+libpws@1 227 <function>pws3_file_remove_empty_group</function></funcdef>
guido+libpws@1 228 <paramdef>struct pws3_file
guido+libpws@1 229 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 230 <paramdef>const char
guido+libpws@1 231 *<parameter><replaceable>group_name</replaceable></parameter></paramdef>
guido+libpws@1 232 </funcprototype>
guido+libpws@1 233 <funcprototype>
guido+libpws@1 234 <funcdef>struct pws3_field *
guido+libpws@1 235 <function>pws3_file_first_empty_group</function></funcdef>
guido+libpws@1 236 <paramdef>struct pws3_file
guido+libpws@1 237 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 238 </funcprototype>
guido+libpws@1 239 <funcprototype>
guido+libpws@1 240 <funcdef>struct pws3_field *
guido+libpws@1 241 <function>pws3_file_last_empty_group</function></funcdef>
guido+libpws@1 242 <paramdef>struct pws3_file
guido+libpws@1 243 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 244 </funcprototype>
guido+libpws@1 245 <funcprototype>
guido+libpws@1 246 <funcdef>struct pws3_field *
guido+libpws@1 247 <function>pws3_file_next_empty_group</function></funcdef>
guido+libpws@1 248 <paramdef>struct pws3_file
guido+libpws@1 249 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 250 <paramdef>struct pws3_field
guido+libpws@1 251 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 252 </funcprototype>
guido+libpws@1 253 <funcprototype>
guido+libpws@1 254 <funcdef>struct pws3_field *
guido+libpws@1 255 <function>pws3_file_prev_empty_group</function></funcdef>
guido+libpws@1 256 <paramdef>struct pws3_file
guido+libpws@1 257 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 258 <paramdef>struct pws3_field
guido+libpws@1 259 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 260 </funcprototype>
guido+libpws@1 261 <funcprototype>
guido+libpws@1 262 <funcdef>void <function>pws3_file_insert_record</function></funcdef>
guido+libpws@1 263 <paramdef>struct pws3_file
guido+libpws@1 264 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 265 <paramdef>struct pws3_record
guido+libpws@1 266 *<parameter><replaceable>record</replaceable></parameter></paramdef>
guido+libpws@1 267 </funcprototype>
guido+libpws@1 268 <funcprototype>
guido+libpws@1 269 <funcdef>struct pws3_record *
guido+libpws@1 270 <function>pws3_file_get_record</function></funcdef>
guido+libpws@1 271 <paramdef>struct pws3_file
guido+libpws@1 272 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 273 <paramdef>const unsigned char
guido+libpws@1 274 <parameter><replaceable>uuid</replaceable>[static
guido+libpws@1 275 PWS3_UUID_SIZE]</parameter></paramdef>
guido+libpws@1 276 </funcprototype>
guido+libpws@1 277 <funcprototype>
guido+libpws@1 278 <funcdef>struct pws3_record *
guido+libpws@1 279 <function>pws3_file_remove_record</function></funcdef>
guido+libpws@1 280 <paramdef>struct pws3_file
guido+libpws@1 281 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 282 <paramdef>const unsigned char
guido+libpws@1 283 <parameter><replaceable>uuid</replaceable>[static
guido+libpws@1 284 PWS3_UUID_SIZE]</parameter></paramdef>
guido+libpws@1 285 </funcprototype>
guido+libpws@1 286 <funcprototype>
guido+libpws@1 287 <funcdef>struct pws3_record *
guido+libpws@1 288 <function>pws3_file_first_record</function></funcdef>
guido+libpws@1 289 <paramdef>struct pws3_file
guido+libpws@1 290 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 291 </funcprototype>
guido+libpws@1 292 <funcprototype>
guido+libpws@1 293 <funcdef>struct pws3_record *
guido+libpws@1 294 <function>pws3_file_last_record</function></funcdef>
guido+libpws@1 295 <paramdef>struct pws3_file
guido+libpws@1 296 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 297 </funcprototype>
guido+libpws@1 298 <funcprototype>
guido+libpws@1 299 <funcdef>struct pws3_record *
guido+libpws@1 300 <function>pws3_file_next_record</function></funcdef>
guido+libpws@1 301 <paramdef>struct pws3_file
guido+libpws@1 302 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 303 <paramdef>struct pws3_record
guido+libpws@1 304 *<parameter><replaceable>record</replaceable></parameter></paramdef>
guido+libpws@1 305 </funcprototype>
guido+libpws@1 306 <funcprototype>
guido+libpws@1 307 <funcdef>struct pws3_record *
guido+libpws@1 308 <function>pws3_file_prev_record</function></funcdef>
guido+libpws@1 309 <paramdef>struct pws3_file
guido+libpws@1 310 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
guido+libpws@1 311 <paramdef>struct pws3_record
guido+libpws@1 312 *<parameter><replaceable>record</replaceable></parameter></paramdef>
guido+libpws@1 313 </funcprototype>
guido+libpws@1 314 <funcprototype>
guido+libpws@1 315 <funcdef>struct pws3_field *
guido+libpws@1 316 <function>pws3_field_create</function></funcdef>
guido+libpws@1 317 <paramdef>int
guido+libpws@1 318 <parameter><replaceable>is_header</replaceable></parameter></paramdef>
guido+libpws@1 319 <paramdef>uint8_t
guido+libpws@1 320 <parameter><replaceable>field_type</replaceable></parameter></paramdef>
guido+libpws@1 321 </funcprototype>
guido+libpws@1 322 <funcprototype>
guido+libpws@1 323 <funcdef>void <function>pws3_field_destroy</function></funcdef>
guido+libpws@1 324 <paramdef>struct pws3_field
guido+libpws@1 325 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 326 </funcprototype>
guido+libpws@1 327 <funcprototype>
guido+libpws@1 328 <funcdef>int
guido+libpws@1 329 <function>pws3_field_is_header</function></funcdef>
guido+libpws@1 330 <paramdef>struct pws3_field
guido+libpws@1 331 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 332 </funcprototype>
guido+libpws@1 333 <funcprototype>
guido+libpws@1 334 <funcdef>uint8_t *
guido+libpws@1 335 <function>pws3_field_get_type</function></funcdef>
guido+libpws@1 336 <paramdef>struct pws3_field
guido+libpws@1 337 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 338 </funcprototype>
guido+libpws@1 339 <funcprototype>
guido+libpws@1 340 <funcdef>enum pws_data_type *
guido+libpws@1 341 <function>pws3_field_get_data_type</function></funcdef>
guido+libpws@1 342 <paramdef>struct pws3_field
guido+libpws@1 343 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 344 </funcprototype>
guido+libpws@1 345 <funcprototype>
guido+libpws@1 346 <funcdef>int <function>pws3_field_set_uuid</function></funcdef>
guido+libpws@1 347 <paramdef>struct pws3_field
guido+libpws@1 348 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 349 <paramdef>const unsigned char
guido+libpws@1 350 <parameter><replaceable>uuid</replaceable>[static
guido+libpws@1 351 PWS3_UUID_SIZE]</parameter></paramdef>
guido+libpws@1 352 </funcprototype>
guido+libpws@1 353 <funcprototype>
guido+libpws@1 354 <funcdef>int <function>pws3_field_set_text</function></funcdef>
guido+libpws@1 355 <paramdef>struct pws3_field
guido+libpws@1 356 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 357 <paramdef>const char
guido+libpws@1 358 <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef>
guido+libpws@1 359 </funcprototype>
guido+libpws@1 360 <funcprototype>
guido+libpws@1 361 <funcdef>int <function>pws3_field_set_time</function></funcdef>
guido+libpws@1 362 <paramdef>struct pws3_field
guido+libpws@1 363 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 364 <paramdef>time_t
guido+libpws@1 365 <parameter><replaceable>time</replaceable></parameter></paramdef>
guido+libpws@1 366 </funcprototype>
guido+libpws@1 367 <funcprototype>
guido+libpws@1 368 <funcdef>int <function>pws3_field_set_uint8</function></funcdef>
guido+libpws@1 369 <paramdef>struct pws3_field
guido+libpws@1 370 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 371 <paramdef>uint8_t
guido+libpws@1 372 <parameter><replaceable>u8</replaceable></parameter></paramdef>
guido+libpws@1 373 </funcprototype>
guido+libpws@1 374 <funcprototype>
guido+libpws@1 375 <funcdef>int <function>pws3_field_set_uint16</function></funcdef>
guido+libpws@1 376 <paramdef>struct pws3_field
guido+libpws@1 377 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 378 <paramdef>uint16_t
guido+libpws@1 379 <parameter><replaceable>u16</replaceable></parameter></paramdef>
guido+libpws@1 380 </funcprototype>
guido+libpws@1 381 <funcprototype>
guido+libpws@1 382 <funcdef>int <function>pws3_field_set_uint32</function></funcdef>
guido+libpws@1 383 <paramdef>struct pws3_field
guido+libpws@1 384 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 385 <paramdef>uint32_t
guido+libpws@1 386 <parameter><replaceable>u32</replaceable></parameter></paramdef>
guido+libpws@1 387 </funcprototype>
guido+libpws@1 388 <funcprototype>
guido+libpws@1 389 <funcdef>int <function>pws3_field_set_bytes</function></funcdef>
guido+libpws@1 390 <paramdef>struct pws3_field
guido+libpws@1 391 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 392 <paramdef>const unsigned char
guido+libpws@1 393 <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef>
guido+libpws@1 394 <paramdef>size_t
guido+libpws@1 395 <parameter><replaceable>n</replaceable></parameter></paramdef>
guido+libpws@1 396 </funcprototype>
guido+libpws@1 397 <funcprototype>
guido+libpws@1 398 <funcdef>const unsigned char *
guido+libpws@1 399 <function>pws3_field_get_uuid</function></funcdef>
guido+libpws@1 400 <paramdef>struct pws3_field
guido+libpws@1 401 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 402 </funcprototype>
guido+libpws@1 403 <funcprototype>
guido+libpws@1 404 <funcdef>const char *
guido+libpws@1 405 <function>pws3_field_get_text</function></funcdef>
guido+libpws@1 406 <paramdef>struct pws3_field
guido+libpws@1 407 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 408 </funcprototype>
guido+libpws@1 409 <funcprototype>
guido+libpws@1 410 <funcdef>time_t
guido+libpws@1 411 <function>pws3_field_get_time</function></funcdef>
guido+libpws@1 412 <paramdef>struct pws3_field
guido+libpws@1 413 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 414 </funcprototype>
guido+libpws@1 415 <funcprototype>
guido+libpws@1 416 <funcdef>uint8_t
guido+libpws@1 417 <function>pws3_field_get_uint8</function></funcdef>
guido+libpws@1 418 <paramdef>struct pws3_field
guido+libpws@1 419 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 420 </funcprototype>
guido+libpws@1 421 <funcprototype>
guido+libpws@1 422 <funcdef>uint16_t
guido+libpws@1 423 <function>pws3_field_get_uint16</function></funcdef>
guido+libpws@1 424 <paramdef>struct pws3_field
guido+libpws@1 425 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 426 </funcprototype>
guido+libpws@1 427 <funcprototype>
guido+libpws@1 428 <funcdef>uint32_t
guido+libpws@1 429 <function>pws3_field_get_uint32</function></funcdef>
guido+libpws@1 430 <paramdef>struct pws3_field
guido+libpws@1 431 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 432 </funcprototype>
guido+libpws@1 433 <funcprototype>
guido+libpws@1 434 <funcdef>void <function>pws3_field_get_bytes</function></funcdef>
guido+libpws@1 435 <paramdef>struct pws3_field
guido+libpws@1 436 *<parameter><replaceable>field</replaceable></parameter></paramdef>
guido+libpws@1 437 <paramdef>const unsigned char
guido+libpws@1 438 **<parameter><replaceable>pp</replaceable></parameter></paramdef>
guido+libpws@1 439 <paramdef>size_t
guido+libpws@1 440 *<parameter><replaceable>np</replaceable></parameter></paramdef>
guido+libpws@1 441 </funcprototype>
guido+libpws@1 442 </funcsynopsis>
guido+libpws@1 443 <synopsis>
guido+libpws@1 444 <constant>PWS3_VERSION</constant>
guido+libpws@1 445
guido+libpws@1 446 <constant>PWS3_MAX_FIELD_LEN</constant>
guido+libpws@1 447
guido+libpws@1 448 <constant>PWS3_MAX_PASSWORD_LEN</constant>
guido+libpws@1 449
guido+libpws@1 450 <constant>PWS3_UUID_SIZE</constant>
guido+libpws@1 451
guido+libpws@1 452 struct pws3_field;
guido+libpws@1 453
guido+libpws@1 454 struct pws3_record;
guido+libpws@1 455
guido+libpws@1 456 struct pws3_file;
guido+libpws@1 457
guido+libpws@1 458 enum pws_error_code;
guido+libpws@1 459
guido+libpws@1 460 enum pws_data_type;
guido+libpws@1 461
guido+libpws@1 462 enum pws3_header_field_type;
guido+libpws@1 463
guido+libpws@1 464 enum pws3_record_field_type;
guido+libpws@1 465 </synopsis>
guido+libpws@1 466 </refsynopsisdiv>
guido+libpws@1 467 <refsect1>
guido+libpws@1 468 <title>Description</title>
guido+libpws@1 469 <refsect2>
guido+libpws@1 470 <title>Introduction</title>
guido+libpws@1 471 <para>The <function>pws3_*()</function> family of functions allows
guido+libpws@1 472 creating, reading, writing, and manipulating Password Safe version 3
guido+libpws@1 473 files. Password Safe version 3 files consist of a header and a body part.
guido+libpws@1 474 The header is comprised of both mandatory and optional typed header
guido+libpws@1 475 fields which hold file-wide metadata. The body consists of records which
guido+libpws@1 476 in turn hold passwords and associated metadata in typed record
guido+libpws@1 477 fields.</para>
guido+libpws@1 478 <para>A header or record field value can be of one of seven basic data
guido+libpws@1 479 types defined below:
guido+libpws@1 480 <table xml:id="table-data-types">
guido+libpws@1 481 <title>Header and Record Field Value Data Types</title>
guido+libpws@1 482 <tgroup cols="3" align="left" colsep="1" rowsep="1">
guido+libpws@1 483 <thead>
guido+libpws@1 484 <row>
guido+libpws@1 485 <entry>Data Type</entry>
guido+libpws@1 486 <entry>C Type</entry>
guido+libpws@1 487 <entry>Description</entry>
guido+libpws@1 488 </row>
guido+libpws@1 489 </thead>
guido+libpws@1 490 <tbody>
guido+libpws@1 491 <row>
guido+libpws@1 492 <entry><constant>PWS_DATA_TYPE_UUID</constant></entry>
guido+libpws@1 493 <entry><code>unsigned char [PWS3_UUID_SIZE]</code></entry>
guido+libpws@1 494 <entry>UUID</entry>
guido+libpws@1 495 </row>
guido+libpws@1 496 <row>
guido+libpws@1 497 <entry><constant>PWS_DATA_TYPE_TEXT</constant></entry>
guido+libpws@1 498 <entry><code>char *</code></entry>
guido+libpws@1 499 <entry>NUL-delimited UTF-8 encoded string</entry>
guido+libpws@1 500 </row>
guido+libpws@1 501 <row>
guido+libpws@1 502 <entry><constant>PWS_DATA_TYPE_TIME</constant></entry>
guido+libpws@1 503 <entry><code>time_t</code></entry>
guido+libpws@1 504 <entry>system-specific representation of time</entry>
guido+libpws@1 505 </row>
guido+libpws@1 506 <row>
guido+libpws@1 507 <entry><constant>PWS_DATA_TYPE_UINT8</constant></entry>
guido+libpws@1 508 <entry><code>uint8_t</code></entry>
guido+libpws@1 509 <entry>8-bit wide unsigned integer</entry>
guido+libpws@1 510 </row>
guido+libpws@1 511 <row>
guido+libpws@1 512 <entry><constant>PWS_DATA_TYPE_UINT16</constant></entry>
guido+libpws@1 513 <entry><code>uint16_t</code></entry>
guido+libpws@1 514 <entry>16-bit wide unsigned integer</entry>
guido+libpws@1 515 </row>
guido+libpws@1 516 <row>
guido+libpws@1 517 <entry><constant>PWS_DATA_TYPE_UINT32</constant></entry>
guido+libpws@1 518 <entry><code>uint32_t</code></entry>
guido+libpws@1 519 <entry>32-bit wide unsigned integer</entry>
guido+libpws@1 520 </row>
guido+libpws@1 521 <row>
guido+libpws@1 522 <entry><constant>PWS_DATA_TYPE_BYTES</constant></entry>
guido+libpws@1 523 <entry><code>unsigned char *</code></entry>
guido+libpws@1 524 <entry>array of bytes</entry>
guido+libpws@1 525 </row>
guido+libpws@1 526 </tbody>
guido+libpws@1 527 </tgroup>
guido+libpws@1 528 </table>
guido+libpws@1 529 </para>
guido+libpws@1 530 <para>The data type of each header field is defined in
guido+libpws@1 531 <xref linkend="table-header-fields"/> and the data type of each record
guido+libpws@1 532 field is defined in <xref linkend="table-record-fields"/>. Each header
guido+libpws@1 533 field, with the exception of the empty groups header field, can only
guido+libpws@1 534 occur once. The version header field
guido+libpws@1 535 (<constant>PWS3_HEADER_FIELD_VERSION</constant>) is mandatory and must
guido+libpws@1 536 not be removed. When reading a file its value is checked and an error is
guido+libpws@1 537 returned if the file format version newer than the one supported by
guido+libpws@1 538 <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
guido+libpws@1 539 The supported version is defined by the <constant>PWS3_VERSION</constant>
guido+libpws@1 540 macro, when creating a new file structure the version header field will be
guido+libpws@1 541 set to its value by default. Non-standard header and record fields will
guido+libpws@1 542 be preserved when a file is read and subsequently written again, they may
guido+libpws@1 543 be read and manipulated as if they had
guido+libpws@1 544 <constant>PWS_DATA_TYPE_BYTES</constant> data type. All strings are
guido+libpws@1 545 expected to be in UTF-8 encoding.</para>
guido+libpws@1 546 <para>The only mandatory record field is the UUID field which uniquely
guido+libpws@1 547 identifies a record in the file.</para>
guido+libpws@1 548 <para>The complete and authoritative specification of the file format is
guido+libpws@1 549 included with the original Password Safe application available from <link
guido+libpws@1 550 xlink:href="https://pwsafe.org/"/>.</para>
guido+libpws@1 551 </refsect2>
guido+libpws@1 552 <refsect2>
guido+libpws@1 553 <title>Password Safe File Data Structure</title>
guido+libpws@1 554 <para>The <function>pws3_file_create()</function> function allocates and
guido+libpws@1 555 intializes a Password Safe file data structure representing a Password
guido+libpws@1 556 Safe version 3 file. It automatically creates the mandatory version header
guido+libpws@1 557 field and initializes it to the value of the
guido+libpws@1 558 <constant>PWS3_VERSION</constant> macro.</para>
guido+libpws@1 559 <para>The <function>pws3_file_destroy()</function> function deallocates
guido+libpws@1 560 all header fields and records of the file structure passed to it and then
guido+libpws@1 561 deallocates the file structure itself.</para>
guido+libpws@1 562 <para>The <function>pws3_file_read_mem()</function> and
guido+libpws@1 563 <function>pws3_file_read_stream()</function> functions read and parse a
guido+libpws@1 564 Password Safe file into the given data structure passed via the
guido+libpws@1 565 <parameter>pws_file</parameter> argument, replacing any existing header
guido+libpws@1 566 fields and records. The key used to decrypt the file is derived from the
guido+libpws@1 567 given <parameter>password</parameter> parameter. The
guido+libpws@1 568 <function>pws3_file_read_mem()</function> function reads the file from a
guido+libpws@1 569 block of memory <parameter>s</parameter> with the size of
guido+libpws@1 570 <parameter>n</parameter> bytes. The
guido+libpws@1 571 <function>pws3_file_read_stream()</function> reads the file from the
guido+libpws@1 572 stream of the <parameter>fp</parameter> file pointer.</para>
guido+libpws@1 573 <para>The <function>pws3_file_write_mem()</function> and
guido+libpws@1 574 <function>pws3_file_write_stream()</function> functions write a new
guido+libpws@1 575 Password Safe file from the given datat structure. The key used to
guido+libpws@1 576 encrypt the file is derived from the <parameter>password</parameter>
guido+libpws@1 577 argument using the number of iterations to stretch the key determined by
guido+libpws@1 578 the <parameter>n_iter</parameter> argument. The
guido+libpws@1 579 <function>pws3_file_write_mem()</function> will allocate and place the
guido+libpws@1 580 file contents into memory and return the location and size to the
guido+libpws@1 581 locations <parameter>sp</parameter> and <parameter>np</parameter>
guido+libpws@1 582 point to. The <function>pws3_file_write_stream()</function> will write the
guido+libpws@1 583 file contents to the stream of the <parameter>fp</parameter> file
guido+libpws@1 584 pointer.</para>
guido+libpws@1 585 </refsect2>
guido+libpws@1 586 <refsect2>
guido+libpws@1 587 <title>Fields</title>
guido+libpws@1 588 <para>Both header and record fields are stored in
guido+libpws@1 589 <varname>pws3_field</varname> structures which are allocated and
guido+libpws@1 590 initialized with the <function>pws3_field_create()</function> function.
guido+libpws@1 591 Depending on whether <parameter>is_header</parameter> is non-zero either
guido+libpws@1 592 a header field or a record field data structure of the given field type
guido+libpws@1 593 will be created.</para>
guido+libpws@1 594 <para>The <function>pws3_field_destroy()</function> function
guido+libpws@1 595 deallocates the given field data structure and its content.</para>
guido+libpws@1 596 <para>The <function>pws3_field_is_header()</function> function
guido+libpws@1 597 can be used to test whether the given field data structure refers to a
guido+libpws@1 598 header field or a record field.</para>
guido+libpws@1 599 <para>The <function>pws3_field_get_type()</function> function
guido+libpws@1 600 returns the field type of the given field data structure.</para>
guido+libpws@1 601 <para>The <function>pws3_field_get_data_type()</function> function
guido+libpws@1 602 returns the data type of the given field structure.</para>
guido+libpws@1 603 <para>The <function>pws3_field_set_uuid()</function>,
guido+libpws@1 604 <function>pws3_field_set_text()</function>,
guido+libpws@1 605 <function>pws3_field_set_time()</function>,
guido+libpws@1 606 <function>pws3_field_set_uint8()</function>,
guido+libpws@1 607 <function>pws3_field_set_uint16()</function>,
guido+libpws@1 608 <function>pws3_field_set_uint32()</function>, and
guido+libpws@1 609 <function>pws3_field_set_bytes()</function> functions set the
guido+libpws@1 610 content of the given field. The given data is always copied and
guido+libpws@1 611 existing content is replaced. The data type used by the function must
guido+libpws@1 612 match the data type of the field specified in <xref
guido+libpws@1 613 linkend="table-header-fields"/> in case of header fields or that in <xref
guido+libpws@1 614 linkend="table-record-fields"/> in case of record fields.</para>
guido+libpws@1 615 <para>The <function>pws3_field_get_time()</function>,
guido+libpws@1 616 <function>pws3_field_get_uint8()</function>,
guido+libpws@1 617 <function>pws3_field_get_uint16()</function>, and
guido+libpws@1 618 <function>pws3_field_get_uint32()</function> functions return the
guido+libpws@1 619 value of the given field. The
guido+libpws@1 620 <function>pws3_field_get_uuid()</function>,
guido+libpws@1 621 <function>pws3_field_get_text()</function>, and
guido+libpws@1 622 <function>pws3_field_get_bytes()</function> functions return a
guido+libpws@1 623 pointer to the data of the given field if it has been set. The data type
guido+libpws@1 624 used by the function must match the data type of the field specified in
guido+libpws@1 625 <xref linkend="table-header-fields"/> in case of header fields and that
guido+libpws@1 626 in <xref linkend="table-record-fields"/> in case of record fields.
guido+libpws@1 627 Returned pointers are only valid until a field is modified or
guido+libpws@1 628 deallocated.</para>
guido+libpws@1 629 </refsect2>
guido+libpws@1 630 <refsect2>
guido+libpws@1 631 <title>Header Fields</title>
guido+libpws@1 632 <para>Header fields are used to store metadata for the whole file, each
guido+libpws@1 633 type of header field with the exception of the empty groups header field
guido+libpws@1 634 only occurs once. The following header fields are supported:
guido+libpws@1 635 <table xml:id="table-header-fields">
guido+libpws@1 636 <title>Header Fields</title>
guido+libpws@1 637 <tgroup cols="4" align="left" colsep="1" rowsep="1">
guido+libpws@1 638 <thead>
guido+libpws@1 639 <row>
guido+libpws@1 640 <entry>Header Field Type</entry>
guido+libpws@1 641 <entry>Numeric Value</entry>
guido+libpws@1 642 <entry>Data Type</entry>
guido+libpws@1 643 <entry>Description</entry>
guido+libpws@1 644 </row>
guido+libpws@1 645 </thead>
guido+libpws@1 646 <tbody>
guido+libpws@1 647 <row>
guido+libpws@1 648 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;VERSION</constant></entry>
guido+libpws@1 649 <entry><literal>0x00</literal></entry>
guido+libpws@1 650 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT16</constant></entry>
guido+libpws@1 651 <entry>file format version</entry>
guido+libpws@1 652 </row>
guido+libpws@1 653 <row>
guido+libpws@1 654 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;UUID</constant></entry>
guido+libpws@1 655 <entry><literal>0x01</literal></entry>
guido+libpws@1 656 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
guido+libpws@1 657 <entry>UUID</entry>
guido+libpws@1 658 </row>
guido+libpws@1 659 <row>
guido+libpws@1 660 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;NON_&#8203;DEFAULT_&#8203;PREFERENCES</constant></entry>
guido+libpws@1 661 <entry><literal>0x02</literal></entry>
guido+libpws@1 662 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 663 <entry>non-default preferences</entry>
guido+libpws@1 664 </row>
guido+libpws@1 665 <row>
guido+libpws@1 666 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;TREE_&#8203;DISPLAY_&#8203;STATUS</constant></entry>
guido+libpws@1 667 <entry><literal>0x03</literal></entry>
guido+libpws@1 668 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 669 <entry>expandended/&#8203;collapsed state of the tree of groups</entry>
guido+libpws@1 670 </row>
guido+libpws@1 671 <row>
guido+libpws@1 672 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;TIMESTAMP</constant></entry>
guido+libpws@1 673 <entry><literal>0x04</literal></entry>
guido+libpws@1 674 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
guido+libpws@1 675 <entry>time when the file was last saved</entry>
guido+libpws@1 676 </row>
guido+libpws@1 677 <row>
guido+libpws@1 678 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;USER_&#8203;HOST</constant></entry>
guido+libpws@1 679 <entry><literal>0x05</literal></entry>
guido+libpws@1 680 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 681 <entry>name of the user who last saved the file and name of the host where the file was saved</entry>
guido+libpws@1 682 </row>
guido+libpws@1 683 <row>
guido+libpws@1 684 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;APPLICATION</constant></entry>
guido+libpws@1 685 <entry><literal>0x06</literal></entry>
guido+libpws@1 686 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 687 <entry>name of the application used to save the file</entry>
guido+libpws@1 688 </row>
guido+libpws@1 689 <row>
guido+libpws@1 690 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;USER</constant></entry>
guido+libpws@1 691 <entry><literal>0x07</literal></entry>
guido+libpws@1 692 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 693 <entry>name of the user who last saved the file</entry>
guido+libpws@1 694 </row>
guido+libpws@1 695 <row>
guido+libpws@1 696 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;HOST</constant></entry>
guido+libpws@1 697 <entry><literal>0x08</literal></entry>
guido+libpws@1 698 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 699 <entry>name of the host where the file was last saved</entry>
guido+libpws@1 700 </row>
guido+libpws@1 701 <row>
guido+libpws@1 702 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;NAME</constant></entry>
guido+libpws@1 703 <entry><literal>0x09</literal></entry>
guido+libpws@1 704 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 705 <entry>logical name for referring to the file</entry>
guido+libpws@1 706 </row>
guido+libpws@1 707 <row>
guido+libpws@1 708 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;DESCRIPTION</constant></entry>
guido+libpws@1 709 <entry><literal>0x0a</literal></entry>
guido+libpws@1 710 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 711 <entry>description of the file</entry>
guido+libpws@1 712 </row>
guido+libpws@1 713 <row>
guido+libpws@1 714 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;FILTERS</constant></entry>
guido+libpws@1 715 <entry><literal>0x0b</literal></entry>
guido+libpws@1 716 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 717 <entry>filters for this file</entry>
guido+libpws@1 718 </row>
guido+libpws@1 719 <row>
guido+libpws@1 720 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
guido+libpws@1 721 <entry><literal>0x0c</literal></entry>
guido+libpws@1 722 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
guido+libpws@1 723 <entry>reserved</entry>
guido+libpws@1 724 </row>
guido+libpws@1 725 <row>
guido+libpws@1 726 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;2</constant></entry>
guido+libpws@1 727 <entry><literal>0x0d</literal></entry>
guido+libpws@1 728 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
guido+libpws@1 729 <entry>reserved</entry>
guido+libpws@1 730 </row>
guido+libpws@1 731 <row>
guido+libpws@1 732 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;3</constant></entry>
guido+libpws@1 733 <entry><literal>0x0e</literal></entry>
guido+libpws@1 734 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
guido+libpws@1 735 <entry>reseved</entry>
guido+libpws@1 736 </row>
guido+libpws@1 737 <row>
guido+libpws@1 738 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RECENTLY_&#8203;USED_&#8203;ENTRIES</constant></entry>
guido+libpws@1 739 <entry><literal>0x0f</literal></entry>
guido+libpws@1 740 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 741 <entry>list of recently used entries</entry>
guido+libpws@1 742 </row>
guido+libpws@1 743 <row>
guido+libpws@1 744 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;NAMED_&#8203;PASSWORD_&#8203;POLICIES</constant></entry>
guido+libpws@1 745 <entry><literal>0x10</literal></entry>
guido+libpws@1 746 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 747 <entry>named password policies</entry>
guido+libpws@1 748 </row>
guido+libpws@1 749 <row>
guido+libpws@1 750 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;EMPTY_&#8203;GROUPS</constant></entry>
guido+libpws@1 751 <entry><literal>0x11</literal></entry>
guido+libpws@1 752 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 753 <entry>empty groups which contain no entries</entry>
guido+libpws@1 754 </row>
guido+libpws@1 755 <row>
guido+libpws@1 756 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;YUBICO</constant></entry>
guido+libpws@1 757 <entry><literal>0x12</literal></entry>
guido+libpws@1 758 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 759 <entry>reserved</entry>
guido+libpws@1 760 </row>
guido+libpws@1 761 </tbody>
guido+libpws@1 762 </tgroup>
guido+libpws@1 763 </table>
guido+libpws@1 764 </para>
guido+libpws@1 765 <para>The <function>pws3_file_set_header_field()</function> function sets
guido+libpws@1 766 the header field on the given file. An existing field of the same type is
guido+libpws@1 767 replaced with the exception of fields of type
guido+libpws@1 768 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> for which
guido+libpws@1 769 <function>pws3_file_set_header_field()</function> has the same effect as
guido+libpws@1 770 calling the <function>pws3_file_insert_empty_group()</function>
guido+libpws@1 771 function.</para>
guido+libpws@1 772 <para>The <function>pws3_file_get_header_field()</function> function
guido+libpws@1 773 returns a pointer to the header field data structure of the given header
guido+libpws@1 774 field type. In case of the
guido+libpws@1 775 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type a pointer
guido+libpws@1 776 to the first empty group field is returned.</para>
guido+libpws@1 777 <para>The <function>pws3_file_remove_header_field()</function> function
guido+libpws@1 778 removes the header field from the given file and returns a pointer to it.
guido+libpws@1 779 It is the responsibility of the caller to deallocate the header field
guido+libpws@1 780 data structure. In case of the
guido+libpws@1 781 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type the first
guido+libpws@1 782 empty group is removed.</para>
guido+libpws@1 783 <para>The <function>pws3_file_insert_empty_group()</function> function
guido+libpws@1 784 inserts the given empty groups field into the file, an existing field for
guido+libpws@1 785 a group of the same name is replaced.</para>
guido+libpws@1 786 <para>The <function>pws3_file_get_empty_group()</function> function
guido+libpws@1 787 returns a pointer to the header field datat structure representing an
guido+libpws@1 788 empty group of the given name.</para>
guido+libpws@1 789 <para>The <function>pws3_file_remove_empty_group()</function> function
guido+libpws@1 790 removes the field representing the empty group of the given name from the
guido+libpws@1 791 file and returns a pointer to the header field data structure. It is the
guido+libpws@1 792 responsibility of the caller to deallocate the header field data
guido+libpws@1 793 structure.</para>
guido+libpws@1 794 <para>The <function>pws3_file_first_empty_group()</function> function
guido+libpws@1 795 returns a pointer to the first empty group header field.</para>
guido+libpws@1 796 <para>The <function>pws3_file_last_empty_group()</function> function
guido+libpws@1 797 returns a pointer to the last empty group header field.</para>
guido+libpws@1 798 <para>The <function>pws3_file_next_empty_group()</function> function
guido+libpws@1 799 returns a pointer to the next empty group header filed data structure
guido+libpws@1 800 following the given <parameter>field</parameter>.</para>
guido+libpws@1 801 <para>The <function>pws3_file_prev_empty_groupious()</function> function
guido+libpws@1 802 returns a pointer to the previous empty group header filed data structure
guido+libpws@1 803 preceding the given <parameter>field</parameter>.</para>
guido+libpws@1 804 </refsect2>
guido+libpws@1 805 <refsect2>
guido+libpws@1 806 <title>Records</title>
guido+libpws@1 807 <para>Records consist of at least one or more typed fields, they are
guido+libpws@1 808 identified by an UUID which is the only mandatory field and must not be
guido+libpws@1 809 removed. For presentational purposes records may be organized in
guido+libpws@1 810 hierarchical groups. The following record fields are supported:
guido+libpws@1 811 <table xml:id="table-record-fields">
guido+libpws@1 812 <title>Record Fields</title>
guido+libpws@1 813 <tgroup cols="4" align="left" colsep="1" rowsep="1">
guido+libpws@1 814 <thead>
guido+libpws@1 815 <row>
guido+libpws@1 816 <entry>Record Field Type</entry>
guido+libpws@1 817 <entry>Numeric Value</entry>
guido+libpws@1 818 <entry>Data Type</entry>
guido+libpws@1 819 <entry>Description</entry>
guido+libpws@1 820 </row>
guido+libpws@1 821 </thead>
guido+libpws@1 822 <tbody>
guido+libpws@1 823 <row>
guido+libpws@1 824 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;UUID</constant></entry>
guido+libpws@1 825 <entry><literal>0x01</literal></entry>
guido+libpws@1 826 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
guido+libpws@1 827 <entry>UUID identifying the record</entry>
guido+libpws@1 828 </row>
guido+libpws@1 829 <row>
guido+libpws@1 830 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;GROUP</constant></entry>
guido+libpws@1 831 <entry><literal>0x02</literal></entry>
guido+libpws@1 832 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 833 <entry>group name the record is a member of</entry>
guido+libpws@1 834 </row>
guido+libpws@1 835 <row>
guido+libpws@1 836 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;TITLE</constant></entry>
guido+libpws@1 837 <entry><literal>0x03</literal></entry>
guido+libpws@1 838 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 839 <entry>title</entry>
guido+libpws@1 840 </row>
guido+libpws@1 841 <row>
guido+libpws@1 842 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;USERNAME</constant></entry>
guido+libpws@1 843 <entry><literal>0x04</literal></entry>
guido+libpws@1 844 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 845 <entry>username</entry>
guido+libpws@1 846 </row>
guido+libpws@1 847 <row>
guido+libpws@1 848 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;NOTES</constant></entry>
guido+libpws@1 849 <entry><literal>0x05</literal></entry>
guido+libpws@1 850 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 851 <entry>notes</entry>
guido+libpws@1 852 </row>
guido+libpws@1 853 <row>
guido+libpws@1 854 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD</constant></entry>
guido+libpws@1 855 <entry><literal>0x06</literal></entry>
guido+libpws@1 856 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 857 <entry>password</entry>
guido+libpws@1 858 </row>
guido+libpws@1 859 <row>
guido+libpws@1 860 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREATION_&#8203;TIME</constant></entry>
guido+libpws@1 861 <entry><literal>0x07</literal></entry>
guido+libpws@1 862 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
guido+libpws@1 863 <entry>time when the record was created</entry>
guido+libpws@1 864 </row>
guido+libpws@1 865 <row>
guido+libpws@1 866 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
guido+libpws@1 867 <entry><literal>0x08</literal></entry>
guido+libpws@1 868 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
guido+libpws@1 869 <entry>time when the password was last modified</entry>
guido+libpws@1 870 </row>
guido+libpws@1 871 <row>
guido+libpws@1 872 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ACCESS_&#8203;TIME</constant></entry>
guido+libpws@1 873 <entry><literal>0x09</literal></entry>
guido+libpws@1 874 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
guido+libpws@1 875 <entry>time when the record was last accessed</entry>
guido+libpws@1 876 </row>
guido+libpws@1 877 <row>
guido+libpws@1 878 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;TIME</constant></entry>
guido+libpws@1 879 <entry><literal>0x0a</literal></entry>
guido+libpws@1 880 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
guido+libpws@1 881 <entry>time when the password expires</entry>
guido+libpws@1 882 </row>
guido+libpws@1 883 <row>
guido+libpws@1 884 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
guido+libpws@1 885 <entry><literal>0x0b</literal></entry>
guido+libpws@1 886 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
guido+libpws@1 887 <entry>reserved</entry>
guido+libpws@1 888 </row>
guido+libpws@1 889 <row>
guido+libpws@1 890 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
guido+libpws@1 891 <entry><literal>0x0c</literal></entry>
guido+libpws@1 892 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
guido+libpws@1 893 <entry>time at whcih the record was last modified</entry>
guido+libpws@1 894 </row>
guido+libpws@1 895 <row>
guido+libpws@1 896 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;URL</constant></entry>
guido+libpws@1 897 <entry><literal>0x0d</literal></entry>
guido+libpws@1 898 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 899 <entry>URL</entry>
guido+libpws@1 900 </row>
guido+libpws@1 901 <row>
guido+libpws@1 902 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;AUTOTYPE</constant></entry>
guido+libpws@1 903 <entry><literal>0x0e</literal></entry>
guido+libpws@1 904 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 905 <entry>text to be typed when using the autotype feature</entry>
guido+libpws@1 906 </row>
guido+libpws@1 907 <row>
guido+libpws@1 908 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;HISTORY</constant></entry>
guido+libpws@1 909 <entry><literal>0x0f</literal></entry>
guido+libpws@1 910 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 911 <entry>creation time and values of previously used passwords</entry>
guido+libpws@1 912 </row>
guido+libpws@1 913 <row>
guido+libpws@1 914 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY</constant></entry>
guido+libpws@1 915 <entry><literal>0x10</literal></entry>
guido+libpws@1 916 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 917 <entry>password policy</entry>
guido+libpws@1 918 </row>
guido+libpws@1 919 <row>
guido+libpws@1 920 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;INTERVAL</constant></entry>
guido+libpws@1 921 <entry><literal>0x11</literal></entry>
guido+libpws@1 922 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT32</constant></entry>
guido+libpws@1 923 <entry>days until the password expires</entry>
guido+libpws@1 924 </row>
guido+libpws@1 925 <row>
guido+libpws@1 926 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RUN_&#8203;COMMAND</constant></entry>
guido+libpws@1 927 <entry><literal>0x12</literal></entry>
guido+libpws@1 928 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 929 <entry>command</entry>
guido+libpws@1 930 </row>
guido+libpws@1 931 <row>
guido+libpws@1 932 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
guido+libpws@1 933 <entry><literal>0x13</literal></entry>
guido+libpws@1 934 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
guido+libpws@1 935 <entry>action on double clicking</entry>
guido+libpws@1 936 </row>
guido+libpws@1 937 <row>
guido+libpws@1 938 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;EMAIL_&#8203;ADDRESS</constant></entry>
guido+libpws@1 939 <entry><literal>0x14</literal></entry>
guido+libpws@1 940 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 941 <entry>email address</entry>
guido+libpws@1 942 </row>
guido+libpws@1 943 <row>
guido+libpws@1 944 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PROTECTED</constant></entry>
guido+libpws@1 945 <entry><literal>0x15</literal></entry>
guido+libpws@1 946 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT8</constant></entry>
guido+libpws@1 947 <entry>flag whether the record is protected from modification</entry>
guido+libpws@1 948 </row>
guido+libpws@1 949 <row>
guido+libpws@1 950 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ALLOWED_&#8203;PASSWORD_&#8203;SYMBOLS</constant></entry>
guido+libpws@1 951 <entry><literal>0x16</literal></entry>
guido+libpws@1 952 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 953 <entry>allowed symbols for generating passwords</entry>
guido+libpws@1 954 </row>
guido+libpws@1 955 <row>
guido+libpws@1 956 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;SHIFT_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
guido+libpws@1 957 <entry><literal>0x17</literal></entry>
guido+libpws@1 958 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
guido+libpws@1 959 <entry>action on pressing shift and double clicking</entry>
guido+libpws@1 960 </row>
guido+libpws@1 961 <row>
guido+libpws@1 962 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY_&#8203;NAME</constant></entry>
guido+libpws@1 963 <entry><literal>0x18</literal></entry>
guido+libpws@1 964 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
guido+libpws@1 965 <entry>name of password policy saved in the header</entry>
guido+libpws@1 966 </row>
guido+libpws@1 967 <row>
guido+libpws@1 968 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;KEYBOARD_&#8203;SHORTCUT</constant></entry>
guido+libpws@1 969 <entry><literal>0x19</literal></entry>
guido+libpws@1 970 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
guido+libpws@1 971 <entry>keyboard shortcut</entry>
guido+libpws@1 972 </row>
guido+libpws@1 973 </tbody>
guido+libpws@1 974 </tgroup>
guido+libpws@1 975 </table>
guido+libpws@1 976 </para>
guido+libpws@1 977 <para>The <function>pws3_record_create()</function> function allocates
guido+libpws@1 978 and creates a record data structure, generates an UUID record field and
guido+libpws@1 979 adds it to the record.</para>
guido+libpws@1 980 <para>The <function>pws3_record_destroy()</function> function deallocates
guido+libpws@1 981 the given record data structure and all its record fields.</para>
guido+libpws@1 982 <para>The <function>pws3_file_record_field_set()</function> function sets
guido+libpws@1 983 the record field on the given record, replacing an existing field of the
guido+libpws@1 984 same type.</para>
guido+libpws@1 985 <para>The <function>pws3_file_record_field_get()</function> function
guido+libpws@1 986 returns a pointer to the record field data structure of the given record
guido+libpws@1 987 field type.</para>
guido+libpws@1 988 <para>The <function>pws3_file_record_field_remove()</function> function
guido+libpws@1 989 removes the record field from the given record and returns a pointer to
guido+libpws@1 990 it. It is the responsibility of the caller to deallocate the record field
guido+libpws@1 991 data structure.</para>
guido+libpws@1 992 <para>The <function>pws3_file_insert_record()</function> function inserts
guido+libpws@1 993 the given record into the file, an existing record with the same UUID is
guido+libpws@1 994 replaced.</para>
guido+libpws@1 995 <para>The <function>pws3_file_get_record()</function> function returns a
guido+libpws@1 996 pointer to the record structure representing a record with the given
guido+libpws@1 997 UUID.</para>
guido+libpws@1 998 <para>The <function>pws3_file_remove_record()</function> function removes
guido+libpws@1 999 the record with the given UUID from the file and returns a pointer to the
guido+libpws@1 1000 record data structure. It is the responsibility of the caller to
guido+libpws@1 1001 deallocate the record data structure.</para>
guido+libpws@1 1002 <para>The <function>pws3_file_first_record()</function> function returns a
guido+libpws@1 1003 pointer to the first record.</para>
guido+libpws@1 1004 <para>The <function>pws3_file_last_record()</function> function returns a
guido+libpws@1 1005 pointer to the last record.</para>
guido+libpws@1 1006 <para>The <function>pws3_file_next_record()</function> function returns a
guido+libpws@1 1007 pointer to the next record following the given
guido+libpws@1 1008 <parameter>record</parameter>.</para>
guido+libpws@1 1009 <para>The <function>pws3_file_prev_record()</function>
guido+libpws@1 1010 function returns a pointer to the previous group preceding the given
guido+libpws@1 1011 <parameter>record</parameter>.</para>
guido+libpws@1 1012 </refsect2>
guido+libpws@1 1013 <refsect2>
guido+libpws@1 1014 <title>Macros</title>
guido+libpws@1 1015 <para>The macro <constant>PWS3_VERSION</constant> contains the supported
guido+libpws@1 1016 version of the Password Safe version 3 file format.</para>
guido+libpws@1 1017 <para>The macro <constant>PWS3_MAX_FIELD_SIZE</constant> contains the
guido+libpws@1 1018 maxium size for header and record fields in bytes and
guido+libpws@1 1019 <constant>PWS3_MAX_PASSWORD_LEN</constant> contains the maxium password
guido+libpws@1 1020 length in bytes.</para>
guido+libpws@1 1021 <para>The macro <constant>PWS3_UUID_SIZE</constant> contains the size of
guido+libpws@1 1022 UUIDs in bytes.</para>
guido+libpws@1 1023 </refsect2>
guido+libpws@1 1024 </refsect1>
guido+libpws@1 1025 <refsect1>
guido+libpws@1 1026 <title>Return Values</title>
guido+libpws@1 1027 <para>The <function>pws3_file_create()</function> function returns a
guido+libpws@1 1028 pointer to a Password Safe file data structure if successful and
guido+libpws@1 1029 <constant>NULL</constant> in case of an error.</para>
guido+libpws@1 1030 <para>The <function>pws3_file_read_mem()</function>,
guido+libpws@1 1031 <function>pws3_file_read_stream()</function>,
guido+libpws@1 1032 <function>pws3_file_write_mem()</function>, and
guido+libpws@1 1033 <function>pws3_file_write_stream()</function> functions return
guido+libpws@1 1034 <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
guido+libpws@1 1035 to indicate an error.</para>
guido+libpws@1 1036 <para>The <function>pws3_file_get_header_field()</function> function
guido+libpws@1 1037 returns a pointer to the header field data structure of the requested type
guido+libpws@1 1038 and <constant>NULL</constant> if such a field does not exist.</para>
guido+libpws@1 1039 <para>The <function>pws3_file_remove_header_field()</function> function
guido+libpws@1 1040 returns a pointer to the header field data structure which was removed from
guido+libpws@1 1041 the file or <constant>NULL</constant> if such a field does not exist.</para>
guido+libpws@1 1042 <para>The <function>pws3_file_get_empty_group()</function> function returns
guido+libpws@1 1043 a pointer to the header field data structure corresponding to the requested
guido+libpws@1 1044 empty group and <constant>NULL</constant> if a group of that name does not
guido+libpws@1 1045 exist.</para>
guido+libpws@1 1046 <para>The <function>pws3_file_remove_empty_group()</function> function
guido+libpws@1 1047 returns a pointer to the header field data structure of the empty group
guido+libpws@1 1048 which was removed from the file or <constant>NULL</constant> if a group of
guido+libpws@1 1049 that name does not exist.</para>
guido+libpws@1 1050 <para>The <function>pws3_file_first_empty_group()</function> function
guido+libpws@1 1051 returns a pointer to the first of the empty group header fields or
guido+libpws@1 1052 <constant>NULL</constant> if there are no such fields.</para>
guido+libpws@1 1053 <para>The <function>pws3_file_last_empty_group()</function> function
guido+libpws@1 1054 returns a pointer to the last of the empty group header fields or
guido+libpws@1 1055 <constant>NULL</constant> if there are no such fields.</para>
guido+libpws@1 1056 <para>The <function>pws3_file_next_empty_group()</function> function
guido+libpws@1 1057 returns a pointer to the next empty group header field or
guido+libpws@1 1058 <constant>NULL</constant> if there are no more such fields.</para>
guido+libpws@1 1059 <para>The <function>pws3_file_prev_empty_group()</function> function
guido+libpws@1 1060 returns a pointer to the previous empty group header field or
guido+libpws@1 1061 <constant>NULL</constant> if there are no more such fields.</para>
guido+libpws@1 1062 <para>The <function>pws3_file_get_record()</function> function returns a
guido+libpws@1 1063 pointer to the record data structure of the requested record or
guido+libpws@1 1064 <constant>NULL</constant> if that record does not exist.</para>
guido+libpws@1 1065 <para>The <function>pws3_file_remove_record()</function> function returns a
guido+libpws@1 1066 pointer to the record data structure which was removed from the file or
guido+libpws@1 1067 <constant>NULL</constant> if no such record exists.</para>
guido+libpws@1 1068 <para>The <function>pws3_file_first_record()</function> function returns a
guido+libpws@1 1069 pointer to the record data structure of the first record or
guido+libpws@1 1070 <constant>NULL</constant> if no records exist.</para>
guido+libpws@1 1071 <para>The <function>pws3_file_last_record()</function> function returns a
guido+libpws@1 1072 pointer to the record data structure of the last record or
guido+libpws@1 1073 <constant>NULL</constant> if no records exist.</para>
guido+libpws@1 1074 <para>The <function>pws3_file_next_record()</function> function returns a
guido+libpws@1 1075 pointer to the record data structure of the next record or
guido+libpws@1 1076 <constant>NULL</constant> if no records exist.</para>
guido+libpws@1 1077 <para>The <function>pws3_file_prev_record()</function> function returns a
guido+libpws@1 1078 pointer to the record data structure of the previous record or
guido+libpws@1 1079 <constant>NULL</constant> if no records exist.</para>
guido+libpws@1 1080 <para>The <function>pws3_field_create()</function> function returns a
guido+libpws@1 1081 pointer to the new header field data structure on success and
guido+libpws@1 1082 <constant>NULL</constant> on failure.</para>
guido+libpws@1 1083 <para>The <function>pws3_field_get_type()</function> function returns
guido+libpws@1 1084 the field type of the header field structure.</para>
guido+libpws@1 1085 <para>The <function>pws3_field_get_data_type()</function> function
guido+libpws@1 1086 returns the data type of the header field structure.</para>
guido+libpws@1 1087 <para>The <function>pws3_field_set_uuid()</function>,
guido+libpws@1 1088 <function>pws3_field_set_text()</function>,
guido+libpws@1 1089 <function>pws3_field_set_time()</function>,
guido+libpws@1 1090 <function>pws3_field_set_uint8()</function>,
guido+libpws@1 1091 <function>pws3_field_set_uint16()</function>,
guido+libpws@1 1092 <function>pws3_field_set_uint32()</function>, and
guido+libpws@1 1093 <function>pws3_field_set_bytes()</function> functions return
guido+libpws@1 1094 <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
guido+libpws@1 1095 on failure.</para>
guido+libpws@1 1096 <para>The <function>pws3_field_get_time()</function>,
guido+libpws@1 1097 <function>pws3_field_get_uint8()</function>,
guido+libpws@1 1098 <function>pws3_field_get_uint16()</function>, and
guido+libpws@1 1099 <function>pws3_field_get_uint32()</function> functions return a
guido+libpws@1 1100 value of the type corresponding to the type of header field.</para>
guido+libpws@1 1101 <para>The <function>pws3_field_get_uuid()</function> function
guido+libpws@1 1102 returns a pointer to a UUID.</para>
guido+libpws@1 1103 <para>The <function>pws3_field_get_text()</function> function
guido+libpws@1 1104 returns a pointer to a string or <constant>NULL</constant> if no value has
guido+libpws@1 1105 been set.</para>
guido+libpws@1 1106 <para>The <function>pws3_record_create()</function> function returns a
guido+libpws@1 1107 pointer to a record data structure if successful and
guido+libpws@1 1108 <constant>NULL</constant> on failure.</para>
guido+libpws@1 1109 <para>The <function>pws3_record_get_field()</function> function returns a
guido+libpws@1 1110 pointer to the record field data structure of the requested type or
guido+libpws@1 1111 <constant>NULL</constant> if such a field does not exist.</para>
guido+libpws@1 1112 <para>The <function>pws3_record_remove_field()</function> function returns
guido+libpws@1 1113 a pointer to the record field data structure which was removed from the
guido+libpws@1 1114 record or <constant>NULL</constant> if such a field does not exist.</para>
guido+libpws@1 1115 </refsect1>
guido+libpws@1 1116 <refsect1>
guido+libpws@1 1117 <title>Errors</title>
guido+libpws@1 1118 <para>If the <function>pws3_file_read_mem()</function>,
guido+libpws@1 1119 <function>pws3_file_read_stream()</function>,
guido+libpws@1 1120 <function>pws3_file_write_mem()</function>, and
guido+libpws@1 1121 <function>pws3_file_write_stream()</function> functions fail, an error code
guido+libpws@1 1122 indicating the nature of the error may be obtained using the
guido+libpws@1 1123 <function>pws3_file_get_error_code()</function> function and a pointer to a
guido+libpws@1 1124 detailed error message may be retrieved using the
guido+libpws@1 1125 <function>pws3_file_get_error_message()</function> function. The above
guido+libpws@1 1126 functions may fail if:</para>
guido+libpws@1 1127 <variablelist>
guido+libpws@1 1128 <varlistentry>
guido+libpws@1 1129 <term><errorname>PWS_ERR_GENERIC_ERROR</errorname></term>
guido+libpws@1 1130 <listitem>
guido+libpws@1 1131 <para>An unknown error occurred.</para>
guido+libpws@1 1132 </listitem>
guido+libpws@1 1133 </varlistentry>
guido+libpws@1 1134 <varlistentry>
guido+libpws@1 1135 <term><errorname>PWS_ERR_NO_MEMORY</errorname></term>
guido+libpws@1 1136 <listitem>
guido+libpws@1 1137 <para>There was not enough space to allocate memory.</para>
guido+libpws@1 1138 </listitem>
guido+libpws@1 1139 </varlistentry>
guido+libpws@1 1140 <varlistentry>
guido+libpws@1 1141 <term><errorname>PWS_ERR_IO_ERROR</errorname></term>
guido+libpws@1 1142 <listitem>
guido+libpws@1 1143 <para>An I/O error occurred.</para>
guido+libpws@1 1144 </listitem>
guido+libpws@1 1145 </varlistentry>
guido+libpws@1 1146 <varlistentry>
guido+libpws@1 1147 <term><errorname>PWS_ERR_TRUNCATED_FILE</errorname></term>
guido+libpws@1 1148 <listitem>
guido+libpws@1 1149 <para>The file appears to be truncated.</para>
guido+libpws@1 1150 </listitem>
guido+libpws@1 1151 </varlistentry>
guido+libpws@1 1152 <varlistentry>
guido+libpws@1 1153 <term><errorname>PWS_ERR_INVALID_CHECKSUM</errorname></term>
guido+libpws@1 1154 <listitem>
guido+libpws@1 1155 <para>The calculated checksum does not match the checksum of the
guido+libpws@1 1156 file.</para>
guido+libpws@1 1157 </listitem>
guido+libpws@1 1158 </varlistentry>
guido+libpws@1 1159 <varlistentry>
guido+libpws@1 1160 <term><errorname>PWS_ERR_INVALID_RECORD</errorname></term>
guido+libpws@1 1161 <listitem>
guido+libpws@1 1162 <para>A record is invalid.</para>
guido+libpws@1 1163 </listitem>
guido+libpws@1 1164 </varlistentry>
guido+libpws@1 1165 <varlistentry>
guido+libpws@1 1166 <term><errorname>PWS_ERR_INVALID_HEADER</errorname></term>
guido+libpws@1 1167 <listitem>
guido+libpws@1 1168 <para>A header is invalid.</para>
guido+libpws@1 1169 </listitem>
guido+libpws@1 1170 </varlistentry>
guido+libpws@1 1171 <varlistentry>
guido+libpws@1 1172 <term><errorname>PWS_ERR_UNSUPPORTED_VERSION</errorname></term>
guido+libpws@1 1173 <listitem>
guido+libpws@1 1174 <para>The file format version is not supported.</para>
guido+libpws@1 1175 </listitem>
guido+libpws@1 1176 </varlistentry>
guido+libpws@1 1177 </variablelist>
guido+libpws@1 1178 </refsect1>
guido+libpws@1 1179 <refsect1>
guido+libpws@1 1180 <title>Examples</title>
guido+libpws@1 1181 <example>
guido+libpws@1 1182 <title>Creating a Password Safe file</title>
guido+libpws@1 1183 <para>The following code creates a new Password Safe file and sets the
guido+libpws@1 1184 save application header field:</para>
guido+libpws@1 1185 <programlisting>
guido+libpws@1 1186 <![CDATA[
guido+libpws@1 1187 #include <pws.h>
guido+libpws@1 1188
guido+libpws@1 1189 /* ... */
guido+libpws@1 1190
guido+libpws@1 1191 struct pws3_file *file;
guido+libpws@1 1192 struct pws3_field *application_field;
guido+libpws@1 1193
guido+libpws@1 1194 /* ... */
guido+libpws@1 1195
guido+libpws@1 1196 /* initialize libpws */
guido+libpws@1 1197 if (pws_init() != 0) {
guido+libpws@1 1198 /* handle error */
guido+libpws@1 1199 }
guido+libpws@1 1200
guido+libpws@1 1201 /* ... */
guido+libpws@1 1202
guido+libpws@1 1203 /* create a new empty file structure */
guido+libpws@1 1204 file = pws3_file_create();
guido+libpws@1 1205 if (file == NULL) {
guido+libpws@1 1206 /* handle error */
guido+libpws@1 1207 }
guido+libpws@1 1208 /* create new empty save application field */
guido+libpws@1 1209 application_field = pws3_field_create(1, PWS3_HEADER_FIELD_SAVE_APPLICATION);
guido+libpws@1 1210 if (application_field == NULL) {
guido+libpws@1 1211 /* handle error */
guido+libpws@1 1212 }
guido+libpws@1 1213 /* set the value of the field */
guido+libpws@1 1214 if (pws3_field_set_text(application_field, "PasswordManager 2.0") != 0) {
guido+libpws@1 1215 /* handle error */
guido+libpws@1 1216 }
guido+libpws@1 1217 /* set the header save application field in the file to the new field */
guido+libpws@1 1218 pws3_file_set_field(file, application_field);
guido+libpws@1 1219 ]]>
guido+libpws@1 1220 </programlisting>
guido+libpws@1 1221 </example>
guido+libpws@1 1222 <example>
guido+libpws@1 1223 <title>Print the title of each record</title>
guido+libpws@1 1224 <para>The following code loops over each record of an existing Password
guido+libpws@1 1225 Safe file and prints the content of the title field if it exists:</para>
guido+libpws@1 1226 <programlisting>
guido+libpws@1 1227 <![CDATA[
guido+libpws@1 1228 #include <stdio.h>
guido+libpws@1 1229 #include <pws.h>
guido+libpws@1 1230
guido+libpws@1 1231 /* ... */
guido+libpws@1 1232
guido+libpws@1 1233 struct pws3_file *file;
guido+libpws@1 1234 struct pws3_record *record;
guido+libpws@1 1235 struct pws3_field *title_field;
guido+libpws@1 1236
guido+libpws@1 1237 /* ... */
guido+libpws@1 1238
guido+libpws@1 1239 /* interate over each record */
guido+libpws@1 1240 for (record = pws3_file_first_record(file); record != NULL;
guido+libpws@1 1241 record = pws3_file_next_record(file, record)) {
guido+libpws@1 1242 /* retrieve title field */
guido+libpws@1 1243 title_field = pws3_record_get_field(record, PWS3_RECORD_FIELD_TITLE);
guido+libpws@1 1244 /* print the title field or "No title" if it does not exitst */
guido+libpws@1 1245 printf("Title: %s\n", (title_field != NULL) ?
guido+libpws@1 1246 pws3_record_field_get_text(PWS3_RECORD_FIELD_TITLE) : "No title");
guido+libpws@1 1247 }
guido+libpws@1 1248 ]]>
guido+libpws@1 1249 </programlisting>
guido+libpws@1 1250 </example>
guido+libpws@1 1251 <example>
guido+libpws@1 1252 <title>Add a new record to a file</title>
guido+libpws@1 1253 <para>The following code creates a new record with a password field, a
guido+libpws@1 1254 title field, and a creation time field and adds it to an existing
guido+libpws@1 1255 Password Safe file:</para>
guido+libpws@1 1256 <programlisting>
guido+libpws@1 1257 <![CDATA[
guido+libpws@1 1258 #include <time.h>
guido+libpws@1 1259 #include <pws.h>
guido+libpws@1 1260
guido+libpws@1 1261 /* ... */
guido+libpws@1 1262
guido+libpws@1 1263 struct pws3_file *file;
guido+libpws@1 1264 struct pws3_record *record;
guido+libpws@1 1265 struct pws3_field *password_field;
guido+libpws@1 1266 struct pws3_field *title_field;
guido+libpws@1 1267 struct pws3_field *ctime_field;
guido+libpws@1 1268 time_t now;
guido+libpws@1 1269
guido+libpws@1 1270 /* ... */
guido+libpws@1 1271
guido+libpws@1 1272 /* create new record */
guido+libpws@1 1273 record = pws3_record_create();
guido+libpws@1 1274 if (record == NULL) {
guido+libpws@1 1275 /* handle error */
guido+libpws@1 1276 }
guido+libpws@1 1277
guido+libpws@1 1278 /* create a password field */
guido+libpws@1 1279 password_field = pws3_record_field_create(PWS3_RECORD_FIELD_PASSWORD);
guido+libpws@1 1280 if (password_field == NULL) {
guido+libpws@1 1281 /* handle error */
guido+libpws@1 1282 }
guido+libpws@1 1283 /* set the value of the password field to "PaSsWoRd" */
guido+libpws@1 1284 if (pws3_record_field_set_text(password_field, "PaSsWoRd") != 0) {
guido+libpws@1 1285 /* handle error */
guido+libpws@1 1286 }
guido+libpws@1 1287 /* set the password field of the record to the new field */
guido+libpws@1 1288 pws3_record_set_field(record, password_field);
guido+libpws@1 1289
guido+libpws@1 1290 /* create a title field */
guido+libpws@1 1291 title_field = pws3_record_field_create(PWS3_RECORD_FIELD_TITLE);
guido+libpws@1 1292 if (title_field == NULL) {
guido+libpws@1 1293 /* handle error */
guido+libpws@1 1294 }
guido+libpws@1 1295 /* set the value of the title field to "Foo Bar" */
guido+libpws@1 1296 if (pws3_record_field_set_text(title_field, "Foo Bar") != 0) {
guido+libpws@1 1297 /* handle error */
guido+libpws@1 1298 }
guido+libpws@1 1299 /* set the title field of the record to the new field */
guido+libpws@1 1300 pws3_record_set_field(record, title_field);
guido+libpws@1 1301
guido+libpws@1 1302 /* create a new creation time field */
guido+libpws@1 1303 ctime_field = pws3_record_field_create(PWS3_RECORD_FIELD_CREATION_TIME);
guido+libpws@1 1304 if (ctime_field == NULL) {
guido+libpws@1 1305 /* handle error */
guido+libpws@1 1306 }
guido+libpws@1 1307 /* set the value of the creation time field to the current time */
guido+libpws@1 1308 pws3_record_field_set_time(ctime_field, time(NULL));
guido+libpws@1 1309 /* set the creation time field of the record to the new field */
guido+libpws@1 1310 pws3_record_set_field(record, ctime_field);
guido+libpws@1 1311
guido+libpws@1 1312 /* insert the new record into the file */
guido+libpws@1 1313 pws3_file_insert_record(file, record);
guido+libpws@1 1314 ]]>
guido+libpws@1 1315 </programlisting>
guido+libpws@1 1316 </example>
guido+libpws@1 1317 <example>
guido+libpws@1 1318 <title>Reading a Password Safe file</title>
guido+libpws@1 1319 <para>The following code opens a Password Safe file named
guido+libpws@1 1320 <filename>example.pwsafe3</filename> and parses it:</para>
guido+libpws@1 1321 <programlisting>
guido+libpws@1 1322 <![CDATA[
guido+libpws@1 1323 #include <stdio.h>
guido+libpws@1 1324 #include <pws.h>
guido+libpws@1 1325
guido+libpws@1 1326 /* ... */
guido+libpws@1 1327
guido+libpws@1 1328 FILE *fp;
guido+libpws@1 1329 struct pws3_file *file;
guido+libpws@1 1330
guido+libpws@1 1331 /* ... */
guido+libpws@1 1332
guido+libpws@1 1333 /* initialize libpws */
guido+libpws@1 1334 if (pws_init() != 0) {
guido+libpws@1 1335 /* handle error */
guido+libpws@1 1336 }
guido+libpws@1 1337
guido+libpws@1 1338 /* ... */
guido+libpws@1 1339
guido+libpws@1 1340 /* create a new empty file structure */
guido+libpws@1 1341 file = pws3_file_create();
guido+libpws@1 1342 if (file == NULL) {
guido+libpws@1 1343 /* handle error */
guido+libpws@1 1344 }
guido+libpws@1 1345
guido+libpws@1 1346 /* open the file */
guido+libpws@1 1347 fp = fopen("example.pwsafe3", "r");
guido+libpws@1 1348 if (fp == NULL) {
guido+libpws@1 1349 /* handle error */
guido+libpws@1 1350 }
guido+libpws@1 1351
guido+libpws@1 1352 /* read and parse the file contents into the file structure */
guido+libpws@1 1353 if (pws3_file_read_stream(file, "PaSsWoRd", fp) != 0) {
guido+libpws@1 1354 fprintf(stderr, "error: %s\n",
guido+libpws@1 1355 pws3_file_get_error_message(file));
guido+libpws@1 1356 /* handle error */
guido+libpws@1 1357 }
guido+libpws@1 1358 ]]>
guido+libpws@1 1359 </programlisting>
guido+libpws@1 1360 </example>
guido+libpws@1 1361 <example>
guido+libpws@1 1362 <title>Writing a Password Safe file</title>
guido+libpws@1 1363 <para>The following code writes a Password Safe file to a file
guido+libpws@1 1364 named <filename>example.pwsafe3</filename>:</para>
guido+libpws@1 1365 <programlisting>
guido+libpws@1 1366 <![CDATA[
guido+libpws@1 1367 #include <stdio.h>
guido+libpws@1 1368 #include <pws.h>
guido+libpws@1 1369
guido+libpws@1 1370 /* ... */
guido+libpws@1 1371
guido+libpws@1 1372 FILE *fp;
guido+libpws@1 1373 struct pws3_file *file;
guido+libpws@1 1374
guido+libpws@1 1375 /* ... */
guido+libpws@1 1376
guido+libpws@1 1377 fp = fopen("example.pwsafe3", "w");
guido+libpws@1 1378 if (fp == NULL) {
guido+libpws@1 1379 /* handle error */
guido+libpws@1 1380 }
guido+libpws@1 1381
guido+libpws@1 1382 if (pws3_file_write_stream(file, "FoOBaR", 10000, fp) != 0) {
guido+libpws@1 1383 /* handle error */
guido+libpws@1 1384 }
guido+libpws@1 1385
guido+libpws@1 1386 fflush(fp);
guido+libpws@1 1387 fclose(fp);
guido+libpws@1 1388 ]]>
guido+libpws@1 1389 </programlisting>
guido+libpws@1 1390 </example>
guido+libpws@1 1391 </refsect1>
guido+libpws@1 1392 <refsect1>
guido+libpws@1 1393 <title>See Also</title>
guido+libpws@1 1394 <para><citerefentry><refentrytitle>libpws</refentrytitle>
guido+libpws@1 1395 <manvolnum>3</manvolnum></citerefentry>,
guido+libpws@1 1396 <citerefentry><refentrytitle>pws_init</refentrytitle>
guido+libpws@1 1397 <manvolnum>3</manvolnum></citerefentry>,
guido+libpws@1 1398 <link xlink:href="https://pwsafe.org/"/></para>
guido+libpws@1 1399 </refsect1>
guido+libpws@1 1400 </refentry>