man/bio.1

   1 .\"                                      Hey, EMACS: -*- nroff -*-
   2 .\" First parameter, NAME, should be all caps
   3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
   4 .\" other parameters are allowed: see man(7), man(1)
   5 .TH BIO 1 "December 21, 2010"
   6 .\" Please adjust this date whenever revising the manpage.
   7 .\"
   8 .\" Some roff macros, for reference:
   9 .\" .nh        disable hyphenation
  10 .\" .hy        enable hyphenation
  11 .\" .ad l      left justify
  12 .\" .ad b      justify to both left and right margins
  13 .\" .nf        disable filling
  14 .\" .fi        enable filling
  15 .\" .br        insert line break
  16 .\" .sp <n>    insert n+1 empty lines
  17 .\" for manpage-specific macros, see man(7)
  18 .SH NAME
  19 .B bio
  20 \- Barry Input / Output
  21 .SH SYNOPSIS
  22 .B bio -i <input type> -o <output type> [-o <output type> ...]
  23 .SH DESCRIPTION
  24 .PP
  25 .B bio
  26 is a command line tool that treats devices, backups, and data streams
  27 as input and output.
  28 .B bio
  29 supports the following types of IO (actual type name shown in bold):
  30
  31 .IP
  32 .B device
  33
  34 .B tar
  35 (backup files)
  36
  37 .B boost
  38 (serialization files and streams)
  39
  40 .B mime
  41 streams
  42
  43 .B ldif
  44 streams
  45
  46 human readable and hex text
  47 .B dump
  48
  49 .B sha1
  50 sum output
  51
  52 .B cstore
  53 for extracting Content Store records
  54
  55 .PP
  56 Each command line consists of at least one input and output option,
  57 along with their switches.  More than one output can be used, as long
  58 as they do not conflict with each other.  For example, it is not possible
  59 to read and write from the same device PIN.
  60
  61 .PP
  62 This tool combines a lot of the functionality of
  63 .B btool, btardump, brecsum,
  64 and
  65 .B bs11nread,
  66 but does it more flexibly, and improves functionality in some cases,
  67 such as Boost archives being able to contain more than one database.
  68
  69 .SH DEVICE TYPE OPTIONS
  70 .PP
  71 The
  72 .B device
  73 type is used to read or write from a device connected via USB.
  74 Some of the options below are valid only in one input or output
  75 mode, some in both.
  76 .TP
  77 .B \-d db
  78 Name of database to load, when using the
  79 .B device
  80 type as input.  Can be used multiple times.  See
  81 .B btool \-t
  82 for a list of databases on the device.
  83 .TP
  84 .B \-A
  85 Selects all databases found on the device, instead of adding them
  86 manually via the \-d option.
  87 .TP
  88 .B \-p pin
  89 PIN of device to talk to.  Valid for both input and output.
  90 Only needed if you have more than one Blackberry connected at once.
  91 .TP
  92 .B \-P password
  93 Simplistic method to specify device password.  In a real application, this
  94 would be done using a more secure prompt.
  95 .TP
  96 .B \-w mode
  97 Set write mode when using the
  98 .B device
  99 type in output mode.  This must be specified, or nothing will be written.
 100 Can be one of:
 101 .B erase, overwrite, addonly, addnew.
 102
 103 .\".SH DATABASE COMMAND MODIFIERS (DEVICE)
 104 .\"The following options modify the -d command option above, and can be used
 105 .\"multiple times for more than one record.
 106 .\".TP
 107 .\".B \-r #
 108 .\"Fetch specific record, given a record index number as seen in the -T state table.
 109 .\"Can be used multiple times to fetch specific records from a single database.
 110 .\".TP
 111 .\".B \-R #
 112 .\"Same as -r, but also clears the record's dirty flags.
 113 .\".TP
 114 .\".B \-D #
 115 .\"Delete the specified record using the index number as seen in the -T state table.
 116
 117 .SH TAR TYPE OPTIONS
 118 .PP
 119 The
 120 .B tar
 121 type is used to read or write from a backup file created by btool or
 122 the backup GUI.
 123 .TP
 124 .B \-d db
 125 Name of database to load, when using the
 126 .B tar
 127 type as input.  Can be used multiple times.
 128 .B Note
 129 that if no \-d options are specified,
 130 .B bio
 131 defaults to reading all available databases.
 132 .TP
 133 .B \-f file
 134 The tar backup file to read or write from.
 135 .B Bio
 136 uses gzip compressed tar files, so suitable extensions would be .tgz
 137 and .tar.gz.  Unfortunately, due to internal limitations,
 138 an actual file must be specified here, and not \- for stdin / stdout.
 139
 140 .SH BOOST TYPE OPTIONS
 141 .PP
 142 The
 143 .B boost
 144 type is used to read and write parsable records in Boost Serialization
 145 format.  These files were historically written and read by
 146 .B btool
 147 and
 148 .B bs11nread.
 149 .B Bio
 150 is more flexible, in that it can contain multiple databases in one
 151 serialization archive.
 152 .TP
 153 .B \-f file
 154 Filename to read from or write to.  Use \- to specify stdin or stdout.
 155 If not specified for input, defaults to stdin, but since output can
 156 contain non-ASCII chars, you must use \-f \- if you want to write
 157 to stdout.
 158
 159 .SH LDIF TYPE OPTIONS
 160 .PP
 161 The
 162 .B ldif
 163 type is used to read or write ldif output, like the output of the
 164 LDAP command line tool
 165 .B ldapsearch.
 166 .TP
 167 .B \-c dn
 168 When using ldif as output, specify the base DN.
 169 .TP
 170 .B \-C dnattr
 171 Again, for output, specify the attribute name to use when building the FQDN.
 172
 173 .SH MIME TYPE OPTIONS
 174 .PP
 175 The
 176 .B mime
 177 type is used to read or write VCARD, VEVENT, VTODO, or VJOURNAL records
 178 based on the Address Book, Calendar, Tasks, or Memos databases respectively.
 179 .TP
 180 .B \-f file
 181 Filename to read from or write to.  Defaults to \- for stdin or stdout.
 182
 183 .SH DUMP TYPE OPTIONS
 184 .PP
 185 The
 186 .B dump
 187 type is used only for output, and sends human readable record data to
 188 stdout.  Parsable records are parsed; unknown records are dumped in hex
 189 format.
 190 .TP
 191 .B \-n
 192 Use hex format for all records.
 193
 194 .SH SHA1 TYPE OPTIONS
 195 .PP
 196 The
 197 .B sha1
 198 type is used to mimic the behaviour of the
 199 .B brecsum
 200 command.  It calculates a SHA1 sum on the raw record data and sends
 201 the sum to stdout.
 202 .TP
 203 .B \-t
 204 Include the DB Name, Type, and Unique record ID in the checksum for each
 205 record.
 206
 207 .SH CSTORE TYPE OPTIONS
 208 .PP
 209 The
 210 .B cstore
 211 type is used to parse Content Store records.
 212 .TP
 213 .B \-l
 214 List the filenames and folders found in the Content Store database.
 215 .TP
 216 .B \-f file
 217 Select a filename from the above list to extract and save locally.
 218 Specify the entire path as shown in the \-l list.
 219 If the file is found in the device, it will be written to the current
 220 directory, using the base filename as the name.  If a file by that name
 221 exists already, the filename will be modified to avoid overwriting local
 222 files.
 223
 224 .SH STANDALONE OPTIONS
 225 .TP
 226 .B \-h
 227 Displays a detailed summary of command line options.
 228 .TP
 229 .B \-I cs
 230 Set the international charset for string conversions.  Valid values here
 231 are available with
 232 .B iconv \-\-list
 233 .TP
 234 .B \-S
 235 Show list of supported database parsers and builders.
 236 .TP
 237 .B \-v
 238 Dump verbose low level protocol data during USB operations, to stdout.
 239
 240
 241
 242
 243 .SH EXAMPLES
 244 .TP
 245 1) Backup a full device to tar backup:
 246 .IP
 247 bio -i device -A -o tar -f mybackup.tar.gz
 248 .TP
 249 2) Read a backup file and convert the Address Book to MIME
 250 .IP
 251 bio -i tar -f mybackup.tar.gz -d "Address Book" -o mime
 252 .TP
 253 3) Copy the Calendar from one device to another, and dump
 254 the records to stdout in human readable format at the same time
 255 .IP
 256 bio -i device -p 3009efe3 -d Calendar -o device -p 204062f3 -w erase -o dump
 257 .TP
 258 4) Read LDIF input and convert the contacts to MIME format
 259 .IP
 260 ldapsearch -x | bio -i ldif -o mime
 261 .TP
 262 5) Test the record code by running the Tasks database through
 263 the Boost storage and back to human readable
 264 .IP
 265 bio -i device -d Tasks -o dump
 266
 267 vs.
 268
 269 bio -i device -d Tasks -o boost -f - | bio -i boost -f - -o dump
 270
 271 .SH AUTHOR
 272 .nh
 273 .B bio
 274 is part of the Barry project.
 275 .SH SEE ALSO
 276 .PP
 277 http://www.netdirect.ca/barry
 278