man/btool.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 BTOOL 1 "February 3, 2012"
   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 btool
  20 \- Barry Project's program to interface with BlackBerry handheld
  21 .SH SYNOPSIS
  22 .B btool
  23 [\-B busname][\-N devname][\-a db][\-c dn][\-C dnattr][\-d db [\-f file][\-F sortkey][\-r#][\-R#]\-D#]][\-h][\-i charset][\-l][\-L][\-m cmd][\-M][\-p pin][\-P password][\-s db \-f file][\-S][\-t][\-v][\-V][\-X][\-z][\-Z]
  24 .SH DESCRIPTION
  25 .PP
  26 .B btool
  27 is a program that communicates with a
  28 BlackBerry device over USB; there is no intention to support ancient
  29 serial\-port BlackBerries.
  30 Since the protocols used by BlackBerry are not documented
  31 by the manufacturer Research In Motion, this program is
  32 experimental and you \fBuse at own risk\fP.
  33 Be sure your device is backed up by another program
  34 if it contains important data.
  35 .SH OPTIONS
  36 .TP
  37 .B \-B busname
  38 Specify the USB bus to search for Blackberry devices on.  This is the
  39 first number displayed in the output from the lsusb command, such as 002.
  40 If the busname is numeric on your system, 2 and 002 are equal.  See
  41 also the \-N option, which can be used together with this option
  42 to precisely select the device to work with.
  43 .TP
  44 .B \-a db
  45 Delete all records from specified database.  This can be used multiple
  46 times to clear multiple databases.
  47 .TP
  48 .B \-c dn
  49 Convert address book database to LDIF format, using the
  50 specified dn as the baseDN.  Sends LDIF output to stdout.
  51 .TP
  52 .B \-C dnattr
  53 Spcify LDIF attribute name to use when building the FQDN in the dn attribute.
  54 Defaults to 'cn'.  If you modify the mapping with the \-m
  55 switch, make sure that the new dnattr exists.
  56 .TP
  57 .B \-d db
  58 Load database 'db' FROM device and dump to stdout.
  59 Can be used multiple times to fetch more than one database.  See the \-t
  60 option for a list of device databases.
  61 .TP
  62 .B \-e epp
  63 Override endpoint pair detection.  'epp' is a single string separated
  64 by a comma, holding the read,write endpoint pair.
  65
  66 Example: \-e 83,5
  67
  68 Note: Endpoints are specified in hex.  Use the same numbers given by the
  69 lsusb \-v output.
  70
  71 You should never need to use this option, as endpoints are autodetected.
  72 .TP
  73 .B \-f file
  74 Filename to write or read handheld data to/from.  Used in conjunction with
  75 the \-d and \-s options, respectively.  Note: the file format of this file
  76 is not backward compatible between devel releases.
  77 .TP
  78 .B \-F sortkey
  79 Sort the \-d database output according to the given sortkey.
  80 Note that the format of this field is special: 'DBName:field1,field2'
  81
  82 It contains no spaces, unless the spaces are part of the name.
  83
  84 This option can be used multiple times, to match your \-d options.
  85
  86 Example: If you used the following command:
  87
  88 btool \-d 'Address Book'
  89
  90 You could use the following sort key to sort by Company name first,
  91 with a subsort of last and first names.
  92
  93 \-F 'Address Book:Company,LastName,FirstName'
  94 .TP
  95 .B \-i charset
  96 Specifies the iconv charset to use for converting international strings.
  97 The Blackberry uses the WINDOWS\-1252 charset, which is incompatible with
  98 the more common code pages used in Linux.  The most useful charset to use
  99 with this option is UTF\-8, and is highly recommended.  Any other charset
 100 available via 'iconv \-\-list' can be used here too, but may not be
 101 successful for some character conversions.
 102 .TP
 103 .B \-I
 104 Sort records before dumping them to stdout.  This uses the default library
 105 sorting order, which is specific to each database.
 106 .TP
 107 .B \-l
 108 Lists attached Blackberry devices, and their PIN numbers.
 109 .TP
 110 .B \-L
 111 List Contact field names.  Each name represents a contact field that the
 112 Barry library recognizes.  Use these names with the \-m option to adjust
 113 the LDIF name to field mapping.
 114 .TP
 115 .B \-m command
 116 Map LDIF name to Contact field, or unmap LDIF name.  To map a new or existing
 117 LDIF attribute name to a Barry contact field, use the format 'ldif,read,write'
 118 where ldif represents the name of the attribute to map, read is the
 119 contact field name used to read data from the record, and write is the
 120 contact field name used to write data to the record.
 121
 122 To unmap an LDIF name, specify the LDIF attribute alone.
 123
 124 For example, to map a new LDIF attribute called "strange" to read from
 125 FirstName and write to LastName, use:
 126
 127 \-m strange,FirstName,LastName
 128
 129 The \-m option can be specified multiple times to create the desired mapping.
 130 .TP
 131 .B \-M
 132 List current LDIF mapping to stdout.
 133 .TP
 134 .B \-N devname
 135 Specify the USB device name.  This is the second number displayed in the
 136 output from the lsusb command, such as 005.  If the device name is numeric
 137 on your system, 5 and 005 are equal.  See also the \-B option.
 138 .TP
 139 .B \-p pin
 140 PIN of device to talk with.  Only needed if you have more than one Blackberry
 141 connected at once.
 142 .TP
 143 .B \-P password
 144 Simplistic method to specify device password.  In a real application, this
 145 would be done using a more secure prompt.
 146 .TP
 147 .B \-s db
 148 Save database 'db' TO device from data loaded from \-f file.  See the \-t
 149 option for a list of device databases.
 150 .TP
 151 .B \-S
 152 Show list of supported database parsers and builders.  Parsers are used
 153 when reading data out of the device, and builders are used when writing
 154 data to the device.  If a parser is supported, but its associated builder
 155 is not, that means you cannot change the database programmatically, such
 156 as with the \-s option.
 157 .TP
 158 .B \-t
 159 Show device's database table.
 160 .TP
 161 .B \-T db
 162 Show record state table for given database.
 163 .TP
 164 .B \-v
 165 Dump verbose protocol data during operation.
 166 .TP
 167 .B \-V
 168 Enable vformat MIME output where available.  Address Book gets printed
 169 in vCard format, Calendar in vEvent format, Memos in vJournal, and
 170 Tasks in vTodo, etc.
 171 .TP
 172 .B \-X
 173 Perform a USB reset on the device.  Similar to the breset command,
 174 and does a virtual "replug" of the device.
 175 .TP
 176 .B \-z
 177 Use non\-threaded sockets when communicating with the device.  This is
 178 the behaviour seen in versions 0.12 and earlier, since threads were
 179 not yet supported.  This option, along with \-Z, are for debugging
 180 and testing.
 181 .TP
 182 .B \-Z
 183 Use a threaded socket router when communicating with the device.
 184 This is the default for btool.  This option, along with \-Z, are for
 185 debugging and testing.
 186 .TP
 187 .B \-h, \-\-help
 188 Show summary of options.
 189
 190 .SH DATABASE COMMAND MODIFIERS
 191 The following options modify the \-d command option above, and can be used
 192 multiple times for more than one record.
 193 .TP
 194 .B \-r #
 195 Fetch specific record, given a record index number as seen in the \-T state table.
 196 Can be used multiple times to fetch specific records from a single database.
 197 .TP
 198 .B \-R #
 199 Same as \-r, but also clears the record's dirty flags.
 200 .TP
 201 .B \-D #
 202 Delete the specified record using the index number as seen in the \-T state table.
 203
 204
 205 .SH AUTHOR
 206 .nh
 207 .B btool
 208 is part of the Barry project.
 209 This manual page was written by Ian Darwin and Chris Frey.
 210 .SH SEE ALSO
 211 .PP
 212 http://www.netdirect.ca/software/packages/barry
 213 .br
 214 Especially the caveats, and the call for developers and others
 215 to help with the project.
 216