Man Linux: Main Page and Category List


       btool - Barry Project’s program to interface with BlackBerry handheld


       btool  [-B  busname][-N  devname][-a  db][-c  dn][-C  dnattr][-d db [-f
       file][-r#][-R#]-D#]][-h][-l][-L][-m cmd][-M][-p pin][-P password][-s db
       -f file][-S][-t][-v][-X][-z][-Z]


       btool is a program that communicates with a BlackBerry device over USB;
       there is no intention  to  support  ancient  serial-port  BlackBerries.
       Since  the  protocols  used  by  BlackBerry  are  not documented by the
       manufacturer Research In Motion, this program is experimental  and  you
       use  at  own risk.  Be sure your device is backed up by another program
       if it contains important data.


       -B busname
              Specify the USB bus to search for Blackberry devices  on.   This
              is  the  first  number  displayed  in  the output from the lsusb
              command, such as 002.  If the busname is numeric on your system,
              2  and 002 are equal.  See also the -N option, which can be used
              together with this option to precisely select the device to work

       -a db  Delete  all  records  from specified database.  This can be used
              multiple times to clear multiple databases.

       -c dn  Convert  address  book  database  to  LDIF  format,  using   the
              specified dn as the baseDN.  Sends LDIF output to stdout.

       -C dnattr
              Spcify  LDIF attribute name to use when building the FQDN in the
              dn attribute.  Defaults to ’cn’.  If you modify the mapping with
              the -m switch, make sure that the new dnattr exists.

       -d db  Load  database ’db’ FROM device and dump to stdout.  Can be used
              multiple times to fetch more than  one  database.   See  the  -t
              option for a list of device databases.

       -e epp Override  endpoint  pair  detection.   ’epp’  is a single string
              separated by a comma, holding the read,write endpoint pair.

              Example: -e 83,5

              Note: Endpoints are specified in  hex.   Use  the  same  numbers
              given by the lsusb -v output.

              You  should  never  need  to  use  this option, as endpoints are

       -f file
              Filename to write  or  read  handheld  data  to/from.   Used  in
              conjunction with the -d and -s options, respectively.  Note: the
              file format of this file  is  not  backward  compatible  between
              devel releases.

       -i charset
              Specifies  the iconv charset to use for converting international
              strings.  The Blackberry uses the WINDOWS-1252 charset, which is
              incompatible with the more common code pages used in Linux.  The
              most useful charset to use with this option  is  UTF-8,  and  is
              highly  recommended.   Any  other  charset  available via ’iconv
              --list’ can be used here too, but may not be successful for some
              character conversions.

       -l     Lists attached Blackberry devices, and their PIN numbers.

       -L     List  Contact field names.  Each name represents a contact field
              that the Barry library recognizes.  Use these names with the  -m
              option to adjust the LDIF name to field mapping.

       -m command
              Map  LDIF  name  to Contact field, or unmap LDIF name.  To map a
              new or existing LDIF attribute name to a  Barry  contact  field,
              use  the format ’ldif,read,write’ where ldif represents the name
              of the attribute to map, read is the contact field name used  to
              read  data  from the record, and write is the contact field name
              used to write data to the record.

              To unmap an LDIF name, specify the LDIF attribute alone.

              For example, to map a new LDIF  attribute  called  "strange"  to
              read from FirstName and write to LastName, use:

              -m strange,FirstName,LastName

              The  -m  option  can  be  specified multiple times to create the
              desired mapping.

       -M     List current LDIF mapping to stdout.

       -N devname
              Specify  the  USB  device  name.   This  is  the  second  number
              displayed in the output from the lsusb command, such as 005.  If
              the device name is numeric on your system, 5 and 005 are  equal.
              See also the -B option.

       -p pin PIN  of  device to talk with.  Only needed if you have more than
              one Blackberry connected at once.

       -P password
              Simplistic  method  to  specify  device  password.   In  a  real
              application, this would be done using a more secure prompt.

       -s db  Save database ’db’ TO device from data loaded from -f file.  See
              the -t option for a list of device databases.

       -S     Show list of supported database parsers and  builders.   Parsers
              are  used  when reading data out of the device, and builders are
              used when writing data to the device.  If a parser is supported,
              but  its associated builder is not, that means you cannot change
              the database programmatically, such as with the -s option.

       -t     Show device’s database table.

       -T db  Show record state table for given database.

       -v     Dump verbose protocol data during operation.

       -X     Reset device.

       -z     Use non-threaded sockets when  communicating  with  the  device.
              This  is  the behaviour seen in versions 0.12 and earlier, since
              threads were not yet supported.  This option, along with -Z, are
              for debugging and testing.

       -Z     Use a threaded socket router when communicating with the device.
              This is the default for btool.  This option, along with -Z,  are
              for debugging and testing.

       -h, --help
              Show summary of options.


       The  following  options  modify the -d command option above, and can be
       used multiple times for more than one record.

       -r #   Fetch specific record, given a record index number  as  seen  in
              the  -T  state  table.   Can  be  used  multiple  times to fetch
              specific records from a single database.

       -R #   Same as -r, but also clears the record’s dirty flags.

       -D #   Delete the specified record using the index number  as  seen  in
              the -T state table.


       btool  is  part  of the Barry project.  This manual page was written by
       Ian Darwin and Chris Frey.

       Especially the caveats, and the call for developers and others to  help
       with the project.

                                  May 6, 2008