Mercurial > projects > libpws

annotate README @ 9:ec5c1b653ee6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Prevent NULL pointer dereference Creating the end field may fail, thus try to allocate it in advance.
author Guido Berhoerster <guido+libpws@berhoerster.name>
date Tue, 30 Jul 2019 14:52:29 +0200
parents e1309515d111
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
1 libpws
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
2 =======
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
3
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
4 Description
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
5 -----------
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
6
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
7 libpws provides an API for creating, reading, manipulating and writing
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
8 Password Safe files, it currently supports version 3 of the Password Safe file
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
9 format.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
10
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
11 Build Instructions
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
12 ------------------
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
13
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
14 libpws requires a POSIX:2004 compatible operating system, it has been tested
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
15 to work on Linux distributions, FreeBSD, Solaris and Illumos-derived
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
16 distributions. The following tools and shared libraries are required to build
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
17 libpws:
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
18
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
19 - GNU make >= 3.81
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
20 - GNU or BSD install
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
21 - Nettle
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
22
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
23 Rebuilding the man pages additionally requires the xsltproc tool from libxml2.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
24
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
25 Before building libpws check the commented macros in the Makefile for any
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
26 macros you may need to override depending on the used toolchain and operating
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
27 system.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
28
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
29 By default, all files will be installed under the "/usr/local" directory, a
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
30 different installation path prefix can be set via the `prefix` macro. In
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
31 addition, a second path prefix can be specified via the `DESTDIR` macro which
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
32 will be prepended to any path, incuding the `prefix` macro path prefix. In
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
33 contrast to `prefix`, the path specified via the `DESTDIR` macro will only be
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
34 prepended to paths during installation and not be used for constructing
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
35 internal paths.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
36
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
37 The following instructions assume that `make` is GNU make, on some platforms
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
38 it may be installed under a different name or a non-default path. In order to
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
39 start the build process run `make all`. After a successful build, run `make
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
40 install` to install the program, any associated data files and the
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
41 documentation.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
42
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
43 Previously built binaries, object files, generated data files and
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
44 documentation can be removed by running `make clean`, any additional,
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
45 generated files which are not removed by the `clean` target can be removed by
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
46 running `make clobber`.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
47
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
48 Contact
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
49 -------
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
50
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
51 Please send any feedback, translations or bug reports via email to
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
52 <guido+libpws@berhoerster.name>.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
53
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
54 Bug Reports
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
55 -----------
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
56
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
57 When sending bug reports, please always mention the exact version of libpws
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
58 with which the issue occurs as well as the version of the operating system you
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
59 are using and make sure that you provide sufficient information to reproduce
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
60 the issue and include any input, output, any error messages.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
61
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
62 In case of build issues, please also specify the implementations and versions
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
63 of the tools and shared libraries used to build the program, in particular the
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
64 compiler.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
65
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
66 In case of crashes, please generate a stack trace with a suitable debugger
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
67 such as gdb, lldb, dbx, or debug after a crash has occurred either by
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
68 examining the resulting core file or by running the program from the debugger
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
69 and attach it to the bug report. In order to generate a meaningful stack
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
70 trace the program as well as any dynamically linked libraries need to be built
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
71 with debugging information, see the documentation of the used compiler for the
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
72 required compiler flags. If any of the dynamically linked shared libraries do
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
73 not contain debugging information, please either install debugging information
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
74 for these libraries using mechanisms provided by your operating system or
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
75 rebuild the libraries accordingly. Please refer to the documentation of the
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
76 debugger for detailed instructions on generating backtraces.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
77
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
78 License
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
79 -------
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
80
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
81 Except otherwise noted, all files are Copyright (C) 2015 Guido Berhoerster and
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
82 distributed under the following license terms:
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
83
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
84 Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
85
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
86 Permission is hereby granted, free of charge, to any person obtaining
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
87 a copy of this software and associated documentation files (the
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
88 "Software"), to deal in the Software without restriction, including
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
89 without limitation the rights to use, copy, modify, merge, publish,
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
90 distribute, sublicense, and/or sell copies of the Software, and to
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
91 permit persons to whom the Software is furnished to do so, subject to
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
92 the following conditions:
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
93
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
94 The above copyright notice and this permission notice shall be included
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
95 in all copies or substantial portions of the Software.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
96
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
97 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
98 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
99 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
100 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
101 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
102 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
e1309515d111 Add README file and manpages
Guido Berhoerster <guido+libpws@berhoerster.name>
parents:
diff changeset
103 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.