pilot-xfer(1)

1pilot-xfer(1)                     PILOT-LINK                     pilot-xfer(1)
2
3
4

NAME

6       pilot-xfer  -  Backup, sync, and restore databases from a Palm handheld
7       device.
8

SECTION

10       pilot-link: Userland conduits
11
12

SYNOPSIS

14        pilot-xfer [-p lt;port>] [-e lt;file>] [-b] [-u] [-s] <directory>
15
16
17       or
18
19
20        pilot-xfer  [-p  lt;port>]  [-r  lt;directory>]  [-l]  [-L]  [-P]  [-f
21       <dbname>] [-d <dbname>] [-i <dbname>] [-m <file>] ...
22
23
24       Use exactly one of -brsudfimlI; mix in -aexDPv, --rom and with-os.
25
26

DESCRIPTION

28       This is the swiss-army-knife of the entire pilot-link suite.
29
30
31        pilot-xfer allows the user to install databases contained in the stan‐
32       dard .prc (Palm Resource Database), .pdb (Palm  Record  Database),  and
33       .pqa  (Palm  Query Application) formats onto a Palm, retrieve databases
34       from the Palm, list the  databases  contained  in  a  Palm,  backup  or
35       restore  all  of  the  databases at once as well as many other powerful
36       operations performed on a Palm handheld device.
37
38

OPTIONS

