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 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  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


       -----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  then
       forwards the passphrase to gpg.

       When  providing  an  incorrect  passphrase  to  guncat  two  additional  attempts  to provide the correct
       passphrase are provided. 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 the option
       --show-gpg) is specified.

INPUT FILE(S)

       When no file arguments are provided (or when - is provided) the standard input stream is processed.

       When option --passphrase is specified the first line of the first file that is processed is read  as  the
       passphrase to use. When a thus specified passphrase is incorrect, guncat terminates.

       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      --errors-OK
              When specifying the option --errors-OK the input s continue to be processed even if gpg returns  a
              non-zero exit value.

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

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

       o      --gpg-no-batch
              Starting with guncat version 1.02.00 this option is not used anymore. It  will  be  removed  in  a
              future vestion.

       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      --help (-h)
              Basic usage information is written to the standard output stream.

       o      --locate-keys -l
              Starting with gpg version 1.02.00 this option is not used anymore. It will be removed in a  future
              vestion.

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

       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=[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.

SEE ALSO

       cat(1), gpg(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/

ORGANIZATION

       Center for Information Technology, University of Groningen.

AUTHOR

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