pcp/man/z85.1

.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Z85 1"
.TH Z85 1 "2013-10-25" "Z85 0.0.1" "USER CONTRIBUTED DOCUMENTATION"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
z85 \- encode and decode strings to Z85 encoding.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& Usage: z85 [options] [<file>]
\&
\& Options:
\&  \-e              encode input to Z85
\&  \-d              decode input from Z85
\&  \-h              print this help message
\&  \-v              print program version
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBz85\fR can be used to encode and decode strings to Z85 encoding.
.PP
The option \fB\-e\fR encodes \fBto\fR Z85, which is the default if
no option have been specified. The option \fB\-d\fR does the opposite
and decodes b<from> Z85.
.PP
If no input file have been specified, \fBz85\fR expects the
input to come from \fB\s-1STDIN\s0\fR, otherwise it reads the contents
of \fBfile\fR.
.PP
Encoded or decoded output will always be written to \fB\s-1STDOUT\s0\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
To encode a given file to Z85 and write the output to another:
.PP
.Vb 1
\& z85 \-e myfile.bin > myfile.z85
.Ve
.PP
To decode the file created above and restore the original:
.PP
.Vb 1
\& z85 \-d myfile.z85 > myfile.bin
.Ve
.PP
To encode something from stdin to Z85:
.PP
.Vb 1
\& ps axuw | z85 > pslist.z85
.Ve
.PP
To decode the above and print to stdout:
.PP
.Vb 1
\& z85 \-d pslist.z85
.Ve
.SH "BACKGROUND"
.IX Header "BACKGROUND"
The Z85 encoding format is described here: <http://rfc.zeromq.org/spec:32>.
It's part of ZeroMQ (<http://zeromq.org>). Z85 is based on \s-1ASCII85\s0 with
a couple of modifications (portability, readability etc).
.PP
To fulfil the requirements of the ZeroMQ Z85 functions, the \fBz85\fR utility
does some additional preparations of raw input before actually doing the 
encoding, since the input for \fIzmq_z85_encode()\fR must be divisible by 4:
.PP
Expand the input so that the resulting size is divisible by 4.
.PP
Fill the added bytes with zeroes.
.PP
Prepend the input with a one byte value which holds the number of zeroes
added in the previous step.
.PP
Example:
.PP
Raw input:
.PP
.Vb 1
\& hello\e0
.Ve
.PP
Here, the input size is 6, which is insufficient, therefore it has to be expanded
to be 8. After the process the input looks like this:
.PP
.Vb 1
\& 1hello\e0\e0
.Ve
.PP
So, we padded the input with 1 zero (makes 7 bytes) and preprended it with the
value 1 (the number of zeros added): makes 8 bytes total.
.PP
After decoding Z85 input the process will be reversed.
.PP
\&\fBTrying to use another tool to decode an Z85 encoded string produced
by z85, might not work therefore, unless the tool takes the padding scheme
outlined above into account\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2013 by T.Linden <tom \s-1AT\s0 cpan \s-1DOT\s0 org>
.SH "AUTHORS"
.IX Header "AUTHORS"
\&\fIT.Linden <tom \s-1AT\s0 cpan \s-1DOT\s0 org\fR>
.SH "LICENSE"
.IX Header "LICENSE"
Licensed under the  \s-1GNU\s0 \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0 version 3.