40   pilot-xfer options
41                               -a, --archive
42                               <dir>
43
44
45       Archives files which have been removed from the Palm to lt;dir> instead
46       of just deleting (unlinking) them.
47
48                               -b, --backup
49                               <dir>
50
51
52       Backs  up  the Palm into the specified directory (which will be created
53       if it does not already exist).
54
55                               -C, --cardinfo
56
57
58       Show information on available cards
59
60                               --delete <dbname>
61
62
63       Permanently delete the specified database(s) by  name  (without  exten‐
64       sion). Obviously, be very careful with this one.
65
66                               -D,
67                               --vfsdir=dir
68
69
70       Modifies  -l,  -i or -f to use VFS dir instead of internal storage (see
71       examples section for usage)
72
73                               -e,
74                               --exclude=
75
76                                   <file>
77
78
79
80       Reads a list of databases from <file> and prevents --backup, --sync, or
81       --update  from  operating  on  the listed database(s). A maximum of 100
82       databases can be excluded. Databases should be specified by name  with‐
83       out the extension, as displayed with --list, in any order.
84
85                               -f, --fetch
86                               <dbname>
87
88
89       Fetch  each  specified database out of the Palm into the current direc‐
90       tory.
91
92                               -F, --Flash
93
94
95       Obsolete. Replaced by --rom in v0.12.
96
97                               -i, --install
98                               <file> [...]
99
100
101       Install each specified file into the Palm.  Wildcards  are  valid  with
102       this syntax and multiple files may be listed at once.
103
104                               -l, --list
105
106
107       Note: the behavior of list has changed in version 0.12 and later
108
109
110       List  all the databases in the Palm, including OS-specific native data‐
111       bases.
112
113                               -L, --Listall
114
115
116       Unsupported in 0.12 - see -l
117
118                               -m, --merge
119                               <file1> <file2> [...]
120
121
122       Adds the records in each specified file  into  the  corresponding  Palm
123       database.
124
125                               -O, --Osflash
126
127
128       Obsolete. Replaced by --with-os in v0.12 and later
129
130                               -P, --Purge
131
132
133       Purge  any deleted data that haven't been cleaned up by a full synchro‐
134       nization (this is a safe operation, and will  prevent  your  Palm  from
135       accumulating  unused data if you delete records but aren't syncing with
136       a PIM.) The only information you can lose is archived  but  un-synchro‐
137       nized records.
138
139                               -r, --restore
140                               <dir>
141
142
143       Installs  all  files contained in the named directory to the Palm. (Use
144       this to restore your Palm after a hard reset has cleared and wiped  its
145       memory, using your backup directory as a baseline).
146
147                               --rom
148
149
150       Modifies -b, -u, and  s , to back up non-OS dbs from the internal Flash
151       ROM
152
153                               -s, --sync
154                               <dir>
155
156
157       Backs up the Palm into the specified directory (which will  be  created
158       if  it  does not already exist). Any Palm databases which have not been
159       modified or created since the versions stored in the  specified  direc‐
160       tory will not be backed up.
161
162
163        NOTE:  Any Palm databases which have been deleted will have their cor‐
164       responding backup file removed.
165
166                               -S, --novsf
167
168
169       Not supported in v0.12. No replacement.
170
171                               --with-os
172
173
174       Modifies -b, -u, and  s , to back up OS databases from  internal  Flash
175       ROM.
176
177                               -u, --update
178
179
180       Backs  up  the Palm into the specified directory (which will be created
181       if it does not already exist). Any Palm databases which have  not  been
182       modified  or  created since the versions stored in the specified direc‐
183       tory will not be backed up.
184
185                               -I, --Illegal
186
187
188       This will back up the UnsavedPreferences.prc file from the  Palm.  Nor‐
189       mally  this file is not backed up by normal means (Palm recommends that
190       you do not restore this file upon  restoration  of  your  device  using
191       --restore.
192
193
194       This also modifies the behavior of --backup, --sync, and --update.
195
196                               -x, --exec=command
197
198
199       Execute  a shell command for intermediate processing. All commands will
200       be done, from left to right on the command-line, before the  connection
201       to the Palm device is made.
202
203
204   Conduit Options
205                               -p, --port
206                               <port>
207
208
209       Use  device  file <port> to communicate with the Palm handheld. If this
210       is not specified, pilot-xfer will look for the  $PILOTPORT  environment
211       variable.  If  neither  are  found,   pilot-xfer   will print the usage
212       information.
213
214                               -v, --version
215
216
217       Display version of pilot-xfer and exit without connecting.
218
219
220   Help Options
221                               -h, --help
222
223
224       Display the help synopsis for pilot-xfer and exit without connecting.
225
226                               --usage
227
228
229       Display a brief usage message and exit without connecting.
230
231

USAGE

233       The program will attempt to connect to a target  Palm  handheld  device
234       and  specified  port and perform the requested options specified by the
235       user on the commandline.
236
237

EXAMPLES

239       To perform a full backup of your Palm handheld:
240
241
242       # using long options
243
244
245                       pilot-xfer --port /dev/pilot
246                           --backup
247
248                       $HOME/pilot/Backup
249
250
251
252
253       # or over IrDA, using short options
254
255
256                       pilot-xfer -p /dev/ircomm0 -b
257                           $HOME/pilot/Backup
258
259
260
261
262
263       To restore that backup to a non-standard serial port (for example, to a
264       xcopilot or POSE session, assuming you have xcopilot or POSE configured
265       properly for this operation, see the appropriate man pages for  details
266       on configuring your emulator):
267
268
269                       pilot-xfer -p /dev/ttyqe --restore
270                           $HOME/pilot/Backup
271
272
273
274
275
276       To fetch a file that is on your Palm handheld, such as the Palm Address
277       Book database, you  could  do  the  following.  This  will  connect  to
278       /dev/pilot  and  retrieve the records found in AddressDB and place them
279       in a local file called AddressDB.pdb (Palm Record Database).
280
281
282                       pilot-xfer -p /dev/pilot --fetch
283                           AddressDB
284
285
286
287
288
289       This will connect to your Palm device and install the  application  Foo
290       (in  Foo.prc)  to  your  external  storage card (typically an SD or MMC
291       card) in the directory /Palm/Launcher on that card, using VFS.
292
293
294                       pilot-xfer -p /dev/pilot -i Foo.prc
295                           -D /Palm/Launcher
296
297
298
299
300

AUTHOR

302        pilot-xfer written by Kenneth Albanowski. This manual page was  origi‐
303       nally  written  by  Kenneth  Albanowski and David H. Silber. Completely
304       rewritten by David A. Desrosiers. Updated for 0.12 by Neil  Williams  <
305       linux@codehelp.co.uk > .
306
307

BUGS

309   Known Bugs
310        --backup will currently truncate/corrupt pdb/prc files if the communi‐
311       cation to the device is interrupted during sync (such as  removing  the
312       Palm  from the cradle, or a temporary network hiccup during a NetSync).
313       Ideally, this should restore the original file, or delete the corrupted
314       version   and  restore  the  original  version  back  into  place,  but
315       presently.. it does not.
316
317
318   Reporting Bugs
319       We have an online bug tracker. Using this is the  only  way  to  ensure
320       that  your  bugs are recorded and that we can track them until they are
321       resolved or closed. Reporting bugs via email, while easy, is  not  very
322       useful  in  terms  of  accountability.  Please  point  your  browser to
323       http://bugs.pilot-link.org: http://bugs.pilot-link.org and report  your
324       bugs and issues there.
325
326

COPYRIGHT

328       This program is free software; you can redistribute it and/or modify it
329       under the terms of the GNU General Public License as published  by  the
330       Free  Software Foundation; either version 2 of the License, or (at your
331       option) any later version.
332
333
334       This program is distributed in the hope that it  will  be  useful,  but
335       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER‐
336       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the  GNU  General
337       Public License for more details.
338
339
340       You should have received a copy of the GNU General Public License along
341       with this program; if not, write to the Free Software Foundation, Inc.,
342       51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
343
344