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

USAGE

274       The program will attempt to connect to a target  Palm  handheld  device
275       and  specified  port and perform the requested options specified by the
276       user on the commandline.
277
278

EXAMPLES

280       To perform a full backup of your Palm handheld:
281
282
283       # using long options
284
285
286          pilot-xfer --port /dev/pilot --backup $HOME/pilot/Backup
287
288
289
290
291       # or over IrDA, using short options
292
293
294          pilot-xfer -p /dev/ircomm0 -b $HOME/pilot/Backup
295
296
297
298
299       To restore that backup to a non-standard serial port (for example, to a
300       xcopilot or POSE session, assuming you have xcopilot or POSE configured
301       properly for this operation, see the appropriate man pages for  details
302       on configuring your emulator):
303
304
305          pilot-xfer -p /dev/ttyqe --restore $HOME/pilot/Backup
306
307
308
309
310       To fetch a file that is on your Palm handheld, such as the Palm Address
311       Book database, you  could  do  the  following.  This  will  connect  to
312       /dev/pilot  and  retrieve the records found in AddressDB and place them
313       in a local file called AddressDB.pdb (Palm Record Database).
314
315
316          pilot-xfer -p /dev/pilot --fetch AddressDB
317
318
319
320
321       This will connect to your Palm device and install the  application  Foo
322       (in  Foo.prc)  to  your  external  storage card (typically an SD or MMC
323       card) in the directory /Palm/Launcher on that card, using VFS.
324
325
326          pilot-xfer -p /dev/pilot -i Foo.prc -D /Palm/Launcher
327
328
329
330

AUTHOR

332        pilot-xfer written by Kenneth Albanowski. This manual page was  origi‐
333       nally  written  by  Kenneth  Albanowski and David H. Silber. Completely
334       rewritten by David A. Desrosiers. Updated for 0.12 by Neil  Williams  <
335       linux@codehelp.co.uk > .
336
337

BUGS

339   Known Bugs
340        --backup will currently truncate/corrupt pdb/prc files if the communi‐
341       cation to the device is interrupted during sync (such as  removing  the
342       Palm  from the cradle, or a temporary network hiccup during a NetSync).
343       Ideally, this should restore the original file, or delete the corrupted
344       version   and  restore  the  original  version  back  into  place,  but
345       presently.. it does not.
346
347
348   Reporting Bugs
349       We have an online bug tracker. Using this is the  only  way  to  ensure
350       that  your  bugs are recorded and that we can track them until they are
351       resolved or closed. Reporting bugs via email, while easy, is  not  very
352       useful  in  terms  of  accountability.  Please  point  your  browser to
353       http://bugs.pilot-link.org: http://bugs.pilot-link.org and report  your
354       bugs and issues there.
355
356

COPYRIGHT

358       This program is free software; you can redistribute it and/or modify it
359       under the terms of the GNU General Public License as published  by  the
360       Free  Software Foundation; either version 2 of the License, or (at your
361       option) any later version.
362
363
364       This program is distributed in the hope that it  will  be  useful,  but
365       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER‐
366       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the  GNU  General
367       Public License for more details.
368
369
370       You should have received a copy of the GNU General Public License along
371       with this program; if not, write to the Free Software Foundation, Inc.,
372       51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
373
374