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

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 first line of the first file
that is processed is read as the passphrase to be used. This line is ignored
if bf(gpg-agent) already can provide the correct passphrase. Otherwise, when a
thus specified passphrase is incorrect, u() terminates.

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 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(gpg-command)nl() 
       Show the gpg command that would be used, and quit, returning 0.
    
    it() lsoption(gpg-option)(m)(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() lsoption(less)(l)(path)nl()
       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 em(--pipe) or option em(--write) is specified.

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

    it() loption(passphrase) soption(p)nl() 
       By default the passphrase is read by u() 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
        em(--passphrase) can be specified to read the passphrase from the
        first line of the first input stream that is read by u(). In that case
        the input stream's first line is (of course) not written to the output
        stream. When the em(--passphrase) option is specified and the provided
        password is incorrect, u() terminates.
    
    it() lsoption(pipe)(P)(path)nl() 
       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 em(--less) or option em(--write) is specified.

    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.

    it() lsoption(write)(W)(path)nl() 
       output is written to em(path). If em(path) already exists g()
        terminates. By default output is written to the std. output
        stream. This option cannot be specified when either option em(--less)
        or option em(--pipe) is specified.
    ) 
    
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'. Copyright remains with the author. U() is available at
em(https://fbb-git.gitlab.io/guncat/)

manpageauthor()

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