mdw@git.distorted.org.uk Git - mLib/blob - codec/bincode.1

   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
  57 flags set by default are
  58 .RB ` ignspc '
  59 and
  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