pilot-xfer - Backup, sync, and restore databases from a
Palm handheld device.
SECTION
pilot-link: Userland Conduits
SYNOPSIS
pilot-xfer [-p <port>] [-e <file>] [-b] [-u] [-s] <direc-
tory>
or
pilot-xfer [-p <port>] [-r <directory>] [-l] [-L] [-P] [-f
<dbname>] [-d <dbname>] [-i <dbname>] [-m <file>] ...
Use exactly one of -brsudfimlI; mix in -aexDPv, --rom and
--with-os.
DESCRIPTION
This is the swiss-army-knife of the entire pilot-link
suite.
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) for-
mats 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.
OPTIONS
PILOT-XFER OPTIONS
-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).
-C, --cardinfo
Show information on available cards
--delete <dbname>
Permanently delete the specified database(s) by
name (without extension). Obviously, be very care-
ful with this one.
-D, --vfsdir=dir
Modifies -l, -i or -f to use VFS dir instead of
Reads a list of databases from <file> and prevents
--backup, --sync, or --update from operating on the
listed database(s). A maximum of 100 databases can
be excluded. Databases should be specified by name
without the extension, as displayed with --list, in
any order.
-f, --fetch <dbname>
Fetch each specified database out of the Palm into
the current directory.
-F, --Flash
Obsolete. Replaced by --rom in v0.12.
-i, --install <file> [...]
Install each specified file into the Palm. Wild-
cards are valid with this syntax and multiple files
may be listed at once.
-l, --list
Note: changed behaviour in 0.12
List all the databases in the Palm, including
OS-specific native databases.
-L, --Listall
Unsupported in 0.12 - see -l
-m, --merge <file> [...]
Adds the records in each specified file into the
corresponding Palm database.
-O, --Osflash
Obsolete. Replaced by --with-os in 0.12
-P, --Purge
Purge any deleted data that hasn't been cleaned up
by a sync (this is a safe operation, and will pre-
vent 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.)
--rom
Modifies -b, -u, and -s , to back up non-OS dbs
from Flash ROM
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 mod-
ified 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.
-S, --novsf
Not supported in 0.12. No replacement.
--with-os
Modifies -b, -u, and -s , to back up OS dbs from
Flash ROM.
-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 mod-
ified or created since the versions stored in the
specified directory will not be backed up.
-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.
-x, --exec=command
Execute a shell command for intermediate process-
ing. All commands will be done, from left to right
in the command-line, before the connection to the
pilot is made.
CONDUIT OPTIONS
-p, --port <port>
Use device file <port> to communicate with the Palm
handheld. If this is not specified, pilot-xfer will
look for the $PILOTPORT environment variable. If
neither are found, pilot-xfer will print the usage
information.
-v, --version
Display version of pilot-xfer and exit without con-
necting.
-q, --quiet
-h, --help
Display the help synopsis for pilot-xfer and exit
without connecting.
--usage
Display a brief usage message and exit without con-
necting.
USAGE
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 command-
line.
EXAMPLES
To perform 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
AUTHOR
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. Updated for 0.12 by Neil Williams linux@code-
help.co.uk.
BUGS
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.
Report bugs at http://bugs.pilot-link.org/
COPYRIGHT
This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any
later version.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111-1307 USA
SEE ALSO
pilot-link(7)
Man(1) output converted with
man2html