More changes on the way to remove secring.gpg.
[gnupg.git] / doc / tools.texi
index 888012e..e974cc4 100644 (file)
@@ -41,7 +41,7 @@ GnuPG comes with a couple of smaller tools:
 @end ifset
 
 @mansect description
-Most of the main utilities are able to write there log files to a
+Most of the main utilities are able to write their log files to a
 Unix Domain socket if configured that way.  @command{watchgnupg} is a simple
 listener for such a socket.  It ameliorates the output with a time
 stamp and makes sure that long lines are not interspersed with log
@@ -237,6 +237,16 @@ Check the options for the component @var{component}.
 Update all configuration files with values taken from the global
 configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
 
+@item --list-dirs
+Lists the directories used by @command{gpgconf}.  One directory is
+listed per line, and each line consists of a colon-separated list where
+the first field names the directory type (for example @code{sysconfdir})
+and the second field contains the percent-escaped directory.  Although
+they are not directories, the socket file names used by
+@command{gpg-agent} and @command{dirmngr} are printed as well.  Note
+that the socket file names and the @code{homedir} lines are the default
+names and they may be overridden by command line switches.
+
 @item --list-config [@var{filename}]
 List the global configuration file in a colon separated format.  If
 @var{filename} is given, check that file instead.
@@ -324,7 +334,7 @@ never contain any special characters.
 Some fields contain strings that are described to be
 @emph{percent-escaped}.  Such strings need to be de-escaped before
 their content can be presented to the user.  A percent-escaped string
-is de-escaped by replacing all occurences of @code{%XY} by the byte
+is de-escaped by replacing all occurrences of @code{%XY} by the byte
 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
 from the set @code{0-9a-f}.
 
@@ -467,7 +477,7 @@ dirmngr:Directory Manager:/usr/local/bin/dirmngr:
 
 The command @code{--check-programs} is similar to
 @code{--list-components} but works on backend programs and not on
-components.  It runs each program to test wether it is installed and
+components.  It runs each program to test whether it is installed and
 runnable.  This also includes a syntax check of all config file options
 of the program.
 
@@ -504,17 +514,17 @@ The @emph{boolean value} in this field indicates whether the program's
 config file is syntactically okay.
 
 @item cfgfile
