guido+pwm@1: <?xml version="1.0"?>
guido+pwm@1: <!--
guido+pwm@1: 
guido+pwm@1: Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
guido+pwm@1: 
guido+pwm@1: Permission is hereby granted, free of charge, to any person obtaining
guido+pwm@1: a copy of this software and associated documentation files (the
guido+pwm@1: "Software"), to deal in the Software without restriction, including
guido+pwm@1: without limitation the rights to use, copy, modify, merge, publish,
guido+pwm@1: distribute, sublicense, and/or sell copies of the Software, and to
guido+pwm@1: permit persons to whom the Software is furnished to do so, subject to
guido+pwm@1: the following conditions:
guido+pwm@1: 
guido+pwm@1: The above copyright notice and this permission notice shall be included
guido+pwm@1: in all copies or substantial portions of the Software.
guido+pwm@1: 
guido+pwm@1: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
guido+pwm@1: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
guido+pwm@1: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
guido+pwm@1: IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
guido+pwm@1: CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
guido+pwm@1: TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
guido+pwm@1: SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
guido+pwm@1: 
guido+pwm@1: -->
guido+pwm@1: <refentry xmlns="http://docbook.org/ns/docbook"
guido+pwm@1:   xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
guido+pwm@1:   <info>
guido+pwm@1:     <author>
guido+pwm@1:       <personname>
guido+pwm@1:         <firstname>Guido</firstname>
guido+pwm@1:         <surname>Berhoerster</surname>
guido+pwm@1:       </personname>
guido+pwm@1:       <email>guido+pwm@berhoerster.name</email>
guido+pwm@1:       <personblurb/>
guido+pwm@1:     </author>
guido+pwm@23:     <date>17 September, 2017</date>
guido+pwm@1:   </info>
guido+pwm@1:   <refmeta>
guido+pwm@1:     <refentrytitle>pwm</refentrytitle>
guido+pwm@1:     <manvolnum>1</manvolnum>
guido+pwm@1:     <refmiscinfo class="source"/>
guido+pwm@1:     <refmiscinfo class="version"/>
guido+pwm@1:     <refmiscinfo class="manual">User Commands</refmiscinfo>
guido+pwm@1:   </refmeta>
guido+pwm@1:   <refnamediv>
guido+pwm@1:     <refname>pwm</refname>
guido+pwm@1:     <refpurpose>password manager</refpurpose>
guido+pwm@1:   </refnamediv>
guido+pwm@1:   <refsynopsisdiv>
guido+pwm@1:     <cmdsynopsis>
guido+pwm@1:       <command>pwm</command>
guido+pwm@1:       <arg choice="opt">
guido+pwm@1:         <option>-P</option>
guido+pwm@1:         <replaceable>password_file</replaceable>
guido+pwm@1:       </arg>
guido+pwm@1:       <arg choice="opt">
guido+pwm@23:         <option>-R</option>
guido+pwm@23:       </arg>
guido+pwm@23:       <arg choice="opt">
guido+pwm@1:         <replaceable>database_file</replaceable>
guido+pwm@1:       </arg>
guido+pwm@1:     </cmdsynopsis>
guido+pwm@1:   </refsynopsisdiv>
guido+pwm@1:   <refsect1>
guido+pwm@1:     <title>Description</title>
guido+pwm@1:     <para>The <command>pwm</command> utility is a password manager which
guido+pwm@1:     stores passwords and associated metadata in an encrypted database protected
guido+pwm@1:     by a master password.  It offers both a text-based user interface for
guido+pwm@1:     interactive use as well as a non-interactive mode.  The database uses the
guido+pwm@1:     PasswordSafe database version 3 file format and thus provides
guido+pwm@1:     interoperabity with other password managers using the same format.</para>
guido+pwm@1:     <para>After opening an existing database or creating a new one,
guido+pwm@1:     <command>pwm</command> provides commands to create, modify, delete, and
guido+pwm@1:     display password database entries which may be organized in groups.  The
guido+pwm@1:     contents of a field of a given entry can also be piped to an external
guido+pwm@26:     command such as the <citerefentry><refentrytitle>pwm-clip</refentrytitle>
guido+pwm@26:     <manvolnum>1</manvolnum></citerefentry> utility in order to copy the
guido+pwm@26:     content of the username or password field of an entry to the
guido+pwm@26:     clipboard.</para>
guido+pwm@1:     <para>If specified, <command>pwm</command> will open or create
guido+pwm@1:     <replaceable>database_file</replaceable> instead of the user's default
guido+pwm@1:     database.</para>
guido+pwm@1:     <para><command>pwm</command> must be run with a locale which uses the UTF-8
guido+pwm@1:     character encoding.</para>
guido+pwm@1:     <refsect2>
guido+pwm@1:       <title>Output format</title>
guido+pwm@10:       <para>The <command>show</command> and <command>info</command> commands
guido+pwm@10:       display fields by printing the field name followed by a colon, one or
guido+pwm@10:       more space characters and the field's verbatim content to the standard
guido+pwm@10:       output stream. Field content may contain newlines, non-printable and/or
guido+pwm@10:       control characters.</para>
guido+pwm@17:       <para>If running in interactive mode, the <command>list</command>,
guido+pwm@17:       <command>show</command> and <command>info</command> will display
guido+pwm@17:       the results on a page-by-page basis using an internal pager.</para>
guido+pwm@1:       <para>The <command>pipe</command> prints the verbatim field content to the
guido+pwm@1:       standard input stream of the given command.</para>
guido+pwm@1:       <para>Error messages are printed to the standard error stream.</para>
guido+pwm@1:     </refsect2>
guido+pwm@1:   </refsect1>
guido+pwm@1:   <refsect1>
guido+pwm@1:     <title>Options</title>
guido+pwm@1:     <para>The following options are supported:</para>
guido+pwm@1:     <variablelist>
guido+pwm@1:       <varlistentry>
guido+pwm@1:         <term>
guido+pwm@1:           <option>-P</option>
guido+pwm@1:           <replaceable>password_file</replaceable>
guido+pwm@1:         </term>
guido+pwm@1:         <listitem>
guido+pwm@1:           <para>Read the master password from the first line of
guido+pwm@1:           <replaceable>password_file</replaceable>.</para>
guido+pwm@1:         </listitem>
guido+pwm@1:       </varlistentry>
guido+pwm@23:       <varlistentry>
guido+pwm@23:         <term>
guido+pwm@23:           <option>-R</option>
guido+pwm@23:         </term>
guido+pwm@23:         <listitem>
guido+pwm@23:           <para>Treat the database as read-only and disallow any modifications
guido+pwm@23:           and write operations.</para>
guido+pwm@23:         </listitem>
guido+pwm@23:       </varlistentry>
guido+pwm@1:     </variablelist>
guido+pwm@1:   </refsect1>
guido+pwm@1:   <refsect1>
guido+pwm@1:     <title>Usage</title>
guido+pwm@1:     <para>If stdin is connected to a terminal pwm will run in interactive mode
guido+pwm@1:     and prompt the user for the master password unless
guido+pwm@1:     <replaceable>password_file</replaceable> is specified via the
guido+pwm@1:     <option>-P</option> option. After successfully opening the password
guido+pwm@1:     database the user will be prompted for a command.</para>
guido+pwm@1:     <para>When running in non-interactive mode a file containing the master
guido+pwm@1:     pasword must be specified via the <option>-P</option> option and after
guido+pwm@1:     successfully opening the password database, pwm will execute commands read
guido+pwm@1:     from stdin until either an error occurrs or end-of-file is reached.</para>
guido+pwm@1:     <para><command>pwm</command> operates on a copy of the password database
guido+pwm@1:     in memory, any changes must be explicitly written back to the database
guido+pwm@1:     using the write command.</para>
guido+pwm@1:     <refsect2>
guido+pwm@1:       <title>IDs</title>
guido+pwm@1:       <para>Database entries are referred to by an ID value which is a
guido+pwm@1:       positive integer value that is guaranteed to be unqiue during the run
guido+pwm@1:       time of the pwm utility.</para>
guido+pwm@1:     </refsect2>
guido+pwm@1:     <refsect2>
guido+pwm@1:       <title>Fields</title>
guido+pwm@10:       <para>The following entry fields are supported:</para>
guido+pwm@10:       <table xml:id="field-table">
guido+pwm@10:         <title>Fields and their identifiers</title>
guido+pwm@10:         <tgroup cols="2" align="left" colsep="1" rowsep="1">
guido+pwm@10:           <thead>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>Field</entry>
guido+pwm@10:               <entry>Field Identifier</entry>
guido+pwm@10:             </row>
guido+pwm@10:           </thead>
guido+pwm@10:           <tbody>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>Group</entry>
guido+pwm@10:               <entry>group</entry>
guido+pwm@10:             </row>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>Title</entry>
guido+pwm@10:               <entry>title</entry>
guido+pwm@10:             </row>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>Username</entry>
guido+pwm@10:               <entry>username</entry>
guido+pwm@10:             </row>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>Password</entry>
guido+pwm@10:               <entry>password</entry>
guido+pwm@10:             </row>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>Notes</entry>
guido+pwm@10:               <entry>notes</entry>
guido+pwm@10:             </row>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>URL</entry>
guido+pwm@10:               <entry>url</entry>
guido+pwm@10:             </row>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>Creation Time</entry>
guido+pwm@10:               <entry>ctime</entry>
guido+pwm@10:             </row>
guido+pwm@10:             <row>
guido+pwm@10:               <entry>Modification Time</entry>
guido+pwm@10:               <entry>mtime</entry>
guido+pwm@10:             </row>
guido+pwm@10:           </tbody>
guido+pwm@10:         </tgroup>
guido+pwm@10:       </table>
guido+pwm@1:       <para>Other, existing fields specified by the PasswordSafe file format
guido+pwm@1:       will be preserved but cannot be displayed or modified.</para>
guido+pwm@1:     </refsect2>
guido+pwm@1:     <refsect2>
guido+pwm@1:       <title>Commands</title>
guido+pwm@1:       <para>Each command must appear on a seperate line terminated by a newline
guido+pwm@1:       character.  The command and its arguments are seperated by whitespace,
guido+pwm@1:       i.e. one or more space or tab characters.  If an argument contains
guido+pwm@1:       whitespace characters it must either be quoted by encosing it in single
guido+pwm@1:       or double quote characters or each whitespace character must be preceded
guido+pwm@1:       by a backslash character.  Arguments quoted with a single or double quote
guido+pwm@1:       character preserve the literal values of all characters with the
guido+pwm@1:       exception of the backslash character which can be used to escape the
guido+pwm@1:       respective quoting character.  Two consecutive backslash characters yield
guido+pwm@1:       a literal backslash within both quoted and unquoted arguments. A line
guido+pwm@1:       must not end in a single backslash character, any other backslash
guido+pwm@1:       characters are ignored.</para>
guido+pwm@1:       <para>If an error occurrs while parsing or executing a command,
guido+pwm@1:       <command>pwm</command> will terminate when running in non-interactive
guido+pwm@1:       mode.  In interactive mode it will print an error message and prompt the
guido+pwm@1:       user for the next command.  The following commands are supported:</para>
guido+pwm@1:       <variablelist>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>List entries</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>list</command>
guido+pwm@11:               <arg choice="opt" rep="repeat">
guido+pwm@11:                 <replaceable>field</replaceable>~<replaceable>regex</replaceable>
guido+pwm@11:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>ls</command>
guido+pwm@11:               <arg choice="opt" rep="repeat">
guido+pwm@11:                 <replaceable>field</replaceable>~<replaceable>regex</replaceable>
guido+pwm@11:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@11:             <para>List password database entries. If one or more filter
guido+pwm@11:             expressions are specified, limit the displayed entries to those
guido+pwm@11:             whose <replaceable>field</replaceable> content matches the extended
guido+pwm@11:             regular expression <replaceable>regex</replaceable>.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Create entry</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>create</command>
guido+pwm@1:               <arg choice="opt" rep="repeat">
guido+pwm@1:                 <replaceable>field</replaceable>=<replaceable>value</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>c</command>
guido+pwm@1:               <arg choice="opt" rep="repeat">
guido+pwm@1:                 <replaceable>field</replaceable>=<replaceable>value</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Create a new entry assigning each given
guido+pwm@1:             <replaceable>field</replaceable> to the corresponsing
guido+pwm@1:             <replaceable>value</replaceable>.</para>
guido+pwm@22:             <para>If no fields are specified in interactive mode,
guido+pwm@22:             <command>pwm</command> will prompt the user for the content of
guido+pwm@22:             each field.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Modify entry</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>modify</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>id</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <arg choice="opt" rep="repeat">
guido+pwm@1:                 <replaceable>field</replaceable>=<replaceable>value</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>m</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>id</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <arg choice="opt" rep="repeat">
guido+pwm@1:                 <replaceable>field</replaceable>=<replaceable>value</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Modify an existing entry identified by
guido+pwm@1:             <replaceable>id</replaceable> assigning each given
guido+pwm@1:             <replaceable>field</replaceable> to the corresponsing
guido+pwm@1:             <replaceable>value</replaceable>.</para>
guido+pwm@22:             <para>If no fields are specified and <command>pwm</command> is
guido+pwm@22:             running in interactive mode, it will prompt the user for the
guido+pwm@22:             content of each field, allowing him to edit any previous
guido+pwm@22:             content.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Remove entry</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>remove</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>id</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>rm</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>id</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Remove an existing entry identified by
guido+pwm@1:             <replaceable>id</replaceable>.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Display entry fields</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>show</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>id</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <arg choice="opt" rep="repeat">
guido+pwm@1:                 <replaceable>field</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>s</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>id</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <arg choice="opt" rep="repeat">
guido+pwm@1:                 <replaceable>field</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Display each <replaceable>field</replaceable> of the entry
guido+pwm@15:             identified by <replaceable>id</replaceable>. If no field is
guido+pwm@15:             specified, display all fields except the password field.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Pipe entry fields to an external command</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>pipe</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>id</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <arg choice="plain" rep="repeat">
guido+pwm@1:                 <replaceable>field</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>command</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>p</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>id</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <arg choice="plain" rep="repeat">
guido+pwm@1:                 <replaceable>field</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>command</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Pipe the content of each given
guido+pwm@1:             <replaceable>field</replaceable> of the entry identified by id to
guido+pwm@1:             command which must be a single argument. The command is executed by
guido+pwm@1:             invoking the <command>sh</command> utility with the <arg>-c</arg>
guido+pwm@1:             option and <replaceable>command</replaceable> as its option
guido+pwm@1:             argument, thus special care should be applied to quoting command.
guido+pwm@1:             See the <citerefentry><refentrytitle>sh</refentrytitle>
guido+pwm@1:             <manvolnum>1</manvolnum></citerefentry> manual page for
guido+pwm@1:             details.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Create empty group</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>creategroup</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>name</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>cg</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>name</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Create a new empty group named
guido+pwm@1:             <replaceable>name</replaceable>.</para>
guido+pwm@22:             <para>In interactive-mode the <replaceable>name</replaceable>
guido+pwm@22:             argument is optional, if it is not specified <command>pwm</command>
guido+pwm@22:             will prompt the user for it.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Remove empty group</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>removegroup</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>name</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>rg</command>
guido+pwm@1:               <arg choice="plain">
guido+pwm@1:                 <replaceable>name</replaceable>
guido+pwm@1:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Remove the empty group named
guido+pwm@1:             <replaceable>name</replaceable>.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@12:           <term>Generate a random password</term>
guido+pwm@12:           <listitem>
guido+pwm@12:             <cmdsynopsis>
guido+pwm@12:               <command>generatepassword</command>
guido+pwm@12:               <arg choice="opt">
guido+pwm@12:                 <replaceable>id</replaceable>
guido+pwm@12:               </arg>
guido+pwm@12:               <arg choice="opt">
guido+pwm@12:                 len=<replaceable>n</replaceable>
guido+pwm@12:               </arg>
guido+pwm@12:               <arg choice="opt" rep="repeat">
guido+pwm@12:                 chars=<replaceable>n</replaceable>:<replaceable>chars</replaceable>
guido+pwm@12:               </arg>
guido+pwm@12:               <arg choice="opt" rep="repeat">
guido+pwm@12:                 charclass=<replaceable>n</replaceable>:<replaceable>class</replaceable>
guido+pwm@12:               </arg>
guido+pwm@12:             </cmdsynopsis>
guido+pwm@12:             <cmdsynopsis>
guido+pwm@12:               <command>gp</command>
guido+pwm@12:               <arg choice="opt">
guido+pwm@12:                 <replaceable>id</replaceable>
guido+pwm@12:               </arg>
guido+pwm@12:               <arg choice="opt">
guido+pwm@12:                 len=<replaceable>n</replaceable>
guido+pwm@12:               </arg>
guido+pwm@12:               <arg choice="opt" rep="repeat">
guido+pwm@12:                 chars=<replaceable>n</replaceable>:<replaceable>chars</replaceable>
guido+pwm@12:               </arg>
guido+pwm@12:               <arg choice="opt" rep="repeat">
guido+pwm@12:                 charclass=<replaceable>n</replaceable>:<replaceable>class</replaceable>
guido+pwm@12:               </arg>
guido+pwm@12:               <sbr/>
guido+pwm@12:             </cmdsynopsis>
guido+pwm@12:             <para>Randomly generate a new password according to the specified
guido+pwm@12:             constraints. The <literal>len</literal> argument sets the length of
guido+pwm@12:             the generated password to <replaceable>n</replaceable> characters.
guido+pwm@12:             The <literal>chars</literal> argument constrains the password to
guido+pwm@12:             <replaceable>n</replaceable> from the set of characters
guido+pwm@12:             <replaceable>chars</replaceable>. Similarly, the
guido+pwm@12:             <literal>charclass</literal> argument to
guido+pwm@12:             <replaceable>n</replaceable> characters from the extended regular
guido+pwm@12:             expression character class <replaceable>class</replaceable>.
guido+pwm@12:             Multiple <literal>char</literal> and <literal>charclass</literal>
guido+pwm@12:             arguments may be specified, in which case the generated passwords
guido+pwm@12:             match all of them.</para>
guido+pwm@12:           </listitem>
guido+pwm@12:         </varlistentry>
guido+pwm@12:         <varlistentry>
guido+pwm@1:           <term>Change the master password</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>changepassword</command>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>ch</command>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Change the master password.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Display help text</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>help</command>
guido+pwm@14:               <arg choice="opt">
guido+pwm@14:                 <replaceable>command</replaceable>
guido+pwm@14:               </arg>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>h</command>
guido+pwm@14:               <arg choice="opt">
guido+pwm@14:                 <replaceable>command</replaceable>
guido+pwm@14:               </arg>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@14:             <para>Display a summary of all commands or usage information for
guido+pwm@14:             the specified <replaceable>command</replaceable>.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@10:           <term>Show metadata information</term>
guido+pwm@10:           <listitem>
guido+pwm@10:             <cmdsynopsis>
guido+pwm@10:               <command>info</command>
guido+pwm@10:             </cmdsynopsis>
guido+pwm@10:             <cmdsynopsis>
guido+pwm@10:               <command>i</command>
guido+pwm@10:               <sbr/>
guido+pwm@10:             </cmdsynopsis>
guido+pwm@10:             <para>Display metadata information such as the user who last wrote
guido+pwm@10:             to the database, the time when the database was last written to,
guido+pwm@10:             and the host on which the password database was last written
guido+pwm@10:             to.</para>
guido+pwm@10:           </listitem>
guido+pwm@10:         </varlistentry>
guido+pwm@10:         <varlistentry>
guido+pwm@16:           <term>Display status messages</term>
guido+pwm@16:           <listitem>
guido+pwm@16:             <cmdsynopsis>
guido+pwm@16:               <command>status</command>
guido+pwm@16:             </cmdsynopsis>
guido+pwm@16:             <cmdsynopsis>
guido+pwm@16:               <command>t</command>
guido+pwm@16:               <sbr/>
guido+pwm@16:             </cmdsynopsis>
guido+pwm@16:             <para>Redisplay any error message from the previous command and
guido+pwm@16:             whether there are unsaved changes.</para>
guido+pwm@16:           </listitem>
guido+pwm@16:         </varlistentry>
guido+pwm@16:         <varlistentry>
guido+pwm@1:           <term>Write database</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>write</command>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>w</command>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <para>Write all changes back to the password database.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:         <varlistentry>
guido+pwm@1:           <term>Quit</term>
guido+pwm@1:           <listitem>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>quit</command>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@1:             <cmdsynopsis>
guido+pwm@1:               <command>q</command>
guido+pwm@21:             </cmdsynopsis>
guido+pwm@21:             <cmdsynopsis>
guido+pwm@21:               <keysym>end-of-file</keysym>
guido+pwm@1:               <sbr/>
guido+pwm@1:             </cmdsynopsis>
guido+pwm@13:             <para>Quit <command>pwm</command>.  If running in interactive mode
guido+pwm@13:             and there are unsaved changes, <command>pwm</command> will not
guido+pwm@13:             terminate but display a warning message. If the quit command is
guido+pwm@13:             invoked twice consecutively, <command>pwm</command> will discard
guido+pwm@13:             unsaved changes and terminate.</para>
guido+pwm@13:           </listitem>
guido+pwm@13:         </varlistentry>
guido+pwm@13:         <varlistentry>
guido+pwm@13:           <term>Quit and discard unsaved changes</term>
guido+pwm@13:           <listitem>
guido+pwm@13:             <cmdsynopsis>
guido+pwm@13:               <command>Quit</command>
guido+pwm@13:             </cmdsynopsis>
guido+pwm@13:             <cmdsynopsis>
guido+pwm@13:               <command>Q</command>
guido+pwm@13:               <sbr/>
guido+pwm@13:             </cmdsynopsis>
guido+pwm@13:             <para>Quit <command>pwm</command> and discard any unsaved changes
guido+pwm@13:             without a warning.</para>
guido+pwm@1:           </listitem>
guido+pwm@1:         </varlistentry>
guido+pwm@1:       </variablelist>
guido+pwm@1:     </refsect2>
guido+pwm@1:   </refsect1>
guido+pwm@1:   <refsect1>
guido+pwm@1:     <title>File Format</title>
guido+pwm@1:     <para>The canonical description of the file format is included with the
guido+pwm@1:     distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle>
guido+pwm@1:     <manvolnum>1</manvolnum></citerefentry> utility.</para>
guido+pwm@1:   </refsect1>
guido+pwm@1:   <refsect1>
guido+pwm@1:     <title>Environment Variables</title>
guido+pwm@1:     <variablelist>
guido+pwm@1:       <varlistentry>
guido+pwm@1:         <term>
guido+pwm@1:           <literal>LANG</literal>
guido+pwm@1:         </term>
guido+pwm@1:         <term>
guido+pwm@1:           <literal>LC_ALL</literal>
guido+pwm@1:         </term>
guido+pwm@1:         <listitem>
guido+pwm@1:           <para>See <citerefentry><refentrytitle>locale</refentrytitle>
guido+pwm@1:           <manvolnum>5</manvolnum></citerefentry></para>
guido+pwm@1:         </listitem>
guido+pwm@1:       </varlistentry>
guido+pwm@10:       <varlistentry>
guido+pwm@10:         <term>
guido+pwm@10:           <literal>LOGNAME</literal>
guido+pwm@10:         </term>
guido+pwm@10:         <listitem>
guido+pwm@10:           <para>The name of the logged in user which is recorded when writing
guido+pwm@10:           the password database</para>
guido+pwm@10:         </listitem>
guido+pwm@10:       </varlistentry>
guido+pwm@1:     </variablelist>
guido+pwm@1:   </refsect1>
guido+pwm@1:   <refsect1>
guido+pwm@1:     <title>Exit Status</title>
guido+pwm@1:     <para>The following exit values are returned:</para>
guido+pwm@1:     <variablelist>
guido+pwm@1:       <varlistentry>
guido+pwm@1:         <term>0</term>
guido+pwm@1:         <listitem>
guido+pwm@1:           <para>Command successfully executed.</para>
guido+pwm@1:         </listitem>
guido+pwm@1:       </varlistentry>
guido+pwm@1:       <varlistentry>
guido+pwm@1:         <term>1</term>
guido+pwm@1:         <listitem>
guido+pwm@1:           <para>An unspecified error has occured.</para>
guido+pwm@1:         </listitem>
guido+pwm@1:       </varlistentry>
guido+pwm@1:       <varlistentry>
guido+pwm@1:         <term>2</term>
guido+pwm@1:         <listitem>
guido+pwm@1:           <para>Invalid command line options were specified.</para>
guido+pwm@1:         </listitem>
guido+pwm@1:       </varlistentry>
guido+pwm@1:     </variablelist>
guido+pwm@1:   </refsect1>
guido+pwm@1:   <refsect1>
guido+pwm@20:     <title>Asynchronous Events</title>
guido+pwm@20:     <variablelist>
guido+pwm@20:       <varlistentry>
guido+pwm@20:         <term><literal>SIGINT</literal></term>
guido+pwm@20:         <term><literal>SIGHUP</literal></term>
guido+pwm@20:         <term><literal>SIGTERM</literal></term>
guido+pwm@20:         <listitem>
guido+pwm@20:           <para>If there are changes since the database was last written and
guido+pwm@20:           <command>pwm</command> is running in interactive mode, it
guido+pwm@20:           automatically writes a copy of the current database to the file
guido+pwm@20:           <filename>~/.pwm/autosave.psafe3</filename> which may be used for
guido+pwm@20:           recovery later.</para>
guido+pwm@20:         </listitem>
guido+pwm@20:       </varlistentry>
guido+pwm@20:     </variablelist>
guido+pwm@20:   </refsect1>
guido+pwm@20:   <refsect1>
guido+pwm@1:     <title>Files</title>
guido+pwm@1:     <variablelist>
guido+pwm@1:       <varlistentry>
guido+pwm@1:         <term><filename>~/.pwm/pwm.psafe3</filename></term>
guido+pwm@1:         <listitem>
guido+pwm@1:           <para>default password database</para>
guido+pwm@1:         </listitem>
guido+pwm@1:       </varlistentry>
guido+pwm@20:       <varlistentry>
guido+pwm@20:         <term><filename>~/.pwm/autosave.psafe3</filename></term>
guido+pwm@20:         <listitem>
guido+pwm@20:           <para>automatic copy of the password database after receiving a fatal
guido+pwm@20:           signal in interactive mode</para>
guido+pwm@20:         </listitem>
guido+pwm@20:       </varlistentry>
guido+pwm@1:     </variablelist>
guido+pwm@1:   </refsect1>
guido+pwm@1:   <refsect1>
guido+pwm@1:     <title>See Also</title>
guido+pwm@26:     <para><citerefentry><refentrytitle>pwm-clip</refentrytitle>
guido+pwm@26:       <manvolnum>1</manvolnum></citerefentry>,
guido+pwm@26:       <citerefentry><refentrytitle>pwsafe</refentrytitle>
guido+pwm@1:       <manvolnum>1</manvolnum></citerefentry>,
guido+pwm@1:       <citerefentry><refentrytitle>sh</refentrytitle>
guido+pwm@1:       <manvolnum>1</manvolnum></citerefentry>,
guido+pwm@1:       <citerefentry><refentrytitle>locale</refentrytitle>
guido+pwm@1:       <manvolnum>5</manvolnum></citerefentry>,
guido+pwm@11:       <citerefentry><refentrytitle>regex</refentrytitle>
guido+pwm@11:       <manvolnum>5</manvolnum></citerefentry>,
guido+pwm@1:       <link xlink:href="https://pwsafe.org/"/></para>
guido+pwm@1:   </refsect1>
guido+pwm@1: </refentry>