--- name: "guncat" section: "1" platform: "linux" package: "guncat" version: "2.02.00-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/guncat" --- # guncat(1) 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 (partially) PGP encrypted files (which may exist in, e.g., mailboxes). Tools to process text-files (like [**grep**(1)](/grep/1.md), or [**less**(1)](/less/1.md)) 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/1.md). **Gpg** needs a passphrase to unencrypt such sections. If not already available (from [**gpg-agent**(1)](/gpg-agent/1.md)) 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/1.md), [**gpg-agent**(1)](/gpg-agent/1.md), [**grep**(1)](/grep/1.md), [**less**(1)](/less/1.md). ## 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).