[mLib] / codec / bincode.1

.\" nroff
.TH bincode 1 "9 January 2009" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
bincode \- binary-to-text encoding and decoding
.SH SYNOPSIS
.B bincode
.RB [ \-de]
.RB [ \-f
.IR flags ]
.RB [ \-i
.IR indent ]
.RB [ \-m
.IR maxline ]
.RB [ \-o
.IR output ]
.RI [ file ...]
.SH DESCRIPTION
The
.B bincode
program encodes binary data as plain text (suitable, for example, for
use in email), and recovers binary data from its encoding.
.PP
The options are as follows.
.TP
.B "\-h, \-\-help"
Print a help message to standard output and exit successfully.
.TP
.B "\-v, \-\-version"
Print the program's version number to standard output and exit
successfully.
.TP
.B "\-u, \-\-usage"
Print a one-line usage summary to standard output and exit successfully.
.TP
.BI "\-d, \-\-decode"
Read encoded data and write the result of decoding it.
.TP
.BI "\-e, \-\-encode"
Read raw binary data and write the result of encoding.
.TP
.BI "\-f, \-\-flags=" flags
Set encoding/decoding flags.  The
.I flags
are a list of comma-separated flag names, each preceded by an optional
.RB ` + '
to set the flag (the default) or
.RB ` \- '
to clear it.  The flag names are as listed in
.BR codec (3),
but in lower case, and without the
.RB ` CDCF_ '
prefix; e.g.,
.B CDCF_IGNNEWL
may be specified as
.RB ` ignnewl '.
This option may be repeated: the options are scanned left-to-right.  The
flags set by default are
.RB ` ignspc '
and
.RB ` ignnewl '.
.TP
.BI "\-i, \-\-indent=" indent
Insert the
.I indent
string before each line.  The string may contain simple
backslash-escapes:
.RB ` \ea ',
.RB ` \eb ',
.RB ` \ef ',
.RB ` \en ',
.RB ` \er ',
.RB ` \et ', and
.RB ` \ev '
respectively stand for alert, backspace, form-feed, newline, carriage
return, and horizontal and vertical tab.  A backslash preceding any
other character yields that character; hence, to include a backslash,
write a double backslash.  The default is the empty string: i.e., just
end each line with a newline character.
.TP
.BI "\-m, \-\-maxline=" maxline
Set the maximum output line length to
.I maxline
when encoding.  The limit is ignored when decoding.  If
.I maxline
is zero, then no line splitting is performed.
.TP
.BI "\-o, \-\-output=" output
Write the (encoded or decoded) output to
.IR output .
The default is to write to standard output.  On platforms where it makes
a difference, the output file is opened in text mode when encoding, and
in binary mode when decoding.
.PP
The input to be encoded or decoded is the concatenation of the specified
.IR file s.
If no files are listed, then standard input is read.  A
.I file
which is a single
.RB ` \- '
also means to read standard input.  On systems where it makes a
difference, named files are read in binary mode when encoding and in
text mode when decoding.
.PP
If an error is encountered, the output may be partially written.
.SH "SEE ALSO"
.BR codec (3).
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>
Commit	Line	Data
236f657b MW	1	.\" nroff
	2	.TH bincode 1 "9 January 2009" "Straylight/Edgeware" "mLib utilities library"
	3	.SH NAME
	4	bincode \- binary-to-text encoding and decoding
	5	.SH SYNOPSIS
	6	.B bincode
	7	.RB [ \-de]
	8	.RB [ \-f
	9	.IR flags ]
	10	.RB [ \-i
	11	.IR indent ]
	12	.RB [ \-m
	13	.IR maxline ]
	14	.RB [ \-o
	15	.IR output ]
	16	.RI [ file ...]
	17	.SH DESCRIPTION
	18	The
	19	.B bincode
	20	program encodes binary data as plain text (suitable, for example, for
	21	use in email), and recovers binary data from its encoding.
	22	.PP
	23	The options are as follows.
	24	.TP
	25	.B "\-h, \-\-help"
	26	Print a help message to standard output and exit successfully.
	27	.TP
	28	.B "\-v, \-\-version"
	29	Print the program's version number to standard output and exit
	30	successfully.
	31	.TP
	32	.B "\-u, \-\-usage"
	33	Print a one-line usage summary to standard output and exit successfully.
	34	.TP
	35	.BI "\-d, \-\-decode"
	36	Read encoded data and write the result of decoding it.
	37	.TP
	38	.BI "\-e, \-\-encode"
	39	Read raw binary data and write the result of encoding.
	40	.TP
	41	.BI "\-f, \-\-flags=" flags
	42	Set encoding/decoding flags. The
	43	.I flags
	44	are a list of comma-separated flag names, each preceded by an optional
	45	.RB ` + '
	46	to set the flag (the default) or
	47	.RB ` \- '
	48	to clear it. The flag names are as listed in
	49	.BR codec (3),
	50	but in lower case, and without the
	51	.RB ` CDCF_ '
	52	prefix; e.g.,
	53	.B CDCF_IGNNEWL
	54	may be specified as
	55	.RB ` ignnewl '.
	56	This option may be repeated: the options are scanned left-to-right. The
09fbf4d0 MW	57	flags set by default are
	58	.RB ` ignspc '
	59	and
236f657b MW	60	.RB ` ignnewl '.
	61	.TP
	62	.BI "\-i, \-\-indent=" indent
	63	Insert the
	64	.I indent
	65	string before each line. The string may contain simple
	66	backslash-escapes:
	67	.RB ` \ea ',
	68	.RB ` \eb ',
	69	.RB ` \ef ',
	70	.RB ` \en ',
	71	.RB ` \er ',
	72	.RB ` \et ', and
	73	.RB ` \ev '
	74	respectively stand for alert, backspace, form-feed, newline, carriage
	75	return, and horizontal and vertical tab. A backslash preceding any
	76	other character yields that character; hence, to include a backslash,
	77	write a double backslash. The default is the empty string: i.e., just
	78	end each line with a newline character.
	79	.TP
	80	.BI "\-m, \-\-maxline=" maxline
	81	Set the maximum output line length to
	82	.I maxline
	83	when encoding. The limit is ignored when decoding. If
	84	.I maxline
	85	is zero, then no line splitting is performed.
	86	.TP
	87	.BI "\-o, \-\-output=" output
	88	Write the (encoded or decoded) output to
	89	.IR output .
	90	The default is to write to standard output. On platforms where it makes
	91	a difference, the output file is opened in text mode when encoding, and
	92	in binary mode when decoding.
	93	.PP
	94	The input to be encoded or decoded is the concatenation of the specified
	95	.IR file s.
	96	If no files are listed, then standard input is read. A
	97	.I file
	98	which is a single
	99	.RB ` \- '
	100	also means to read standard input. On systems where it makes a
	101	difference, named files are read in binary mode when encoding and in
	102	text mode when decoding.
	103	.PP
	104	If an error is encountered, the output may be partially written.
	105	.SH "SEE ALSO"
	106	.BR codec (3).
	107	.SH "AUTHOR"
	108	Mark Wooding, <mdw@distorted.org.uk>
	109