changeset 1:55281f14dc9b

Add README file and manpage
author Guido Berhoerster <guido+pwm@berhoerster.name>
date Fri, 03 Feb 2017 16:11:58 +0100
parents a7e41e1a79c8
children 5cd0debdb7d8
files Makefile README docbook-update-source-data.xsl pwm.1.xml
diffstat 4 files changed, 648 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/Makefile	Thu Jan 19 22:39:51 2017 +0100
+++ b/Makefile	Fri Feb 03 16:11:58 2017 +0100
@@ -44,10 +44,34 @@
 PAX :=		pax
 GZIP :=		gzip
 SED :=		sed
+XSLTPROC :=	xsltproc
+DOCBOOK5_MANPAGES_STYLESHEET =	http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
+DOCBOOK5_MANPAGES_FLAGS =	--stringparam man.authors.section.enabled 0 \
+				--stringparam man.copyright.section.enabled 0
+
+define generate-manpage-rule =
+$(addsuffix .%,$(basename $1)): $(addsuffix .%.xml,$(basename $(firstword $1))) docbook-update-source-data.xsl
+	$$(XSLTPROC) \
+	    --xinclude \
+	    --stringparam package $$(PACKAGE) \
+	    --stringparam version $$(VERSION) \
+	    docbook-update-source-data.xsl $$< | \
+	    $$(XSLTPROC) \
+	    --xinclude \
+	    --output $(firstword $1) \
+	    $$(DOCBOOK5_MANPAGES_FLAGS) \
+	    $$(DOCBOOK5_MANPAGES_STYLESHEET) \
+	    -
+	for alias in $(wordlist 2,$(words $1),$1); do \
+	    ln -sf $(notdir $(firstword $1)) $$$$alias; \
+	done
+endef
 
 DESTDIR ?=
 prefix ?=	/usr/local
 bindir ?=	$(prefix)/bin
+datadir ?=	$(prefix)/share
+mandir ?=	$(datadir)/man
 
 OS_NAME :=	$(shell uname -s)
 OS_RELEASE :=	$(shell uname -r)
@@ -101,11 +125,13 @@
 	tok.o \
 	util.o
 
+MANPAGES = pwm.1
+
 .DEFAULT_TARGET = all
 
 .PHONY: all clean clobber dist install
 
-all: $(PACKAGE)
+all: $(PACKAGE) $(MANPAGES)
 
 XCPPFLAGS =	-DPACKAGE=\"$(PACKAGE)\" \
 		-DVERSION=\"$(VERSION)\"
@@ -146,15 +172,26 @@
 $(PACKAGE): $(OBJS)
 	$(LINK.o) $^ $(LDLIBS) -o $@
 
+$(eval $(call generate-manpage-rule,$(MANPAGES)))
+
 %.o: %.c
 	$(MAKEDEPEND.c) $< | $(SED) -f deps.sed >$*.d
 	$(COMPILE.c) -o $@ $<
 
 install:
 	$(INSTALL.exec) $(PACKAGE) "$(DESTDIR)$(bindir)/$(PACKAGE)"
+	for manpage in $(MANPAGES); do \
+	    if [ -L $${manpage} ]; then \
+	        $(INSTALL.link) $${manpage} \
+	            "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
+	    else \
+	        $(INSTALL.data) $${manpage} \
+	            "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
+	    fi \
+	done
 
 clean:
