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. Files
       processed by guncat may have to be repositioned. 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
       the option --gpg-command is specified).  1  is  returned  if  gpg  could  not  decrypt  an
       encrypted section or if guncat is started without arguments or options

INPUT FILE(S)

       When  no  file  arguments  are  provided input may be provided using standard input stream
       redirection.

       When option --passphrase 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 gpg-agent already can
       provide the correct passphrase. Otherwise, when a thus specified passphrase is  incorrect,
       guncat terminates.

       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 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      --gpg-command
              Show the gpg command that would be used, and quit, returning 0.

       o      --gpg-option=option (-m)
              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      --less=path (-l)
              output  is  written  to  ’/usr/bin/less’.  By default output is written to the std.
              output stream. This option cannot be specified when either option --pipe or  option
              --write is specified.

       o      --no-errors
              When this options is specified guncat terminates gpg returns a non-zero exit value.

       o      --passphrase -p
              By  default  the passphrase is read by guncat 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  --passphrase can be specified to read the passphrase
              from the first line of the first input stream that is read by guncat. In that  case
              the input stream’s first line is (of course) not written to the output stream. When
              the --passphrase option is specified and the provided password is incorrect, guncat
              terminates.

       o      --pipe=path (-P)
              Full  path  to a program receiving guncat’s output. By default output is written to
              the std. output stream. This option cannot be specified when either  option  --less
              or option --write is specified.

       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.

       o      --write=path (-W)
              output is written to path. If path already exists gpg terminates. By default output
              is  written  to the std. output stream. This option cannot be specified when either
              option --less or option --pipe is specified.

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’.
       Copyright      remains     with     the     author.     Guncat     is     available     at
       https://fbb-git.gitlab.io/guncat/

AUTHOR

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