BTOOL(1)						      General Commands Manual							  BTOOL(1)

NAME

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

SYNOPSIS

       btool  [-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]

DESCRIPTION

       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.

OPTIONS

       -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 with.

       -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 autodetected.

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

       -F sortkey
	      Sort the -d database output according to the given sortkey.  Note that the format of this field is special: 'DBName:field1,field2'

	      It contains no spaces, unless the spaces are part of the name.

	      This option can be used multiple times, to match your -d options.

	      Example: If you used the following command:

	      btool -d 'Address Book'

	      You could use the following sort key to sort by Company name first, with a subsort of last and first names.

	      -F 'Address Book:Company,LastName,FirstName'

       -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 con-
	      versions.

       -I     Sort records before dumping them to stdout.  This uses the default library sorting order, which is specific to each database.

       -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.

       -V     Enable vformat MIME output where available.  Address Book gets printed in vCard format, Calendar in vEvent format, Memos	in  vJour-
	      nal, and Tasks in vTodo, etc.

       -X     Perform a USB reset on the device.  Similar to the breset command, and does a virtual "replug" of the 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.

DATABASE COMMAND MODIFIERS

       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.

AUTHOR

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

SEE ALSO

       http://www.netdirect.ca/software/packages/barry
       Especially the caveats, and the call for developers and others to help with the project.

								 February 3, 2012							  BTOOL(1)