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 "May 17, 2011"
   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> [input args] -o <output type> [output args] [-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 .IP
 104 .B erase
 105 Erases all records from existing database and adds all new records to the
 106 device, using their Unique IDs, if available.  This is what you would normally
 107 use to restore a backup.
 108
 109 .B overwrite
 110 Adds any new records, and for records with Unique IDs that already exist
 111 on the device, overwrite them.
 112
 113 .B addonly
 114 Adds any new records, but if a record exists in the device with the same
 115 Unique ID, skip that record and don't write it to the device.
 116
 117 .B addnew
 118 Adds all incoming records as brand new records, generating a new Unique ID
 119 for each one, and leaving any existing records intact.  This may cause
 120 data duplication if you're restoring data that initially came from this
 121 same device.  Use this for copying data from another device, while keeping
 122 your existing records.
 123
 124 .PP
 125
 126 .\".SH DATABASE COMMAND MODIFIERS (DEVICE)
 127 .\"The following options modify the -d command option above, and can be used
 128 .\"multiple times for more than one record.
 129 .\".TP
 130 .\".B \-r #
 131 .\"Fetch specific record, given a record index number as seen in the -T state table.
 132 .\"Can be used multiple times to fetch specific records from a single database.
 133 .\".TP
 134 .\".B \-R #
 135 .\"Same as -r, but also clears the record's dirty flags.
 136 .\".TP
 137 .\".B \-D #
 138 .\"Delete the specified record using the index number as seen in the -T state table.
 139
 140 .SH TAR TYPE OPTIONS
 141 .PP
 142 The
 143 .B tar
 144 type is used to read or write from a backup file created by btool or
 145 the backup GUI.
 146 .TP
 147 .B \-d db
 148 Name of database to load, when using the
 149 .B tar
 150 type as input.  Can be used multiple times.
 151 .B Note
 152 that if no \-d options are specified,
 153 .B bio
 154 defaults to reading all available databases.
 155 .TP
 156 .B \-f file
 157 The tar backup file to read or write from.
 158 .B Bio
 159 uses gzip compressed tar files, so suitable extensions would be .tgz
 160 and .tar.gz.  Unfortunately, due to internal limitations,
 161 an actual file must be specified here, and not \- for stdin / stdout.
 162
 163 .SH BOOST TYPE OPTIONS
 164 .PP
 165 The
 166 .B boost
 167 type is used to read and write parsable records in Boost Serialization
 168 format.  These files were historically written and read by
 169 .B btool
 170 and
 171 .B bs11nread.
 172 .B Bio
 173 is more flexible, in that it can contain multiple databases in one
 174 serialization archive.
 175 .TP
 176 .B \-f file
 177 Filename to read from or write to.  Use \- to specify stdin or stdout.
 178 If not specified for input, defaults to stdin, but since output can
 179 contain non-ASCII chars, you must use \-f \- if you want to write
 180 to stdout.
 181
 182 .SH LDIF TYPE OPTIONS
 183 .PP
 184 The
 185 .B ldif
 186 type is used to read or write ldif output, like the output of the
 187 LDAP command line tool
 188 .B ldapsearch.
 189 .TP
 190 .B \-c dn
 191 When using ldif as output, specify the base DN.
 192 .TP
 193 .B \-C dnattr
 194 Again, for output, specify the attribute name to use when building the FQDN.
 195
 196 .SH MIME TYPE OPTIONS
 197 .PP
 198 The
 199 .B mime
 200 type is used to read or write VCARD, VEVENT, VTODO, or VJOURNAL records
 201 based on the Address Book, Calendar, Tasks, or Memos databases respectively.
 202 .TP
 203 .B \-f file
 204 Filename to read from or write to.  Defaults to \- for stdin or stdout.
 205
 206 .SH DUMP TYPE OPTIONS
 207 .PP
 208 The
 209 .B dump
 210 type is used only for output, and sends human readable record data to
 211 stdout.  Parsable records are parsed; unknown records are dumped in hex
 212 format.
 213 .TP
 214 .B \-n
 215 Use hex format for all records.
 216
 217 .SH SHA1 TYPE OPTIONS
 218 .PP
 219 The
 220 .B sha1
 221 type is used to mimic the behaviour of the
 222 .B brecsum
 223 command.  It calculates a SHA1 sum on the raw record data and sends
 224 the sum to stdout.
 225 .TP
 226 .B \-t
 227 Include the DB Name, Type, and Unique record ID in the checksum for each
 228 record.
 229
 230 .SH CSTORE TYPE OPTIONS
 231 .PP
 232 The
 233 .B cstore
 234 type is used to parse Content Store records.
 235 .TP
 236 .B \-l
 237 List the filenames and folders found in the Content Store database.
 238 .TP
 239 .B \-f file
 240 Select a filename from the above list to extract and save locally.
 241 Specify the entire path as shown in the \-l list.
 242 If the file is found in the device, it will be written to the current
 243 directory, using the base filename as the name.  If a file by that name
 244 exists already, the filename will be modified to avoid overwriting local
 245 files.
 246
 247 .SH STANDALONE OPTIONS
 248 .TP
 249 .B \-h
 250 Displays a detailed summary of command line options.
 251 .TP
 252 .B \-I cs
 253 Set the international charset for string conversions.  Valid values here
 254 are available with
 255 .B iconv \-\-list
 256 .TP
 257 .B \-S
 258 Show list of supported database parsers and builders.
 259 .TP
 260 .B \-v
 261 Dump verbose low level protocol data during USB operations, to stdout.
 262
 263
 264
 265
 266 .SH EXAMPLES
 267 .TP
 268 1) Backup a full device to tar backup:
 269 .IP
 270 bio -i device -A -o tar -f mybackup.tar.gz
 271 .TP
 272 2) Read a backup file and convert the Address Book to MIME
 273 .IP
 274 bio -i tar -f mybackup.tar.gz -d "Address Book" -o mime
 275 .TP
 276 3) Restore a single database to a device
 277 .IP
 278 bio -i tar -f mybackup.tar.gz -d "Address Book" -o device -w erase
 279 .TP
 280 4) Copy the Calendar from one device to another, and dump
 281 the records to stdout in human readable format at the same time
 282 .IP
 283 bio -i device -p 3009efe3 -d Calendar -o device -p 204062f3 -w erase -o dump
 284 .TP
 285 5) Read LDIF input and convert the contacts to MIME format
 286 .IP
 287 ldapsearch -x | bio -i ldif -o mime
 288 .TP
 289 6) Test the record code by running the Tasks database through
 290 the Boost storage and back to human readable
 291 .IP
 292 bio -i device -d Tasks -o dump
 293
 294 vs.
 295
 296 bio -i device -d Tasks -o boost -f - | bio -i boost -f - -o dump
 297
 298 .SH AUTHOR
 299 .nh
 300 .B bio
 301 is part of the Barry project.
 302 .SH SEE ALSO
 303 .PP
 304 http://www.netdirect.ca/barry
 305