Provided by: guncat_2.01.00-1build1_amd64 
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 (partially) PGP encrypted files
(which may exist in, e.g., mailboxes). Tools to process text-files (like grep(1), or
less(1)) may be used to process those files, but those tools leave PGP encrypted sections
inside such files as-is. As a consequence, browsing the `real’ contents (i.e., clear-text
sections and the unencrypted content of PGP encrypted sections) of those files is
difficult.
Guncat acts comparably to 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 the following markers:
-----BEGIN PGP MESSAGE-----
and
-----END PGP MESSAGE-----
When guncat encounters such sections they are processed by gpg(1). Gpg needs a passphrase
to unencrypt such sections. If not already available (from gpg-agent(1)) the required
passphrase is requested by guncat, whereafter it is used by gpg.
When an incorrect passphrase is entered two additional attempts to provide the correct
passphrase are allowed. If the third attempt also fails, guncat terminates. While
processing files guncat may have to reposition their current file pointer locations. If
repositioning is not supported guncat terminated with an error message.
RETURN VALUE
Guncat returns 0 to the operating system unless an error occurs (0 is also returned when
information providing option (like --version or --gpg-command) are specified). 1 is
returned if gpg could not decrypt an encrypted section or when called without options or s
to process.
INPUT FILE(S)
When no file arguments are provided input may be provided using standard input stream
redirection.
When option --passphrase is specified the content of the first line of a specified file is
used as the passphrase (see option --passphrase below.
Any other argument is considered a filename (path specifications are allowed) specifying a
file to be processed (in sequence) by guncat.
If a file cannot be read or decrypted guncat terminates with an error message.
OPTIONS
In the following overview of options single letter options, when available, are listed
between parentheses following their associated long-option alternatives. Single letter
options require arguments if their long option alternatives require arguments as well.
o --dots (-d)
A dot (.)is written to the standard error stream after processing each block of
8192 input lines. This option is ignored when the --pgp-ranges, --section-lines or
--verbose options are specified.
o --gpg-command
Show the gpg command that would be used, and quit, returning 0.
o --gpg-messages=path (-m)
Path to the file receiving the messages written by the GPG program to its standard
error stream. Use `stdout’ to write the messages to the standard output stream, use
`stderr’ to write the messages to the standard error stream. If not specified the
messages written by the GPG program are not shown.
o --gpg-option=option
Add option to gpg’s call. If the option contains blanks, surround option by single
or double quotes. Option gpg-option may repeatedly be specified.
o --gpg-path=path
Path to the gpg program (default: /usr/bin/gpg)
o --help (-h)
Basic usage information is written to the standard output stream.
o --no-errors
When this options is specified guncat terminates gpg returns a non-zero exit value.
o --passphrase=path
By default guncat obtains the passphrase to use by prompting the user to enter the
passphrase. The passphrase may also be read from a separate file whose path is
specified as argument to the --passphrase option. When the --passphrase option is
specified and the provided password is incorrect, guncat terminates.
o --pgp-ranges (-r)
the lines-ranges of complete PGP MESSAGE sections are reported. No additional
output is produced.
o --quoted-printable (-q)
merely decrypt PGP messages, keeping their quoted-printable content (by default
quoted-printable content like ’=3D’ is converted to ascii).
o --reduce-headers (-R)
When encountering mail headers (starting at lines beginning with `From ’ and ending
at the next empty line) only output the mail headers Cc:, Date:, From:, Subject:,
and To:.
o --section-lines (-S)
In the output precede decrypted PGP MESSAGE sections by their line numbers, using a
format like
****************************
filename:43:104: PGP MESSAGE
****************************
where the first number refers to the first line number of the PGP section and the
second number refers to last line number of the PGP section
o --skip-incomplete (-s)
Incomple PGP MESSAGE sections are ignored and are not outputted. By default the
program’s output also contain the lines of any incomplete PGP MESSAGE sections that
were encountered.
o --time-limit=seconds (-T)
Option --time-limit is used to specify the max. time in seconds that gpg is allowed
to run while decrypting a single encrypted section. By default no time limit is
used. This option is useful when the file to process might contain errors in
encrypted sections (like a missing END PGP MESSAGE line).
o --tty-OK (-t)
Option --no-tty is not specified when calling gpg. By default it is specified.
o --verbose=path (-V)
Path to where guncat should write additional messages. Specify - to write the
messages to the standard error stream.
o --version ((-v))
Guncat’s version number is written to the standard output stream, terminating
guncat, returning exit value 0.
SEE ALSO
gpg(1), gpg-agent(1), grep(1), less(1).
BUGS
None reported
COPYRIGHT
This is free software, distributed under the terms of the `GNU General Public License’.
Guncat is available at https://fbb-git.gitlab.io/guncat/
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).