projects/pwm

changeset 1:55281f14dc9b

Add README file and manpage
author Guido Berhoerster <guido+pwm@berhoerster.name>
date Fri Feb 03 16:11:58 2017 +0100 (2017-02-03)
parents a7e41e1a79c8
children 5cd0debdb7d8
files Makefile README docbook-update-source-data.xsl pwm.1.xml
line diff
     1.1 --- a/Makefile	Thu Jan 19 22:39:51 2017 +0100
     1.2 +++ b/Makefile	Fri Feb 03 16:11:58 2017 +0100
     1.3 @@ -44,10 +44,34 @@
     1.4  PAX :=		pax
     1.5  GZIP :=		gzip
     1.6  SED :=		sed
     1.7 +XSLTPROC :=	xsltproc
     1.8 +DOCBOOK5_MANPAGES_STYLESHEET =	http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
     1.9 +DOCBOOK5_MANPAGES_FLAGS =	--stringparam man.authors.section.enabled 0 \
    1.10 +				--stringparam man.copyright.section.enabled 0
    1.11 +
    1.12 +define generate-manpage-rule =
    1.13 +$(addsuffix .%,$(basename $1)): $(addsuffix .%.xml,$(basename $(firstword $1))) docbook-update-source-data.xsl
    1.14 +	$$(XSLTPROC) \
    1.15 +	    --xinclude \
    1.16 +	    --stringparam package $$(PACKAGE) \
    1.17 +	    --stringparam version $$(VERSION) \
    1.18 +	    docbook-update-source-data.xsl $$< | \
    1.19 +	    $$(XSLTPROC) \
    1.20 +	    --xinclude \
    1.21 +	    --output $(firstword $1) \
    1.22 +	    $$(DOCBOOK5_MANPAGES_FLAGS) \
    1.23 +	    $$(DOCBOOK5_MANPAGES_STYLESHEET) \
    1.24 +	    -
    1.25 +	for alias in $(wordlist 2,$(words $1),$1); do \
    1.26 +	    ln -sf $(notdir $(firstword $1)) $$$$alias; \
    1.27 +	done
    1.28 +endef
    1.29  
    1.30  DESTDIR ?=
    1.31  prefix ?=	/usr/local
    1.32  bindir ?=	$(prefix)/bin
    1.33 +datadir ?=	$(prefix)/share
    1.34 +mandir ?=	$(datadir)/man
    1.35  
    1.36  OS_NAME :=	$(shell uname -s)
    1.37  OS_RELEASE :=	$(shell uname -r)
    1.38 @@ -101,11 +125,13 @@
    1.39  	tok.o \
    1.40  	util.o
    1.41  
    1.42 +MANPAGES = pwm.1
    1.43 +
    1.44  .DEFAULT_TARGET = all
    1.45  
    1.46  .PHONY: all clean clobber dist install
    1.47  
    1.48 -all: $(PACKAGE)
    1.49 +all: $(PACKAGE) $(MANPAGES)
    1.50  
    1.51  XCPPFLAGS =	-DPACKAGE=\"$(PACKAGE)\" \
    1.52  		-DVERSION=\"$(VERSION)\"
    1.53 @@ -146,15 +172,26 @@
    1.54  $(PACKAGE): $(OBJS)
    1.55  	$(LINK.o) $^ $(LDLIBS) -o $@
    1.56  
    1.57 +$(eval $(call generate-manpage-rule,$(MANPAGES)))
    1.58 +
    1.59  %.o: %.c
    1.60  	$(MAKEDEPEND.c) $< | $(SED) -f deps.sed >$*.d
    1.61  	$(COMPILE.c) -o $@ $<
    1.62  
    1.63  install:
    1.64  	$(INSTALL.exec) $(PACKAGE) "$(DESTDIR)$(bindir)/$(PACKAGE)"
    1.65 +	for manpage in $(MANPAGES); do \
    1.66 +	    if [ -L $${manpage} ]; then \
    1.67 +	        $(INSTALL.link) $${manpage} \
    1.68 +	            "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
    1.69 +	    else \
    1.70 +	        $(INSTALL.data) $${manpage} \
    1.71 +	            "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
    1.72 +	    fi \
    1.73 +	done
    1.74  
    1.75  clean:
    1.76 -	rm -f $(PACKAGE) $(OBJS)
    1.77 +	rm -f $(PACKAGE) $(OBJS) $(MANPAGES)
    1.78  
    1.79  clobber: clean
    1.80  	rm -f $(patsubst %.o,%.d,$(OBJS))
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/README	Fri Feb 03 16:11:58 2017 +0100
     2.3 @@ -0,0 +1,107 @@
     2.4 +pwm
     2.5 +===
     2.6 +
     2.7 +Description
     2.8 +-----------
     2.9 +
    2.10 +The pwm utility is a password manager which stores passwords and associated
    2.11 +metadata in an encrypted database protected by a master password.  It has a
    2.12 +text-based user interface and can be used both interactively and
    2.13 +non-interactively.  The database uses the PasswordSafe database format
    2.14 +version 3 and is thus compatible with other password managers using this
    2.15 +format.
    2.16 +
    2.17 +Build Instructions
    2.18 +------------------
    2.19 +
    2.20 +pwm requires a POSIX:2004 compatible operating system, it has been tested to
    2.21 +work on Linux distributions, FreeBSD, NetBSD, OpenBSD, Solaris and
    2.22 +Illumos-derived distributions.  The following tools and shared libraries are
    2.23 +required to build pwm:
    2.24 +
    2.25 +- GNU make >= 3.81
    2.26 +- GNU or BSD install
    2.27 +- libtecla >= 1.6.0
    2.28 +- libpws >= 1.0.0
    2.29 +
    2.30 +Rebuilding the man pages additionally requires the xsltproc tool from libxml2.
    2.31 +
    2.32 +Before building pwm check the commented macros in the Makefile for any
    2.33 +macros you may need to override depending on the used toolchain and operating
    2.34 +system.
    2.35 +
    2.36 +By default, all files will be installed under the "/usr/local" directory, a
    2.37 +different installation path prefix can be set via the `prefix` macro.  In
    2.38 +addition, a second path prefix can be specified via the `DESTDIR` macro which
    2.39 +will be prepended to any path, incuding the `prefix` macro path prefix.  In
    2.40 +contrast to `prefix`, the path specified via the `DESTDIR` macro will only be
    2.41 +prepended to paths during installation and not be used for constructing
    2.42 +internal paths.
    2.43 +
    2.44 +The following instructions assume that `make` is GNU make, on some platforms
    2.45 +it may be installed under a different name or a non-default path.  In order to
    2.46 +start the build process run `make all`.  After a successful build, run `make
    2.47 +install` to install the program, any associated data files and the
    2.48 +documentation.
    2.49 +
    2.50 +Previously built binaries, object files, generated data files and
    2.51 +documentation can be removed by running `make clean`, any additional,
    2.52 +generated files which are not removed by the `clean` target can be removed by
    2.53 +running `make clobber`.
    2.54 +
    2.55 +Contact
    2.56 +-------
    2.57 +
    2.58 +Please send any feedback, translations or bug reports via email to
    2.59 +<guido+pwm@berhoerster.name>.
    2.60 +
    2.61 +Bug Reports
    2.62 +-----------
    2.63 +
    2.64 +When sending bug reports, please always mention the exact version of pwm
    2.65 +with which the issue occurs as well as the version of the operating system you
    2.66 +are using and make sure that you provide sufficient information to reproduce
    2.67 +the issue and include any input, output, any error messages.
    2.68 +
    2.69 +In case of build issues, please also specify the implementations and versions
    2.70 +of the tools and shared libraries used to build the program, in particular the
    2.71 +compiler.
    2.72 +
    2.73 +In case of crashes, please generate a stack trace with a suitable debugger
    2.74 +such as gdb, lldb, dbx, or debug after a crash has occurred either by
    2.75 +examining the resulting core file or by running the program from the debugger
    2.76 +and attach it to the bug report.  In order to generate a meaningful stack
    2.77 +trace the program as well as any dynamically linked libraries need to be built
    2.78 +with debugging information, see the documentation of the used compiler for the
    2.79 +required compiler flags.  If any of the dynamically linked shared libraries do
    2.80 +not contain debugging information, please either install debugging information
    2.81 +for these libraries using mechanisms provided by your operating system or
    2.82 +rebuild the libraries accordingly.  Please refer to the documentation of the
    2.83 +debugger for detailed instructions on generating backtraces.
    2.84 +
    2.85 +License
    2.86 +-------
    2.87 +
    2.88 +Except otherwise noted, all files are Copyright (C) 2017 Guido Berhoerster and
    2.89 +distributed under the following license terms:
    2.90 +
    2.91 +Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
    2.92 +
    2.93 +Permission is hereby granted, free of charge, to any person obtaining
    2.94 +a copy of this software and associated documentation files (the
    2.95 +"Software"), to deal in the Software without restriction, including
    2.96 +without limitation the rights to use, copy, modify, merge, publish,
    2.97 +distribute, sublicense, and/or sell copies of the Software, and to
    2.98 +permit persons to whom the Software is furnished to do so, subject to
    2.99 +the following conditions:
   2.100 +
   2.101 +The above copyright notice and this permission notice shall be included
   2.102 +in all copies or substantial portions of the Software.
   2.103 +
   2.104 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   2.105 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   2.106 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   2.107 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   2.108 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   2.109 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
   2.110 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/docbook-update-source-data.xsl	Fri Feb 03 16:11:58 2017 +0100
     3.3 @@ -0,0 +1,29 @@
     3.4 +<?xml version="1.0"?>
     3.5 +<xsl:stylesheet
     3.6 +  version="1.0"
     3.7 +  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     3.8 +  xmlns:db="http://docbook.org/ns/docbook"
     3.9 +  xmlns="http://docbook.org/ns/docbook"
    3.10 +  exclude-result-prefixes="xsl db">
    3.11 +
    3.12 +  <xsl:param name="package" select="''" />
    3.13 +  <xsl:param name="version" select="''" />
    3.14 +
    3.15 +  <xsl:template match="db:refmeta/db:refmiscinfo[@class = 'source' or
    3.16 +    @class = 'version']"/>
    3.17 +
    3.18 +  <xsl:template match="db:refmeta">
    3.19 +    <xsl:copy>
    3.20 +      <xsl:apply-templates/>
    3.21 +      <refmiscinfo class="source"><xsl:value-of select="$package"/></refmiscinfo>
    3.22 +      <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
    3.23 +    </xsl:copy>
    3.24 +  </xsl:template>
    3.25 +
    3.26 +  <xsl:template match="@*|node()">
    3.27 +    <xsl:copy>
    3.28 +      <xsl:apply-templates select="@*|node()"/>
    3.29 +    </xsl:copy>
    3.30 +  </xsl:template>
    3.31 +
    3.32 +</xsl:stylesheet>
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/pwm.1.xml	Fri Feb 03 16:11:58 2017 +0100
     4.3 @@ -0,0 +1,473 @@
     4.4 +<?xml version="1.0"?>
     4.5 +<!--
     4.6 +
     4.7 +Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
     4.8 +
     4.9 +Permission is hereby granted, free of charge, to any person obtaining
    4.10 +a copy of this software and associated documentation files (the
    4.11 +"Software"), to deal in the Software without restriction, including
    4.12 +without limitation the rights to use, copy, modify, merge, publish,
    4.13 +distribute, sublicense, and/or sell copies of the Software, and to
    4.14 +permit persons to whom the Software is furnished to do so, subject to
    4.15 +the following conditions:
    4.16 +
    4.17 +The above copyright notice and this permission notice shall be included
    4.18 +in all copies or substantial portions of the Software.
    4.19 +
    4.20 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    4.21 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    4.22 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    4.23 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    4.24 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    4.25 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    4.26 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    4.27 +
    4.28 +-->
    4.29 +<refentry xmlns="http://docbook.org/ns/docbook"
    4.30 +  xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
    4.31 +  <info>
    4.32 +    <author>
    4.33 +      <personname>
    4.34 +        <firstname>Guido</firstname>
    4.35 +        <surname>Berhoerster</surname>
    4.36 +      </personname>
    4.37 +      <email>guido+pwm@berhoerster.name</email>
    4.38 +      <personblurb/>
    4.39 +    </author>
    4.40 +    <date>3 February, 2017</date>
    4.41 +  </info>
    4.42 +  <refmeta>
    4.43 +    <refentrytitle>pwm</refentrytitle>
    4.44 +    <manvolnum>1</manvolnum>
    4.45 +    <refmiscinfo class="source"/>
    4.46 +    <refmiscinfo class="version"/>
    4.47 +    <refmiscinfo class="manual">User Commands</refmiscinfo>
    4.48 +  </refmeta>
    4.49 +  <refnamediv>
    4.50 +    <refname>pwm</refname>
    4.51 +    <refpurpose>password manager</refpurpose>
    4.52 +  </refnamediv>
    4.53 +  <refsynopsisdiv>
    4.54 +    <cmdsynopsis>
    4.55 +      <command>pwm</command>
    4.56 +      <arg choice="opt">
    4.57 +        <option>-P</option>
    4.58 +        <replaceable>password_file</replaceable>
    4.59 +      </arg>
    4.60 +      <arg choice="opt">
    4.61 +        <replaceable>database_file</replaceable>
    4.62 +      </arg>
    4.63 +    </cmdsynopsis>
    4.64 +  </refsynopsisdiv>
    4.65 +  <refsect1>
    4.66 +    <title>Description</title>
    4.67 +    <para>The <command>pwm</command> utility is a password manager which
    4.68 +    stores passwords and associated metadata in an encrypted database protected
    4.69 +    by a master password.  It offers both a text-based user interface for
    4.70 +    interactive use as well as a non-interactive mode.  The database uses the
    4.71 +    PasswordSafe database version 3 file format and thus provides
    4.72 +    interoperabity with other password managers using the same format.</para>
    4.73 +    <para>After opening an existing database or creating a new one,
    4.74 +    <command>pwm</command> provides commands to create, modify, delete, and
    4.75 +    display password database entries which may be organized in groups.  The
    4.76 +    contents of a field of a given entry can also be piped to an external
    4.77 +    command, e.g. in order to copy the content of the username or password
    4.78 +    field of an entry to the clipboard.</para>
    4.79 +    <para>If specified, <command>pwm</command> will open or create
    4.80 +    <replaceable>database_file</replaceable> instead of the user's default
    4.81 +    database.</para>
    4.82 +    <para><command>pwm</command> must be run with a locale which uses the UTF-8
    4.83 +    character encoding.</para>
    4.84 +    <refsect2>
    4.85 +      <title>Output format</title>
    4.86 +      <para>The <command>show</command> command displays selected fields by
    4.87 +      printing the field name followed by a colon, one or more space characters
    4.88 +      and the field's verbatim content to the standard output stream. Field
    4.89 +      values may contain newlines, non-printable and/or control
    4.90 +      characters.</para>
    4.91 +      <para>The <command>pipe</command> prints the verbatim field content to the
    4.92 +      standard input stream of the given command.</para>
    4.93 +      <para>Error messages are printed to the standard error stream.</para>
    4.94 +    </refsect2>
    4.95 +  </refsect1>
    4.96 +  <refsect1>
    4.97 +    <title>Options</title>
    4.98 +    <para>The following options are supported:</para>
    4.99 +    <variablelist>
   4.100 +      <varlistentry>
   4.101 +        <term>
   4.102 +          <option>-P</option>
   4.103 +          <replaceable>password_file</replaceable>
   4.104 +        </term>
   4.105 +        <listitem>
   4.106 +          <para>Read the master password from the first line of
   4.107 +          <replaceable>password_file</replaceable>.</para>
   4.108 +        </listitem>
   4.109 +      </varlistentry>
   4.110 +    </variablelist>
   4.111 +  </refsect1>
   4.112 +  <refsect1>
   4.113 +    <title>Usage</title>
   4.114 +    <para>If stdin is connected to a terminal pwm will run in interactive mode
   4.115 +    and prompt the user for the master password unless
   4.116 +    <replaceable>password_file</replaceable> is specified via the
   4.117 +    <option>-P</option> option. After successfully opening the password
   4.118 +    database the user will be prompted for a command.</para>
   4.119 +    <para>When running in non-interactive mode a file containing the master
   4.120 +    pasword must be specified via the <option>-P</option> option and after
   4.121 +    successfully opening the password database, pwm will execute commands read
   4.122 +    from stdin until either an error occurrs or end-of-file is reached.</para>
   4.123 +    <para><command>pwm</command> operates on a copy of the password database
   4.124 +    in memory, any changes must be explicitly written back to the database
   4.125 +    using the write command.</para>
   4.126 +    <refsect2>
   4.127 +      <title>IDs</title>
   4.128 +      <para>Database entries are referred to by an ID value which is a
   4.129 +      positive integer value that is guaranteed to be unqiue during the run
   4.130 +      time of the pwm utility.</para>
   4.131 +    </refsect2>
   4.132 +    <refsect2>
   4.133 +      <title>Fields</title>
   4.134 +      <para>The following entry fields are supported:
   4.135 +      <simplelist type="vert">
   4.136 +        <member>group</member>
   4.137 +        <member>title</member>
   4.138 +        <member>username</member>
   4.139 +        <member>password</member>
   4.140 +        <member>notes</member>
   4.141 +        <member>url</member>
   4.142 +      </simplelist>
   4.143 +      </para>
   4.144 +      <para>Other, existing fields specified by the PasswordSafe file format
   4.145 +      will be preserved but cannot be displayed or modified.</para>
   4.146 +    </refsect2>
   4.147 +    <refsect2>
   4.148 +      <title>Commands</title>
   4.149 +      <para>Each command must appear on a seperate line terminated by a newline
   4.150 +      character.  The command and its arguments are seperated by whitespace,
   4.151 +      i.e. one or more space or tab characters.  If an argument contains
   4.152 +      whitespace characters it must either be quoted by encosing it in single
   4.153 +      or double quote characters or each whitespace character must be preceded
   4.154 +      by a backslash character.  Arguments quoted with a single or double quote
   4.155 +      character preserve the literal values of all characters with the
   4.156 +      exception of the backslash character which can be used to escape the
   4.157 +      respective quoting character.  Two consecutive backslash characters yield
   4.158 +      a literal backslash within both quoted and unquoted arguments. A line
   4.159 +      must not end in a single backslash character, any other backslash
   4.160 +      characters are ignored.</para>
   4.161 +      <para>If an error occurrs while parsing or executing a command,
   4.162 +      <command>pwm</command> will terminate when running in non-interactive
   4.163 +      mode.  In interactive mode it will print an error message and prompt the
   4.164 +      user for the next command.  The following commands are supported:</para>
   4.165 +      <variablelist>
   4.166 +        <varlistentry>
   4.167 +          <term>List entries</term>
   4.168 +          <listitem>
   4.169 +            <cmdsynopsis>
   4.170 +              <command>list</command>
   4.171 +            </cmdsynopsis>
   4.172 +            <cmdsynopsis>
   4.173 +              <command>ls</command>
   4.174 +              <sbr/>
   4.175 +            </cmdsynopsis>
   4.176 +            <para>List all password database entries.</para>
   4.177 +          </listitem>
   4.178 +        </varlistentry>
   4.179 +        <varlistentry>
   4.180 +          <term>Create entry</term>
   4.181 +          <listitem>
   4.182 +            <cmdsynopsis>
   4.183 +              <command>create</command>
   4.184 +              <arg choice="opt" rep="repeat">
   4.185 +                <replaceable>field</replaceable>=<replaceable>value</replaceable>
   4.186 +              </arg>
   4.187 +            </cmdsynopsis>
   4.188 +            <cmdsynopsis>
   4.189 +              <command>c</command>
   4.190 +              <arg choice="opt" rep="repeat">
   4.191 +                <replaceable>field</replaceable>=<replaceable>value</replaceable>
   4.192 +              </arg>
   4.193 +              <sbr/>
   4.194 +            </cmdsynopsis>
   4.195 +            <para>Create a new entry assigning each given
   4.196 +            <replaceable>field</replaceable> to the corresponsing
   4.197 +            <replaceable>value</replaceable>.</para>
   4.198 +          </listitem>
   4.199 +        </varlistentry>
   4.200 +        <varlistentry>
   4.201 +          <term>Modify entry</term>
   4.202 +          <listitem>
   4.203 +            <cmdsynopsis>
   4.204 +              <command>modify</command>
   4.205 +              <arg choice="plain">
   4.206 +                <replaceable>id</replaceable>
   4.207 +              </arg>
   4.208 +              <arg choice="opt" rep="repeat">
   4.209 +                <replaceable>field</replaceable>=<replaceable>value</replaceable>
   4.210 +              </arg>
   4.211 +            </cmdsynopsis>
   4.212 +            <cmdsynopsis>
   4.213 +              <command>m</command>
   4.214 +              <arg choice="plain">
   4.215 +                <replaceable>id</replaceable>
   4.216 +              </arg>
   4.217 +              <arg choice="opt" rep="repeat">
   4.218 +                <replaceable>field</replaceable>=<replaceable>value</replaceable>
   4.219 +              </arg>
   4.220 +              <sbr/>
   4.221 +            </cmdsynopsis>
   4.222 +            <para>Modify an existing entry identified by
   4.223 +            <replaceable>id</replaceable> assigning each given
   4.224 +            <replaceable>field</replaceable> to the corresponsing
   4.225 +            <replaceable>value</replaceable>.</para>
   4.226 +          </listitem>
   4.227 +        </varlistentry>
   4.228 +        <varlistentry>
   4.229 +          <term>Remove entry</term>
   4.230 +          <listitem>
   4.231 +            <cmdsynopsis>
   4.232 +              <command>remove</command>
   4.233 +              <arg choice="plain">
   4.234 +                <replaceable>id</replaceable>
   4.235 +              </arg>
   4.236 +            </cmdsynopsis>
   4.237 +            <cmdsynopsis>
   4.238 +              <command>rm</command>
   4.239 +              <arg choice="plain">
   4.240 +                <replaceable>id</replaceable>
   4.241 +              </arg>
   4.242 +              <sbr/>
   4.243 +            </cmdsynopsis>
   4.244 +            <para>Remove an existing entry identified by
   4.245 +            <replaceable>id</replaceable>.</para>
   4.246 +          </listitem>
   4.247 +        </varlistentry>
   4.248 +        <varlistentry>
   4.249 +          <term>Display entry fields</term>
   4.250 +          <listitem>
   4.251 +            <cmdsynopsis>
   4.252 +              <command>show</command>
   4.253 +              <arg choice="plain">
   4.254 +                <replaceable>id</replaceable>
   4.255 +              </arg>
   4.256 +              <arg choice="opt" rep="repeat">
   4.257 +                <replaceable>field</replaceable>
   4.258 +              </arg>
   4.259 +            </cmdsynopsis>
   4.260 +            <cmdsynopsis>
   4.261 +              <command>s</command>
   4.262 +              <arg choice="plain">
   4.263 +                <replaceable>id</replaceable>
   4.264 +              </arg>
   4.265 +              <arg choice="opt" rep="repeat">
   4.266 +                <replaceable>field</replaceable>
   4.267 +              </arg>
   4.268 +              <sbr/>
   4.269 +            </cmdsynopsis>
   4.270 +            <para>Display each <replaceable>field</replaceable> of the entry
   4.271 +            identified by <replaceable>id</replaceable>.</para>
   4.272 +          </listitem>
   4.273 +        </varlistentry>
   4.274 +        <varlistentry>
   4.275 +          <term>Pipe entry fields to an external command</term>
   4.276 +          <listitem>
   4.277 +            <cmdsynopsis>
   4.278 +              <command>pipe</command>
   4.279 +              <arg choice="plain">
   4.280 +                <replaceable>id</replaceable>
   4.281 +              </arg>
   4.282 +              <arg choice="plain" rep="repeat">
   4.283 +                <replaceable>field</replaceable>
   4.284 +              </arg>
   4.285 +              <arg choice="plain">
   4.286 +                <replaceable>command</replaceable>
   4.287 +              </arg>
   4.288 +            </cmdsynopsis>
   4.289 +            <cmdsynopsis>
   4.290 +              <command>p</command>
   4.291 +              <arg choice="plain">
   4.292 +                <replaceable>id</replaceable>
   4.293 +              </arg>
   4.294 +              <arg choice="plain" rep="repeat">
   4.295 +                <replaceable>field</replaceable>
   4.296 +              </arg>
   4.297 +              <arg choice="plain">
   4.298 +                <replaceable>command</replaceable>
   4.299 +              </arg>
   4.300 +              <sbr/>
   4.301 +            </cmdsynopsis>
   4.302 +            <para>Pipe the content of each given
   4.303 +            <replaceable>field</replaceable> of the entry identified by id to
   4.304 +            command which must be a single argument. The command is executed by
   4.305 +            invoking the <command>sh</command> utility with the <arg>-c</arg>
   4.306 +            option and <replaceable>command</replaceable> as its option
   4.307 +            argument, thus special care should be applied to quoting command.
   4.308 +            See the <citerefentry><refentrytitle>sh</refentrytitle>
   4.309 +            <manvolnum>1</manvolnum></citerefentry> manual page for
   4.310 +            details.</para>
   4.311 +          </listitem>
   4.312 +        </varlistentry>
   4.313 +        <varlistentry>
   4.314 +          <term>Create empty group</term>
   4.315 +          <listitem>
   4.316 +            <cmdsynopsis>
   4.317 +              <command>creategroup</command>
   4.318 +              <arg choice="plain">
   4.319 +                <replaceable>name</replaceable>
   4.320 +              </arg>
   4.321 +            </cmdsynopsis>
   4.322 +            <cmdsynopsis>
   4.323 +              <command>cg</command>
   4.324 +              <arg choice="plain">
   4.325 +                <replaceable>name</replaceable>
   4.326 +              </arg>
   4.327 +              <sbr/>
   4.328 +            </cmdsynopsis>
   4.329 +            <para>Create a new empty group named
   4.330 +            <replaceable>name</replaceable>.</para>
   4.331 +          </listitem>
   4.332 +        </varlistentry>
   4.333 +        <varlistentry>
   4.334 +          <term>Remove empty group</term>
   4.335 +          <listitem>
   4.336 +            <cmdsynopsis>
   4.337 +              <command>removegroup</command>
   4.338 +              <arg choice="plain">
   4.339 +                <replaceable>name</replaceable>
   4.340 +              </arg>
   4.341 +            </cmdsynopsis>
   4.342 +            <cmdsynopsis>
   4.343 +              <command>rg</command>
   4.344 +              <arg choice="plain">
   4.345 +                <replaceable>name</replaceable>
   4.346 +              </arg>
   4.347 +              <sbr/>
   4.348 +            </cmdsynopsis>
   4.349 +            <para>Remove the empty group named
   4.350 +            <replaceable>name</replaceable>.</para>
   4.351 +          </listitem>
   4.352 +        </varlistentry>
   4.353 +        <varlistentry>
   4.354 +          <term>Change the master password</term>
   4.355 +          <listitem>
   4.356 +            <cmdsynopsis>
   4.357 +              <command>changepassword</command>
   4.358 +            </cmdsynopsis>
   4.359 +            <cmdsynopsis>
   4.360 +              <command>ch</command>
   4.361 +              <sbr/>
   4.362 +            </cmdsynopsis>
   4.363 +            <para>Change the master password.</para>
   4.364 +          </listitem>
   4.365 +        </varlistentry>
   4.366 +        <varlistentry>
   4.367 +          <term>Display help text</term>
   4.368 +          <listitem>
   4.369 +            <cmdsynopsis>
   4.370 +              <command>help</command>
   4.371 +            </cmdsynopsis>
   4.372 +            <cmdsynopsis>
   4.373 +              <command>h</command>
   4.374 +              <sbr/>
   4.375 +            </cmdsynopsis>
   4.376 +            <para>Display a list of all commands and a short help text.</para>
   4.377 +          </listitem>
   4.378 +        </varlistentry>
   4.379 +        <varlistentry>
   4.380 +          <term>Write database</term>
   4.381 +          <listitem>
   4.382 +            <cmdsynopsis>
   4.383 +              <command>write</command>
   4.384 +            </cmdsynopsis>
   4.385 +            <cmdsynopsis>
   4.386 +              <command>w</command>
   4.387 +              <sbr/>
   4.388 +            </cmdsynopsis>
   4.389 +            <para>Write all changes back to the password database.</para>
   4.390 +          </listitem>
   4.391 +        </varlistentry>
   4.392 +        <varlistentry>
   4.393 +          <term>Quit</term>
   4.394 +          <listitem>
   4.395 +            <cmdsynopsis>
   4.396 +              <command>quit</command>
   4.397 +            </cmdsynopsis>
   4.398 +            <cmdsynopsis>
   4.399 +              <command>q</command>
   4.400 +              <sbr/>
   4.401 +            </cmdsynopsis>
   4.402 +            <para>Quit <command>pwm</command>.</para>
   4.403 +          </listitem>
   4.404 +        </varlistentry>
   4.405 +      </variablelist>
   4.406 +    </refsect2>
   4.407 +  </refsect1>
   4.408 +  <refsect1>
   4.409 +    <title>File Format</title>
   4.410 +    <para>The canonical description of the file format is included with the
   4.411 +    distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle>
   4.412 +    <manvolnum>1</manvolnum></citerefentry> utility.</para>
   4.413 +  </refsect1>
   4.414 +  <refsect1>
   4.415 +    <title>Environment Variables</title>
   4.416 +    <variablelist>
   4.417 +      <varlistentry>
   4.418 +        <term>
   4.419 +          <literal>LANG</literal>
   4.420 +        </term>
   4.421 +        <term>
   4.422 +          <literal>LC_ALL</literal>
   4.423 +        </term>
   4.424 +        <listitem>
   4.425 +          <para>See <citerefentry><refentrytitle>locale</refentrytitle>
   4.426 +          <manvolnum>5</manvolnum></citerefentry></para>
   4.427 +        </listitem>
   4.428 +      </varlistentry>
   4.429 +    </variablelist>
   4.430 +  </refsect1>
   4.431 +  <refsect1>
   4.432 +    <title>Exit Status</title>
   4.433 +    <para>The following exit values are returned:</para>
   4.434 +    <variablelist>
   4.435 +      <varlistentry>
   4.436 +        <term>0</term>
   4.437 +        <listitem>
   4.438 +          <para>Command successfully executed.</para>
   4.439 +        </listitem>
   4.440 +      </varlistentry>
   4.441 +      <varlistentry>
   4.442 +        <term>1</term>
   4.443 +        <listitem>
   4.444 +          <para>An unspecified error has occured.</para>
   4.445 +        </listitem>
   4.446 +      </varlistentry>
   4.447 +      <varlistentry>
   4.448 +        <term>2</term>
   4.449 +        <listitem>
   4.450 +          <para>Invalid command line options were specified.</para>
   4.451 +        </listitem>
   4.452 +      </varlistentry>
   4.453 +    </variablelist>
   4.454 +  </refsect1>
   4.455 +  <refsect1>
   4.456 +    <title>Files</title>
   4.457 +    <variablelist>
   4.458 +      <varlistentry>
   4.459 +        <term><filename>~/.pwm/pwm.psafe3</filename></term>
   4.460 +        <listitem>
   4.461 +          <para>default password database</para>
   4.462 +        </listitem>
   4.463 +      </varlistentry>
   4.464 +    </variablelist>
   4.465 +  </refsect1>
   4.466 +  <refsect1>
   4.467 +    <title>See Also</title>
   4.468 +    <para><citerefentry><refentrytitle>pwsafe</refentrytitle>
   4.469 +      <manvolnum>1</manvolnum></citerefentry>,
   4.470 +      <citerefentry><refentrytitle>sh</refentrytitle>
   4.471 +      <manvolnum>1</manvolnum></citerefentry>,
   4.472 +      <citerefentry><refentrytitle>locale</refentrytitle>
   4.473 +      <manvolnum>5</manvolnum></citerefentry>,
   4.474 +      <link xlink:href="https://pwsafe.org/"/></para>
   4.475 +  </refsect1>
   4.476 +</refentry>