-	rm -f $(PACKAGE) $(OBJS)
+	rm -f $(PACKAGE) $(OBJS) $(MANPAGES)
 
 clobber: clean
 	rm -f $(patsubst %.o,%.d,$(OBJS))
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Fri Feb 03 16:11:58 2017 +0100
@@ -0,0 +1,107 @@
+pwm
+===
+
+Description
+-----------
+
+The pwm utility is a password manager which stores passwords and associated
+metadata in an encrypted database protected by a master password.  It has a
+text-based user interface and can be used both interactively and
+non-interactively.  The database uses the PasswordSafe database format
+version 3 and is thus compatible with other password managers using this
+format.
+
+Build Instructions
+------------------
+
+pwm requires a POSIX:2004 compatible operating system, it has been tested to
+work on Linux distributions, FreeBSD, NetBSD, OpenBSD, Solaris and
+Illumos-derived distributions.  The following tools and shared libraries are
+required to build pwm:
+
+- GNU make >= 3.81
+- GNU or BSD install
+- libtecla >= 1.6.0
+- libpws >= 1.0.0
+
+Rebuilding the man pages additionally requires the xsltproc tool from libxml2.
+
+Before building pwm check the commented macros in the Makefile for any
+macros you may need to override depending on the used toolchain and operating
+system.
+
+By default, all files will be installed under the "/usr/local" directory, a
+different installation path prefix can be set via the `prefix` macro.  In
+addition, a second path prefix can be specified via the `DESTDIR` macro which
+will be prepended to any path, incuding the `prefix` macro path prefix.  In
+contrast to `prefix`, the path specified via the `DESTDIR` macro will only be
+prepended to paths during installation and not be used for constructing
+internal paths.
+
+The following instructions assume that `make` is GNU make, on some platforms
+it may be installed under a different name or a non-default path.  In order to
+start the build process run `make all`.  After a successful build, run `make
+install` to install the program, any associated data files and the
+documentation.
+
+Previously built binaries, object files, generated data files and
+documentation can be removed by running `make clean`, any additional,
+generated files which are not removed by the `clean` target can be removed by
+running `make clobber`.
+
+Contact
+-------
+
+Please send any feedback, translations or bug reports via email to
+<guido+pwm@berhoerster.name>.
+
+Bug Reports
+-----------
+
+When sending bug reports, please always mention the exact version of pwm
+with which the issue occurs as well as the version of the operating system you
+are using and make sure that you provide sufficient information to reproduce
+the issue and include any input, output, any error messages.
+
+In case of build issues, please also specify the implementations and versions
+of the tools and shared libraries used to build the program, in particular the
+compiler.
+
+In case of crashes, please generate a stack trace with a suitable debugger
+such as gdb, lldb, dbx, or debug after a crash has occurred either by
+examining the resulting core file or by running the program from the debugger
+and attach it to the bug report.  In order to generate a meaningful stack
+trace the program as well as any dynamically linked libraries need to be built
+with debugging information, see the documentation of the used compiler for the
+required compiler flags.  If any of the dynamically linked shared libraries do
+not contain debugging information, please either install debugging information
+for these libraries using mechanisms provided by your operating system or
+rebuild the libraries accordingly.  Please refer to the documentation of the
+debugger for detailed instructions on generating backtraces.
+
+License
+-------
+
+Except otherwise noted, all files are Copyright (C) 2017 Guido Berhoerster and
+distributed under the following license terms:
+
+Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docbook-update-source-data.xsl	Fri Feb 03 16:11:58 2017 +0100
@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<xsl:stylesheet
+  version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:db="http://docbook.org/ns/docbook"
+  xmlns="http://docbook.org/ns/docbook"
+  exclude-result-prefixes="xsl db">
+
+  <xsl:param name="package" select="''" />
+  <xsl:param name="version" select="''" />
+
+  <xsl:template match="db:refmeta/db:refmiscinfo[@class = 'source' or
+    @class = 'version']"/>
+
+  <xsl:template match="db:refmeta">
+    <xsl:copy>
+      <xsl:apply-templates/>
+      <refmiscinfo class="source"><xsl:value-of select="$package"/></refmiscinfo>
+      <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()"/>
+    </xsl:copy>
+  </xsl:template>
+
+</xsl:stylesheet>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pwm.1.xml	Fri Feb 03 16:11:58 2017 +0100
@@ -0,0 +1,473 @@
+<?xml version="1.0"?>
+<!--
+
+Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+<refentry xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
+  <info>
+    <author>
+      <personname>
+        <firstname>Guido</firstname>
+        <surname>Berhoerster</surname>
+      </personname>
+      <email>guido+pwm@berhoerster.name</email>
+      <personblurb/>
+    </author>
+    <date>3 February, 2017</date>
+  </info>
+  <refmeta>
+    <refentrytitle>pwm</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="source"/>
+    <refmiscinfo class="version"/>
+    <refmiscinfo class="manual">User Commands</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>pwm</refname>
+    <refpurpose>password manager</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>pwm</command>
+      <arg choice="opt">
+        <option>-P</option>
+        <replaceable>password_file</replaceable>
+      </arg>
+      <arg choice="opt">
+        <replaceable>database_file</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>Description</title>
+    <para>The <command>pwm</command> utility is a password manager which
+    stores passwords and associated metadata in an encrypted database protected
+    by a master password.  It offers both a text-based user interface for
+    interactive use as well as a non-interactive mode.  The database uses the
+    PasswordSafe database version 3 file format and thus provides
+    interoperabity with other password managers using the same format.</para>
+    <para>After opening an existing database or creating a new one,
+    <command>pwm</command> provides commands to create, modify, delete, and
+    display password database entries which may be organized in groups.  The
+    contents of a field of a given entry can also be piped to an external
+    command, e.g. in order to copy the content of the username or password
+    field of an entry to the clipboard.</para>
+    <para>If specified, <command>pwm</command> will open or create
+    <replaceable>database_file</replaceable> instead of the user's default
+    database.</para>
+    <para><command>pwm</command> must be run with a locale which uses the UTF-8
+    character encoding.</para>
+    <refsect2>
+      <title>Output format</title>
+      <para>The <command>show</command> command displays selected fields by
+      printing the field name followed by a colon, one or more space characters
+      and the field's verbatim content to the standard output stream. Field
+      values may contain newlines, non-printable and/or control
+      characters.</para>
+      <para>The <command>pipe</command> prints the verbatim field content to the
+      standard input stream of the given command.</para>
+      <para>Error messages are printed to the standard error stream.</para>
+    </refsect2>
+  </refsect1>
+  <refsect1>
+    <title>Options</title>
+    <para>The following options are supported:</para>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <option>-P</option>
+          <replaceable>password_file</replaceable>
+        </term>
+        <listitem>
+          <para>Read the master password from the first line of
+          <replaceable>password_file</replaceable>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Usage</title>
+    <para>If stdin is connected to a terminal pwm will run in interactive mode
+    and prompt the user for the master password unless
+    <replaceable>password_file</replaceable> is specified via the
+    <option>-P</option> option. After successfully opening the password
+    database the user will be prompted for a command.</para>
+    <para>When running in non-interactive mode a file containing the master
+    pasword must be specified via the <option>-P</option> option and after
+    successfully opening the password database, pwm will execute commands read
+    from stdin until either an error occurrs or end-of-file is reached.</para>
+    <para><command>pwm</command> operates on a copy of the password database
+    in memory, any changes must be explicitly written back to the database
+    using the write command.</para>
+    <refsect2>
+      <title>IDs</title>
+      <para>Database entries are referred to by an ID value which is a
+      positive integer value that is guaranteed to be unqiue during the run
+      time of the pwm utility.</para>
+    </refsect2>
+    <refsect2>
+      <title>Fields</title>
+      <para>The following entry fields are supported:
+      <simplelist type="vert">
+        <member>group</member>
+        <member>title</member>
+        <member>username</member>
+        <member>password</member>
+        <member>notes</member>
+        <member>url</member>
+      </simplelist>
+      </para>
+      <para>Other, existing fields specified by the PasswordSafe file format
+      will be preserved but cannot be displayed or modified.</para>
+    </refsect2>
+    <refsect2>
+      <title>Commands</title>
+      <para>Each command must appear on a seperate line terminated by a newline
+      character.  The command and its arguments are seperated by whitespace,
+      i.e. one or more space or tab characters.  If an argument contains
+      whitespace characters it must either be quoted by encosing it in single
+      or double quote characters or each whitespace character must be preceded
+      by a backslash character.  Arguments quoted with a single or double quote
+      character preserve the literal values of all characters with the
+      exception of the backslash character which can be used to escape the
+      respective quoting character.  Two consecutive backslash characters yield
+      a literal backslash within both quoted and unquoted arguments. A line
+      must not end in a single backslash character, any other backslash
+      characters are ignored.</para>
+      <para>If an error occurrs while parsing or executing a command,
+      <command>pwm</command> will terminate when running in non-interactive
+      mode.  In interactive mode it will print an error message and prompt the
+      user for the next command.  The following commands are supported:</para>
+      <variablelist>
+        <varlistentry>
+          <term>List entries</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>list</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>ls</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>List all password database entries.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Create entry</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>create</command>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>=<replaceable>value</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>c</command>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>=<replaceable>value</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Create a new entry assigning each given
+            <replaceable>field</replaceable> to the corresponsing
+            <replaceable>value</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Modify entry</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>modify</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>=<replaceable>value</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>m</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>=<replaceable>value</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Modify an existing entry identified by
+            <replaceable>id</replaceable> assigning each given
+            <replaceable>field</replaceable> to the corresponsing
+            <replaceable>value</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Remove entry</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>remove</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>rm</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Remove an existing entry identified by
+            <replaceable>id</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Display entry fields</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>show</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>s</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Display each <replaceable>field</replaceable> of the entry
+            identified by <replaceable>id</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Pipe entry fields to an external command</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>pipe</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="plain" rep="repeat">
+                <replaceable>field</replaceable>
+              </arg>
+              <arg choice="plain">
+                <replaceable>command</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>p</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="plain" rep="repeat">
+                <replaceable>field</replaceable>
+              </arg>
+              <arg choice="plain">
+                <replaceable>command</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Pipe the content of each given
+            <replaceable>field</replaceable> of the entry identified by id to
+            command which must be a single argument. The command is executed by
+            invoking the <command>sh</command> utility with the <arg>-c</arg>
+            option and <replaceable>command</replaceable> as its option
+            argument, thus special care should be applied to quoting command.
+            See the <citerefentry><refentrytitle>sh</refentrytitle>
+            <manvolnum>1</manvolnum></citerefentry> manual page for
+            details.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Create empty group</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>creategroup</command>
+              <arg choice="plain">
+                <replaceable>name</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>cg</command>
+              <arg choice="plain">
+                <replaceable>name</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Create a new empty group named
+            <replaceable>name</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Remove empty group</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>removegroup</command>
+              <arg choice="plain">
+                <replaceable>name</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>rg</command>
+              <arg choice="plain">
+                <replaceable>name</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Remove the empty group named
+            <replaceable>name</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Change the master password</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>changepassword</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>ch</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Change the master password.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Display help text</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>help</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>h</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Display a list of all commands and a short help text.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Write database</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>write</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>w</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Write all changes back to the password database.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Quit</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>quit</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>q</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Quit <command>pwm</command>.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+  </refsect1>
+  <refsect1>
+    <title>File Format</title>
+    <para>The canonical description of the file format is included with the
+    distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle>
+    <manvolnum>1</manvolnum></citerefentry> utility.</para>
+  </refsect1>
+  <refsect1>
+    <title>Environment Variables</title>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <literal>LANG</literal>
+        </term>
+        <term>
+          <literal>LC_ALL</literal>
+        </term>
+        <listitem>
+          <para>See <citerefentry><refentrytitle>locale</refentrytitle>
+          <manvolnum>5</manvolnum></citerefentry></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Exit Status</title>
+    <para>The following exit values are returned:</para>
+    <variablelist>
+      <varlistentry>
+        <term>0</term>
+        <listitem>
+          <para>Command successfully executed.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>1</term>
+        <listitem>
+          <para>An unspecified error has occured.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>2</term>
+        <listitem>
+          <para>Invalid command line options were specified.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Files</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>~/.pwm/pwm.psafe3</filename></term>
+        <listitem>
+          <para>default password database</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>See Also</title>
+    <para><citerefentry><refentrytitle>pwsafe</refentrytitle>
+      <manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sh</refentrytitle>
+      <manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>locale</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry>,
+      <link xlink:href="https://pwsafe.org/"/></para>
+  </refsect1>
+</refentry>