chiark - git - mdw - mLib/blob - codec/bincode.1.in

   1 .\" nroff
   2 .\"
   3 .\" Manual for `bincode' utility
   4 .\"
   5 .\" (c) 2009, 2014, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH bincode 1 "9 January 2009" "Straylight/Edgeware" "mLib utilities library"
  32 .
  33 .\"--------------------------------------------------------------------------
  34 .SH NAME
  35 bincode \- binary-to-text encoding and decoding
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH SYNOPSIS
  39 .
  40 .B bincode
  41 .RB [ \-de]
  42 .RB [ \-f
  43 .IR flags ]
  44 .RB [ \-i
  45 .IR indent ]
  46 .RB [ \-m
  47 .IR maxline ]
  48 .RB [ \-o
  49 .IR output ]
  50 .RI [ file ...]
  51 .
  52 .\"--------------------------------------------------------------------------
  53 .SH DESCRIPTION
  54 .
  55 The
  56 .B bincode
  57 program encodes binary data as plain text (suitable, for example, for
  58 use in email), and recovers binary data from its encoding.
  59 .PP
  60 The options are as follows.
  61 .TP
  62 .B "\-h, \-\-help"
  63 Print a help message to standard output and exit successfully.
  64 .TP
  65 .B "\-v, \-\-version"
  66 Print the program's version number to standard output and exit
  67 successfully.
  68 .TP
  69 .B "\-u, \-\-usage"
  70 Print a one-line usage summary to standard output and exit successfully.
  71 .TP
  72 .BI "\-d, \-\-decode"
  73 Read encoded data and write the result of decoding it.
  74 .TP
  75 .BI "\-e, \-\-encode"
  76 Read raw binary data and write the result of encoding.
  77 .TP
  78 .BI "\-f, \-\-flags=" flags
  79 Set encoding/decoding flags.  The
  80 .I flags
  81 are a list of comma-separated flag names, each preceded by an optional
  82 .RB ` + '
  83 to set the flag (the default) or
  84 .RB ` \- '
  85 to clear it.  The flag names are as listed in
  86 .BR codec (3),
  87 but in lower case, and without the
  88 .RB ` CDCF_ '
  89 prefix; e.g.,
  90 .B CDCF_IGNNEWL
  91 may be specified as
  92 .RB ` ignnewl '.
  93 This option may be repeated: the options are scanned left-to-right.  The
  94 flags set by default are
  95 .RB ` ignspc '
  96 and
  97 .RB ` ignnewl '.
  98 .TP
  99 .BI "\-i, \-\-indent=" indent
 100 Insert the
 101 .I indent
 102 string before each line.  The string may contain simple
 103 backslash-escapes:
 104 .RB ` \ea ',
 105 .RB ` \eb ',
 106 .RB ` \ef ',
 107 .RB ` \en ',
 108 .RB ` \er ',
 109 .RB ` \et ', and
 110 .RB ` \ev '
 111 respectively stand for alert, backspace, form-feed, newline, carriage
 112 return, and horizontal and vertical tab.  A backslash preceding any
 113 other character yields that character; hence, to include a backslash,
 114 write a double backslash.  The default is the empty string: i.e., just
 115 end each line with a newline character.
 116 .TP
 117 .BI "\-m, \-\-maxline=" maxline
 118 Set the maximum output line length to
 119 .I maxline
 120 when encoding.  The limit is ignored when decoding.  If
 121 .I maxline
 122 is zero, then no line splitting is performed.
 123 .TP
 124 .BI "\-o, \-\-output=" output
 125 Write the (encoded or decoded) output to
 126 .IR output .
 127 The default is to write to standard output.  On platforms where it makes
 128 a difference, the output file is opened in text mode when encoding, and
 129 in binary mode when decoding.
 130 .PP
 131 The input to be encoded or decoded is the concatenation of the specified
 132 .IR file s.
 133 If no files are listed, then standard input is read.  A
 134 .I file
 135 which is a single
 136 .RB ` \- '
 137 also means to read standard input.  On systems where it makes a
 138 difference, named files are read in binary mode when encoding and in
 139 text mode when decoding.
 140 .PP
 141 If an error is encountered, the output may be partially written.
 142 .
 143 .\"--------------------------------------------------------------------------
 144 .SH "SEE ALSO"
 145 .
 146 .BR codec (3).
 147 .
 148 .\"--------------------------------------------------------------------------
 149 .SH "AUTHOR"
 150 .
 151 Mark Wooding, <mdw@distorted.org.uk>
 152 .
 153 .\"----- That's all, folks --------------------------------------------------
 154