.TH "guncat" "1" "2014\-2020" "guncat_2\&.00\&.01" "guncat \- unencrypting file concatenation"

.PP 
.SH "NAME"
guncat \- catenates files, unencrypting pgp encrypted sections
.PP 
.SH "SYNOPSIS"
\fBguncat\fP [OPTIONS] [file(s)] 
.br 
[OPTIONS] \- cf\&. section \fBOPTIONS\fP
.br 
[file(s)] \- optional files to process (cf\&. section \fBINPUT
FILE(S)\fP)
.br 

.PP 
.SH "DESCRIPTION"

.PP 
\fBGuncat\fP 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 \fBgrep\fP(1), or \fBless\fP(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\(cq\& contents (i\&.e\&., clear\-text
sections and the unencrypted content of PGP encrypted sections) of those
files is difficult\&.
.PP 
\fBGuncat\fP acts comparably to \fBcat\fP, but unencrypts encrypted sections encountered
in the files processed by \fBguncat\fP, copying the unencrypted information to \fBguncat\fP\(cq\&s
standard output stream, which may thereupon be processed by other tools\&.
.PP 
PGP/GPG encrypted sections are surrounded by the following markers:
.nf 

\-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\-

.fi 
and
.nf 

\-\-\-\-\-END PGP MESSAGE\-\-\-\-\-

.fi 

.PP 
When \fBguncat\fP encounters such sections they are processed by \fBgpg\fP(1)\&. \fBGpg\fP needs
a passphrase to unencrypt such sections\&. If not already available (from
\fBgpg\-agent\fP(1)) the required passphrase is requested by \fBguncat\fP, whereafter it
is used by \fBgpg\fP\&.
.PP 
When an incorrect passphrase is entered two additional attempts to
provide the correct passphrase are allowed\&. If the third attempt also fails,
\fBguncat\fP terminates\&. Files processed by \fBguncat\fP may have to be repositioned\&. If
repositioning is not supported \fBguncat\fP terminated with an error message\&.
.PP 
.SH "RETURN VALUE"

.PP 
\fBGuncat\fP returns 0 to the operating system unless an error occurs (0 is also
returned when the option \fI\-\-gpg\-command\fP is specified)\&. 1 is returned if \fBgpg\fP
could not decrypt an encrypted section or if \fBguncat\fP is started without arguments
or options
.PP 
.SH "INPUT FILE(S)"

.PP 
When no file arguments are provided input may be provided using standard
input stream redirection\&.
.PP 
When option \fI\-\-passphrase\fP is specified the first line of the first file
that is processed is read as the passphrase to be used\&. This line is ignored
if \fBgpg\-agent\fP already can provide the correct passphrase\&. Otherwise, when a
thus specified passphrase is incorrect, \fBguncat\fP terminates\&.
.PP 
Any other argument is considered a filename (path specifications are allowed) 
specifying a file to be processed (in sequence) by \fBguncat\fP\&. 
.PP 
If a file cannot be read \fBguncat\fP terminates with an error message\&.
.PP 
.SH "OPTIONS"

.PP 
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\&.
.PP 
.IP o 
\fB\-\-gpg\-command\fP
.br 
Show the gpg command that would be used, and quit, returning 0\&.
.IP 
.IP o 
\fB\-\-gpg\-option\fP=option (\fB\-m\fP)
.br 
Add \fIoption\fP to \fBgpg\fP\(cq\&s call\&. If the option contains blanks, surround
\fIoption\fP by single or double quotes\&. Option \fIgpg\-option\fP may
repeatedly be specified\&.
.IP 
.IP o 
\fB\-\-gpg\-path\fP=path
.br 
Path to the \fBgpg\fP program (default: \fI/usr/bin/gpg\fP)
.IP 
.IP o 
\fB\-\-help\fP (\fB\-h\fP)
.br 
Basic usage information is written to the standard output stream\&.
.IP 
.IP o 
\fB\-\-less\fP=path (\fB\-l\fP)
.br 
output is written to \(cq\&/usr/bin/less\(cq\&\&. By default output is written to
the std\&. output stream\&. This option cannot be specified when either
option \fI\-\-pipe\fP or option \fI\-\-write\fP is specified\&.
.IP 
.IP o 
\fB\-\-no\-errors\fP
.br 
When this options is specified \fBguncat\fP terminates \fBgpg\fP returns a non\-zero
exit value\&.
.IP 
.IP o 
\fB\-\-passphrase\fP \fB\-p\fP
.br 
By default the passphrase is read by \fBguncat\fP after prompting the user to
enter the passphrase\&. The passphrase is not echoed\&. If input
redirection is used or if input files are specified option
\fI\-\-passphrase\fP can be specified to read the passphrase from the
first line of the first input stream that is read by \fBguncat\fP\&. In that case
the input stream\(cq\&s first line is (of course) not written to the output
stream\&. When the \fI\-\-passphrase\fP option is specified and the provided
password is incorrect, \fBguncat\fP terminates\&.
.IP 
.IP o 
\fB\-\-pipe\fP=path (\fB\-P\fP)
.br 
Full path to a program receiving guncat\(cq\&s output\&. By default output is
written to the std\&. output stream\&. This option cannot be specified
when either option \fI\-\-less\fP or option \fI\-\-write\fP is specified\&.
.IP 
.IP o 
\fB\-\-pgp\-ranges\fP \fB\-r\fP
.br 
the lines\-ranges of complete \fIPGP MESSAGE\fP sections are reported\&. No
additional output is produced\&.
.IP 
.IP o 
\fB\-\-quoted\-printable\fP \fB\-q\fP
.br 
merely decrypt PGP messages, keeping their quoted\-printable content (by
default quoted\-printable content like \(cq\&\fI=3D\fP\(cq\& is converted to
ascii)\&.
.IP 
.IP o 
\fB\-\-reduce\-headers\fP \fB\-R\fP
.br 
When encountering mail headers (starting at lines beginning with
`\fIFrom \fP\(cq\& and ending at the next empty line) only output the mail
headers \fICc:, Date:, From:, Subject:\fP, and \fITo:\fP\&.
.IP 
.IP o 
\fB\-\-section\-lines\fP \fB\-S\fP
.br 
In the output precede decrypted \fIPGP MESSAGE\fP sections by their line
numbers, using a format like
.nf 

****************************
filename:43:104: PGP MESSAGE
****************************
    
.fi 
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
.IP 
.IP o 
\fB\-\-skip\-incomplete\fP \fB\-s\fP
.br 
Incomple \fIPGP MESSAGE\fP sections are ignored and are not outputted\&. By
default the program\(cq\&s output also contain the lines of any incomplete
\fIPGP MESSAGE\fP sections that were encountered\&.
.IP 
.IP o 
\fB\-\-time\-limit\fP=seconds (\fB\-T\fP)
.br 
Option \fI\-\-time\-limit\fP is used to specify the max\&. time in seconds
that \fBgpg\fP 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 \fIEND PGP MESSAGE\fP line)\&.
.IP 
.IP o 
\fB\-\-tty\-OK\fP \fB\-t\fP
.br 
Option \fI\-\-no\-tty\fP is not specified when calling \fBgpg\fP\&. By default it is
specified\&. 
.IP 
.IP o 
\fB\-\-verbose\fP=path (\fB\-V\fP)
.br 
Path to where \fBguncat\fP should write additional messages\&. Specify \- to write
the messages to the standard error stream\&.
.IP 
.IP o 
\fB\-\-version\fP (\fB\-v\fP)
.br 
\fBGuncat\fP\(cq\&s version number is written to the standard output stream,
terminating \fBguncat\fP, returning exit value 0\&.
.IP 
.IP o 
\fB\-\-write\fP=path (\fB\-W\fP)
.br 
output is written to \fIpath\fP\&. If \fIpath\fP already exists \fBgpg\fP
terminates\&. By default output is written to the std\&. output
stream\&. This option cannot be specified when either option \fI\-\-less\fP
or option \fI\-\-pipe\fP is specified\&.

.PP 
.SH "SEE ALSO"

.PP 
\fBgpg\fP(1), \fBgpg\-agent\fP(1), \fBgrep\fP(1), \fBless\fP(1)\&.
.PP 
.SH "BUGS"
None reported
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the `GNU General
Public License\(cq\&\&. Copyright remains with the author\&. \fBGuncat\fP is available at
\fIhttps://fbb\-git\&.gitlab\&.io/guncat/\fP
.PP 
.SH "AUTHOR"

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