gagmacrowarning(server FILE)

includefile(../../release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)

gagmacrowarning(guncat)
mailto(f.b.brokken@rug.nl)

DEFINEMACRO(lsoption)(3)(\
    bf(--ARG1)=tt(ARG3) (bf(-ARG2))\
)
DEFINEMACRO(laoption)(2)(\
    bf(--ARG1)=tt(ARG2)\
)
DEFINEMACRO(loption)(1)(\
    bf(--ARG1)\
)
DEFINEMACRO(soption)(1)(\
    (bf(-ARG1))\
)
DEFINEMACRO(u)(0)(bf(guncat))
DEFINEMACRO(U)(0)(bf(Guncat))
DEFINEMACRO(g)(0)(bf(gpg))

manpage(guncat)(1)(_CurYrs_)(guncat__CurVers_)
        (guncat - unencrypting file concatenation)

manpagename(guncat)(catenates files, unencrypting pgp encrypted sections)

manpagesynopsis()
       bf(guncat) [OPTIONS] tt([file(s)]) nl()
        [OPTIONS] - cf. section bf(OPTIONS)nl()
        [file+nop()(s)] - optional files to process (cf. section bf(INPUT
            FILE(S)))nl()

manpagedescription()

U() 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 bf(grep)(1), or bf(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.

U() acts comparably to bf(cat), but unencrypts encrypted sections encountered
in the files processed by u(), copying the unencrypted information to u()'s
standard output stream, which may thereupon be processed by other tools.

PGP/GPG encrypted sections are surrounded by the following markers:
    verb(
-----BEGIN PGP MESSAGE-----
)
and
    verb(
-----END PGP MESSAGE-----
)

When u() encounters such sections they are processed by g()(1). bf(Gpg) needs
a passphrase to unencrypt such sections. If not already available (from
bf(gpg-agent)(1)) the required passphrase is requested by u(), whereafter it
is used by g().

When an incorrect passphrase is entered two additional attempts to provide the
correct passphrase are allowed. If the third attempt also fails, u()
terminates. While processing files u() may have to reposition their current
file pointer locations. If repositioning is not supported u() terminated with
an error message.

manpagesection(RETURN VALUE)

    U() returns 0 to the operating system unless an error occurs (0 is also
returned when information providing option (like em(--version) or
em(--gpg-command)) are specified). 1 is returned if g() could not decrypt an
encrypted section or when called without options or file(s) to process.

manpagesection(INPUT FILE(S))

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

When option em(--passphrase) is specified the content of the first line of a
specified file is used as the passphrase (see option em(--passphrase) below.

Any other argument is considered a filename (path specifications are allowed) 
specifying a file to be processed (in sequence) by u(). 

If a file cannot be read or decrypted u() terminates with an error message.

manpageoptions()

    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.

    itemization(
    it() loption(dots) soption(d)nl() 
      A dot (.)is written to the standard error stream after processing each
        block of 8192 input lines. This option is ignored when the
        tt(--pgp-ranges, --section-lines) or tt(--verbose) options are
        specified.

    it() loption(gpg-command)nl() 
       Show the gpg command that would be used, and quit, returning 0.
    
    it() laoption(gpg-messages)(path) soption(m)nl() 
       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.
    
    it() laoption(gpg-option)(option)nl()
       Add em(option) to g()'s call. If the option contains blanks, surround
        em(option) by single or double quotes. Option em(gpg-option) may
        repeatedly be specified.

    it() laoption(gpg-path)(path)nl()
        Path to the g() program (default: em(/usr/bin/gpg))

    it() loption(help) soption(h)nl()
       Basic usage information is written to the standard output stream.

    it() loption(no-errors)nl()
       When this options is specified u() terminates g() returns a non-zero
        exit value.

    it() laoption(passphrase)(path)nl() 
       By default u() 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 tt(--passphrase)
        option.  When the em(--passphrase) option is specified and the
        provided password is incorrect, u() terminates.
    
    it() loption(pgp-ranges) soption(r)nl() 
       the lines-ranges of complete em(PGP MESSAGE) sections are reported. No
        additional output is produced.

    it() loption(quoted-printable) soption(q)nl() 
       merely decrypt PGP messages, keeping their quoted-printable content (by
        default quoted-printable content like 'em(=3D)' is converted to
        ascii).

    it() loption(reduce-headers) soption(R)nl() 
       When encountering mail headers (starting at lines beginning with
        `em(From )' and ending at the next empty line) only output the mail
        headers em(Cc:, Date:, From:, Subject:), and em(To:).

    it() loption(section-lines) soption(S)nl() 
       In the output precede decrypted em(PGP MESSAGE) sections by their line
        numbers, using a format like
    verb(
****************************
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

    it() loption(skip-incomplete) soption(s)nl() 
       Incomple em(PGP MESSAGE) sections are ignored and are not outputted. By
        default the program's output also contain the lines of any incomplete
        em(PGP MESSAGE) sections that were encountered.

    it() lsoption(time-limit)(T)(seconds)nl() 
       Option em(--time-limit) is used to specify the max. time in seconds
        that g() 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 em(END PGP MESSAGE) line).

    it() loption(tty-OK) soption(t)nl() 
       Option em(--no-tty) is not specified when calling g(). By default it is
        specified.

    it() lsoption(verbose)(V)(path)nl()
        Path to where u() should write additional messages. Specify - to write
        the messages to the standard error stream.

    it() loption(version) (soption(v))nl()
       U()'s version number is written to the standard output stream,
        terminating u(), returning exit value 0.
    ) 
    
manpageseealso() 

bf(gpg)(1), bf(gpg-agent)(1), bf(grep)(1), bf(less)(1).

manpagebugs()
    None reported

manpagesection(COPYRIGHT)
    This is free software, distributed under the terms of the `GNU General
Public License'. U() is available at em(https://fbb-git.gitlab.io/guncat/)

manpageauthor()

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