Ubuntu Manpage: guncat - catenates files, unencrypting pgp encrypted sections

NAME

       guncat - catenates files, unencrypting pgp encrypted sections

SYNOPSIS

       guncat [OPTIONS] [file(s)]
       [OPTIONS] - cf. section OPTIONS
       [file(s)] - optional files to process (cf. section INPUT FILE(S))

DESCRIPTION

Guncat was designed to tackle a problem encountered with (partically) PGP encrypted files
(which may be encountered in, e.g., mailboxes). Tools to process text-files (like grep(1),
or less(1)) may be used to process those files, but standard tools like cat(1) leave PGP
encrypted sections within such files as-is. As a consequence, browsing the `real’ contents
(i.e., clear-text sections and the unencrypted contents of PGP encrypted sections) of
those files is difficult.

Guncat acts like cat, but unencrypts encrypted sections encountered in the files processed
by guncat, copying the unencrypted information to guncat’s standard output stream, which
may thereupon be processed by other tools.

PGP/GPG encrypted sections are surrounded by

-----BEGIN PGP MESSAGE-----
and

-----END PGP MESSAGE-----
markers. Whenever guncat encounters such sections they will be processed by gpg(1). Gpg
needs a passphrase to unencrypt such sections. The required passphrase may be provided to
guncat, which will then forward the passphrase to gpg, or gpg will itself ask for the
required passphrase.

When providing an incorrect passphrase to guncat two additional attempts to provide the
correct passphrase are granted. If the third attempt also fails, guncat terminates.
Furthermore, when an incorrect passphrase is provided, the currently processed file must
be reset to the beginning of the encrypted section. This implies that the processed file
must be seekable. If the file does not support seeking operations then guncat also
terminates.

RETURN VALUE

       Guncat returns 0 to the operating system unless an error occurs (0 is also  returned  when
       usage  info (option --help), guncat’s version number (option --version), or the configured
       gpg call (option --show-gpg) is requested.

INPUT FILE(S)

       When no file arguments are provided (or when - is provided) the standard input  stream  is
       processed.  Note  that when the standard input stream is specified and option --passphrase
       is specified the standard input stream’s first line is used as gpg’s passphrase.

       Any other argument is considered a file (path specifications are allowed) to be  processed
       in sequence by guncat.

       If an argument does not refer to a readable file, guncat terminates with an error message.

OPTIONS

       Where  available,  single  letter  options  are listed between parentheses following their
       associated  long-option  variants.  Single  letter  options  require  arguments  if  their
       associated long options require arguments as well.

       o      --gpg=path
              Path to the gpg program (default: /usr/bin/gpg)

       o      --gpg-msg=path (-m)
              Path to where gpg should write its messages. Specify - to write the messages to the
              standard error stream. By default messages are suppressed.

       o      --gpg-no-batch
              Option --batch is omitted when calling gpg.

       o      --gpg-option=option (-m)
              Add option to gpg’s call. If the option contains blanks, surround option by  single
              or double quotes.

       o      --help (-h)
              Basic usage information is written to the standard output stream.

       o      --locate-keys -l
              Locate missing public keys at the configured key server(s) (by default missing keys
              are not searched for).

       o      --passphrase -p
              The passphrase is read as the first line from the standard  input  stream  (without
              being  echoed);  otherwise  the  passphrase  is  handled by gpg itself (e.g., using
              gpg-agent(1)).

       o      --show-gpg
              Show the gpg command that would be used, and quit, returning 0.

       o      --tty-OK -t
              Option --no-tty is omitted when calling gpg.

       o      --verbose=[0-2]
              Specifies gpg’s verbosity level. When calling gpg, by default --quiet is specified;
              with  --verbose  0  gpg’s  option --no-verbose is specified; otherwise --verbose is
              specified once or twice.

       o      --version (-v)
              Guncat’s version number is written to the standard output stream.

BUGS

       None reported

COPYRIGHT

       This is free software, distributed under the terms of the `GNU  General  Public  License’.
       Copyright      remains     with     the     author.     Guncat     is     available     at
       https://fbb-git.github.io/guncat/

ORGANIZATION

       Center for Information Technology, University of Groningen.

AUTHOR

           Frank B. Brokken (f.b.brokken@rug.nl).