           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)