-If an error occured in the configuraion file (as indicated by a false
+If an error occurred in the configuration file (as indicated by a false
 value in the field @code{okay}), this field has the name of the failing
 configuration file.  It is @emph{percent-escaped}.
 
 @item line
-If an error occured in the configuration file, this field has the line
+If an error occurred in the configuration file, this field has the line
 number of the failing statement in the configuration file.  
 It is an @emph{unsigned number}.
 
 @item error
-If an error occured in the configuration file, this field has the error
+If an error occurred in the configuration file, this field has the error
 text of the failing statement in the configuration file.  It is
 @emph{percent-escaped} and @emph{localized}.
 
@@ -686,6 +696,11 @@ fingerprint.
 @item sec key (36)
 A @emph{string} that describes a certificate with a key by user ID,
 key ID or fingerprint.
+
+@item alias list (37)
+A @emph{string} that describes an alias list, like the one used with
+gpg's group option.  The list consists of a key, an equal sign and space
+separated values.
 @end table
 
 More types will be added in the future.  Please see the @var{alt-type}
@@ -732,7 +747,7 @@ no argument is given.
 @item value
 This field is defined only for options.  Its format is that of an
 @emph{option argument}.  If it is empty, then the option is not
-explicitely set in the current configuration, and the default applies
+explicitly set in the current configuration, and the default applies
 (if any).  Otherwise, it contains the current value of the option.
 Note that this field is also meaningful if the option itself does not
 take a real argument (in this case, it contains the number of times
@@ -850,7 +865,7 @@ empty string.
 @end table
 
 @noindent
-Unknown record typs should be ignored.  Note that there is intentionally
+Unknown record types should be ignored.  Note that there is intentionally
 no feature to change the global option file through @command{gpgconf}.
 
 
@@ -932,7 +947,7 @@ applygnupgdefaults
 @end ifset
 
 @mansect description
-This is a simple tool to interactivly generate a certificate request
+This is a simple tool to interactively generate a certificate request
 which will be printed to stdout.
 
 @manpause
@@ -967,7 +982,7 @@ which will be printed to stdout.
 .B  gpg-preset-passphrase
 .RI [ options ]
 .RI [ command ]
-.I keygrip
+.I cache-id
 @end ifset
 
 @mansect description
@@ -997,14 +1012,19 @@ starting @command{gpg-agent} with the
 @command{gpg-preset-passphrase} is invoked this way:
 
 @example
-gpg-preset-passphrase [options] [command] @var{keygrip}
+gpg-preset-passphrase [options] [command] @var{cacheid}
 @end example
 
-@var{keygrip} is a 40 character string of hexadecimal characters
-identifying the key for which the passphrase should be set or cleared.
-This keygrip is listed along with the key when running the command:
-@code{gpgsm --dump-secret-keys}. One of the following command options
-must be given:
+@var{cacheid} is either a 40 character keygrip of hexadecimal
+characters identifying the key for which the passphrase should be set
+or cleared.  The keygrip is listed along with the key when running the
+command: @code{gpgsm --dump-secret-keys}.  Alternatively an arbitrary
+string may be used to identify a passphrase; it is suggested that such
+a string is prefixed with the name of the application (e.g
+@code{foo:12346}).
+
+@noindent
+One of the following command options must be given:
 
 @table @gnupgtabopt
 @item --preset
@@ -1015,7 +1035,7 @@ use. @command{gpg-preset-passphrase} will then read the passphrase from
 
 @item --forget
 @opindex forget
-Flush the passphrase for the given keygrip from the cache.
+Flush the passphrase for the given cache ID from the cache.
 
 @end table
 
@@ -1062,14 +1082,14 @@ for other users.
 @mansect synopsis
 @ifset manverb
 .B  gpg-connect-agent
-.RI [ options ]
+.RI [ options ] [commands]
 @end ifset
 
 @mansect description
 The @command{gpg-connect-agent} is a utility to communicate with a
 running @command{gpg-agent}.  It is useful to check out the commands
 gpg-agent provides using the Assuan interface.  It might also be useful
-for scripting simple applications.  Inputis expected at stdin and out
+for scripting simple applications.  Input is expected at stdin and out
 put gets printed to stdout.
 
 It is very similar to running @command{gpg-agent} in server mode; but
@@ -1088,7 +1108,7 @@ here we connect to a running instance.
 @command{gpg-connect-agent} is invoked this way:
 
 @example
-gpg-connect-agent [options]
+gpg-connect-agent [options] [commands]
 @end example
 @mancont
 
@@ -1125,7 +1145,7 @@ execute it as an assuan server. Here is how you would run @command{gpgsm}:
 @smallexample
  gpg-connect-agent --exec gpgsm --server
 @end smallexample
-
+Note that you may not use options on the command line in this case.
 
 @item --no-ext-connect
 @opindex no-ext-connect
@@ -1136,7 +1156,8 @@ passing.  This option makes it use the old mode.
 @item --run @var{file}
 @opindex run 
 Run the commands from @var{file} at startup and then continue with the
-regular input method.
+regular input method.  Note, that commands given on the command line are
+executed after this file.
 
 @item -s
 @itemx --subst
@@ -1171,9 +1192,9 @@ Just print @var{args}.
 @item /let @var{name} @var{value}
 Set the variable @var{name} to @var{value}.  Variables are only
 substituted on the input if the @command{/subst} has been used.
-Variables are referenced by prefixing the name with a dollr sign and
+Variables are referenced by prefixing the name with a dollar sign and
 optionally include the name in curly braces.  The rules for a valid name
-are idnetically to those of the standard bourne shell.  This is not yet
+are identically to those of the standard bourne shell.  This is not yet
 enforced but may be in the future.  When used with curly braces no
 leading or trailing white space is allowed. 
 
@@ -1216,14 +1237,14 @@ the function name.
 
 @item unpercent @var{args}
 @itemx unpercent+ @var{args}
-Remove percent style ecaping from @var{args}.  Note that @code{%00}
+Remove percent style escaping from @var{args}.  Note that @code{%00}
 terminates the string implicitly.  The string to be converted are the
 entire arguments right behind the delimiting space of the function
 name. @code{unpercent+} also maps plus signs to a spaces.
 
 @item percent @var{args}
 @itemx percent+ @var{args}
-Escape the @var{args} using percent style ecaping.  Tabs, formfeeds,
+Escape the @var{args} using percent style escaping.  Tabs, formfeeds,
 linefeeds, carriage returns and colons are escaped. @code{percent+} also
 maps spaces to plus signs.
 
@@ -1267,6 +1288,14 @@ Use content of @var{file} for inquiries with @var{name}.
 Run @var{prog} for inquiries matching @var{name} and pass the
 entire line to it as command line arguments.
 
+@item /datafile @var{name}
+Write all data lines from the server to the file @var{name}.  The file
+is opened for writing and created if it does not exists.  An existing
+file is first truncated to 0.  The data written to the file fully
+decoded.  Using a single dash for @var{name} writes to stdout.  The
+file is kept open until a new file is set using this command or this
+command is used without an argument.
+
 @item /showdef
 Print all definitions
 
@@ -1291,7 +1320,7 @@ Close the file descriptor @var{fd}.  Warning: This command is
 experimental and might change in future versions.
 
 @item /showopen
-Show a listy of open files.
+Show a list of open files.
 
 @item /serverpid
 Send the Assuan command @command{GETINFO pid} to the server and store
@@ -1437,7 +1466,7 @@ argument @var{inputfile}, and the ciphertext will be output to STDOUT.
 For decryption vice versa.
 
 @var{CLASS} describes the calling conventions of the external tool.
-Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
+Currently it must be given as @samp{confucius}.  @var{PROGRAM} is
 the full filename of that external tool.
  
 For the class @samp{confucius} the option @option{--keyfile} is
@@ -1470,7 +1499,7 @@ Try to be as quiet as possible.
 @item --log-file @var{file}
 @opindex log-file
 Append all logging output to @var{file}.  Default is to write logging
-informaton to STDERR.
+information to STDERR.
 
 @end table