pilot-xfer - backup, sync, and restore databases from a Palm handheld device, such as those made from Palm, Handspring, Handera, TRGPro, Sony or other PalmOS-based handheld.

pilot-xfer [-p <port>] [-e <file>] [-b] [-u] [-s] <directory>

or

pilot-xfer [-p <port>] [-r <directory>] [-l] [-L] [-P] [-f <dbname>] [-d <dbname>] [-i <dbname>] [-m <file>] ...

(Note that some options are not shown above and short option aliases are excluded for brevity. Please use pilot-xfer --help to get the full list of available options).

pilot-xfer allows the user to install databases contained in the standard .prc (Palm Resource Database), .pdb (Palm Record Database), and .pqa (Palm Query Application) formats onto a Palm, retrieve databases from the Palm, list the databases contained in a Palm, and backup or restore all of the databases at once, and many other powerful operations.

-p, --port <port>

Use device file <port> to communicate with the Palm handheld. If this is not specified, will look for the $PILOTPORT environment variable. If both are not found, will fall back to /dev/pilot.

-h, --help

Display the help synopsis for install-user.

-v, --version

Display version of install-user.

-a, --archive <dir>

Archives files which have been removed from the Palm to <dir> instead of just deleting (unlinking) them.

-b, --backup <dir>

Backs up the Palm into the specified directory (which will be created if it does not already exist). This operation must be specified after any --exclude option.

-d, --delete <dbname>

Delete the specified database(s) by name (without extension). Obviously, be very careful with this one.

-e, --exclude <file>

Reads a list of databases from <file> and prevents --backup, --sync, or --update from operating on the listed database(s). This option must be specified before the --backup, --sync, or --update operation whose action it modifies.

-f, --fetch <dbname>

Fetch each specified database out of the Palm into the current directory.

-F, --Flash

Modifies the behavior of --backup, --sync, and --update to back up non-OS databases which have been stored in Flash ROM

-i, --install <file> [...]

Install each specified file into the Palm. Wildcards are valid with this syntax and multiple files may be listed at once.

-l, --list

List the databases in the Palm, excluding OS-specific databases.

-L, --Listall

List all of the databases on the Palm, including OS-specific native databases.

-m, --merge <file> [...]

Adds the records in each specified file into the corresponding Palm database.

-O, --Osflash

Modifies the behavior of --backup, --sync, and --update to back up OS databases which are stored in Flash ROM

-P, --Purge

Purge any deleted data that hasn't been cleaned up by a sync (this is a safe operation, and will prevent your Palm from accumulating crud if you delete records but aren't syncing with a PIM.) The only information you can lose is archived but un-synced records.

-r, --restore <dir>

Installs all files contained in a directory into the Palm. (Use this to restore your Palm after a hard reset has cleared its memory, using your backup directory as a baseline.)

-s, --sync <dir>

Backs up the Palm into the specified directory (which will be created if it does not already exist). Any Palm databases which have not been modified or created since the versions stored in the specified directory will not be backed up.

NOTE: Any Palm databases which have been deleted will have their corresponding backup file removed. This operation must be specified after any --exclude option.

-u, --update

Backs up the Palm into the specified directory (which will be created if it does not already exist). Any Palm databases which have not been modified or created since the versions stored in the specified directory will not be backed up. This operation must be specified after any --exclude option.

-I, --Illegal

This will back up the UnsavedPreferences.pdb file from the Palm. Normally this file is not backed up by normal means (Palm Computing recommends that you do not restore this file upon restoration of your device using --restore

This also modifies the behavior of --backup, --sync, and --update.

The program will connect to a target Palm handheld and port, prompt the user to hit HotSync, and perform the requested options specified by the user on the commandline.

To performa a full backup of your Palm handheld:

# using long options

pilot-xfer --port /dev/pilot --backup $HOME/pilot/Backup

or # over IrDA, using short options

pilot-xfer -p /dev/ircomm0 -b $HOME/pilot/Backup

To restore that backup to a non-standard serial port (for example, to a xcopilot or POSE session, assuming you have xcopilot or POSE configured properly for this operation, see the appropriate man pages for details on configuring your emulator):

pilot-xfer -p /dev/ttyqe --restore $HOME/pilot/Backup

To fetch a file that is on your Palm handheld, such as the Palm Address Book database:

pilot-xfer -p /dev/pilot --fetch AddressDB

KNOWN BUGS

--backup will currently truncate/corrupt pdb/prc files if communication is interrupted during sync. Ideally, this should restore the original file, or delete the corrupted version and restore the original version back into place.

REPORTING BUGS

Report bugs at http://bugs.pilot-link.org/

pilot-xfer written by Kenneth Albanowski. This manual page was originally written by Kenneth Albanowski and David H. Silber. Completely rewritten by David A. Desrosiers.

pilot-link(7)