Version 1.5.21.
[libguestfs.git] / po-docs / ja.po
1 # SOME DESCRIPTIVE TITLE.
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
4 #
5 #, fuzzy
6 msgid ""
7 msgstr ""
8 "Project-Id-Version: PACKAGE VERSION\n"
9 "Report-Msgid-Bugs-To: libguestfs@redhat.com\n"
10 "POT-Creation-Date: 2010-10-01 21:02+0200\n"
11 "PO-Revision-Date: 2010-09-02 14:46+0100\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
14 "Language: \n"
15 "MIME-Version: 1.0\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
18
19 # type: =encoding
20 #: ../src/guestfs.pod:1 ../fish/guestfish.pod:1
21 #: ../test-tool/libguestfs-test-tool.pod:1 ../fuse/guestmount.pod:1
22 #: ../inspector/virt-inspector.pl:36 ../tools/virt-edit.pl:31
23 #: ../tools/virt-win-reg.pl:34 ../tools/virt-df.pl:32 ../tools/virt-ls.pl:31
24 #: ../tools/virt-resize.pl:38 ../tools/virt-list-filesystems.pl:28
25 #: ../tools/virt-cat.pl:30 ../tools/virt-tar.pl:30 ../tools/virt-rescue.pl:29
26 #: ../tools/virt-make-fs.pl:33 ../tools/virt-list-partitions.pl:28
27 msgid "utf8"
28 msgstr ""
29
30 # type: =head1
31 #: ../src/guestfs.pod:3 ../fish/guestfish.pod:3
32 #: ../test-tool/libguestfs-test-tool.pod:3 ../fuse/guestmount.pod:3
33 #: ../inspector/virt-inspector.pl:38 ../tools/virt-edit.pl:33
34 #: ../tools/virt-win-reg.pl:36 ../tools/virt-df.pl:34 ../tools/virt-ls.pl:33
35 #: ../tools/virt-resize.pl:40 ../tools/virt-list-filesystems.pl:30
36 #: ../tools/virt-cat.pl:32 ../tools/virt-tar.pl:32 ../tools/virt-rescue.pl:31
37 #: ../tools/virt-make-fs.pl:35 ../tools/virt-list-partitions.pl:30
38 msgid "NAME"
39 msgstr "名前"
40
41 # type: textblock
42 #: ../src/guestfs.pod:5
43 msgid "guestfs - Library for accessing and modifying virtual machine images"
44 msgstr ""
45
46 # type: =head1
47 #: ../src/guestfs.pod:7 ../fish/guestfish.pod:7
48 #: ../test-tool/libguestfs-test-tool.pod:7 ../fuse/guestmount.pod:7
49 #: ../inspector/virt-inspector.pl:42 ../tools/virt-edit.pl:37
50 #: ../tools/virt-win-reg.pl:40 ../tools/virt-df.pl:38 ../tools/virt-ls.pl:37
51 #: ../tools/virt-resize.pl:44 ../tools/virt-list-filesystems.pl:34
52 #: ../tools/virt-cat.pl:36 ../tools/virt-tar.pl:36 ../tools/virt-rescue.pl:35
53 #: ../tools/virt-make-fs.pl:39 ../tools/virt-list-partitions.pl:34
54 msgid "SYNOPSIS"
55 msgstr ""
56
57 # type: verbatim
58 #: ../src/guestfs.pod:9
59 #, no-wrap
60 msgid ""
61 " #include <guestfs.h>\n"
62 " \n"
63 msgstr ""
64
65 # type: verbatim
66 #: ../src/guestfs.pod:11
67 #, no-wrap
68 msgid ""
69 " guestfs_h *g = guestfs_create ();\n"
70 " guestfs_add_drive (g, \"guest.img\");\n"
71 " guestfs_launch (g);\n"
72 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
73 " guestfs_touch (g, \"/hello\");\n"
74 " guestfs_umount (g, \"/\");\n"
75 " guestfs_sync (g);\n"
76 " guestfs_close (g);\n"
77 "\n"
78 msgstr ""
79
80 # type: verbatim
81 #: ../src/guestfs.pod:20
82 #, no-wrap
83 msgid ""
84 " cc prog.c -o prog -lguestfs\n"
85 "or:\n"
86 " cc prog.c -o prog `pkg-config libguestfs --cflags --libs`\n"
87 "\n"
88 msgstr ""
89
90 # type: =head1
91 #: ../src/guestfs.pod:24 ../fish/guestfish.pod:30
92 #: ../test-tool/libguestfs-test-tool.pod:11 ../fuse/guestmount.pod:16
93 #: ../inspector/virt-inspector.pl:48 ../tools/virt-edit.pl:51
94 #: ../tools/virt-win-reg.pl:64 ../tools/virt-df.pl:46 ../tools/virt-ls.pl:43
95 #: ../tools/virt-resize.pl:50 ../tools/virt-list-filesystems.pl:40
96 #: ../tools/virt-cat.pl:42 ../tools/virt-tar.pl:73 ../tools/virt-rescue.pl:51
97 #: ../tools/virt-make-fs.pl:47 ../tools/virt-list-partitions.pl:40
98 msgid "DESCRIPTION"
99 msgstr ""
100
101 # type: textblock
102 #: ../src/guestfs.pod:26
103 msgid ""
104 "Libguestfs is a library for accessing and modifying guest disk images.  "
105 "Amongst the things this is good for: making batch configuration changes to "
106 "guests, getting disk used/free statistics (see also: virt-df), migrating "
107 "between virtualization systems (see also: virt-p2v), performing partial "
108 "backups, performing partial guest clones, cloning guests and changing "
109 "registry/UUID/hostname info, and much else besides."
110 msgstr ""
111
112 # type: textblock
113 #: ../src/guestfs.pod:34
114 msgid ""
115 "Libguestfs uses Linux kernel and qemu code, and can access any type of guest "
116 "filesystem that Linux and qemu can, including but not limited to: ext2/3/4, "
117 "btrfs, FAT and NTFS, LVM, many different disk partition schemes, qcow, "
118 "qcow2, vmdk."
119 msgstr ""
120
121 # type: textblock
122 #: ../src/guestfs.pod:39
123 msgid ""
124 "Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, "
125 "what filesystem is in each LV, etc.).  It can also run commands in the "
126 "context of the guest.  Also you can access filesystems over FUSE."
127 msgstr ""
128
129 # type: textblock
130 #: ../src/guestfs.pod:44
131 msgid ""
132 "Libguestfs is a library that can be linked with C and C++ management "
133 "programs (or management programs written in OCaml, Perl, Python, Ruby, Java, "
134 "PHP, Haskell or C#).  You can also use it from shell scripts or the command "
135 "line."
136 msgstr ""
137
138 # type: textblock
139 #: ../src/guestfs.pod:49
140 msgid ""
141 "You don't need to be root to use libguestfs, although obviously you do need "
142 "enough permissions to access the disk images."
143 msgstr ""
144
145 # type: textblock
146 #: ../src/guestfs.pod:52
147 msgid ""
148 "Libguestfs is a large API because it can do many things.  For a gentle "
149 "introduction, please read the L</API OVERVIEW> section next."
150 msgstr ""
151
152 # type: =head1
153 #: ../src/guestfs.pod:55
154 msgid "API OVERVIEW"
155 msgstr ""
156
157 # type: textblock
158 #: ../src/guestfs.pod:57
159 msgid ""
160 "This section provides a gentler overview of the libguestfs API.  We also try "
161 "to group API calls together, where that may not be obvious from reading "
162 "about the individual calls in the main section of this manual."
163 msgstr ""
164
165 # type: =head2
166 #: ../src/guestfs.pod:62
167 msgid "HANDLES"
168 msgstr ""
169
170 # type: textblock
171 #: ../src/guestfs.pod:64
172 msgid ""
173 "Before you can use libguestfs calls, you have to create a handle.  Then you "
174 "must add at least one disk image to the handle, followed by launching the "
175 "handle, then performing whatever operations you want, and finally closing "
176 "the handle.  By convention we use the single letter C<g> for the name of the "
177 "handle variable, although of course you can use any name you want."
178 msgstr ""
179
180 # type: textblock
181 #: ../src/guestfs.pod:71
182 msgid "The general structure of all libguestfs-using programs looks like this:"
183 msgstr ""
184
185 # type: verbatim
186 #: ../src/guestfs.pod:74
187 #, no-wrap
188 msgid ""
189 " guestfs_h *g = guestfs_create ();\n"
190 " \n"
191 msgstr ""
192
193 # type: verbatim
194 #: ../src/guestfs.pod:76
195 #, no-wrap
196 msgid ""
197 " /* Call guestfs_add_drive additional times if there are\n"
198 "  * multiple disk images.\n"
199 "  */\n"
200 " guestfs_add_drive (g, \"guest.img\");\n"
201 " \n"
202 msgstr ""
203
204 # type: verbatim
205 #: ../src/guestfs.pod:81
206 #, no-wrap
207 msgid ""
208 " /* Most manipulation calls won't work until you've launched\n"
209 "  * the handle 'g'.  You have to do this _after_ adding drives\n"
210 "  * and _before_ other commands.\n"
211 "  */\n"
212 " guestfs_launch (g);\n"
213 " \n"
214 msgstr ""
215
216 # type: verbatim
217 #: ../src/guestfs.pod:87
218 #, no-wrap
219 msgid ""
220 " /* Now you can examine what partitions, LVs etc are available.\n"
221 "  */\n"
222 " char **partitions = guestfs_list_partitions (g);\n"
223 " char **logvols = guestfs_lvs (g);\n"
224 " \n"
225 msgstr ""
226
227 # type: verbatim
228 #: ../src/guestfs.pod:92
229 #, no-wrap
230 msgid ""
231 " /* To access a filesystem in the image, you must mount it.\n"
232 "  */\n"
233 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
234 " \n"
235 msgstr ""
236
237 # type: verbatim
238 #: ../src/guestfs.pod:96
239 #, no-wrap
240 msgid ""
241 " /* Now you can perform filesystem actions on the guest\n"
242 "  * disk image.\n"
243 "  */\n"
244 " guestfs_touch (g, \"/hello\");\n"
245 " \n"
246 msgstr ""
247
248 # type: verbatim
249 #: ../src/guestfs.pod:101
250 #, no-wrap
251 msgid ""
252 " /* You only need to call guestfs_sync if you have made\n"
253 "  * changes to the guest image.  (But if you've made changes\n"
254 "  * then you *must* sync).  See also: guestfs_umount and\n"
255 "  * guestfs_umount_all calls.\n"
256 "  */\n"
257 " guestfs_sync (g);\n"
258 " \n"
259 msgstr ""
260
261 # type: verbatim
262 #: ../src/guestfs.pod:108
263 #, no-wrap
264 msgid ""
265 " /* Close the handle 'g'. */\n"
266 " guestfs_close (g);\n"
267 "\n"
268 msgstr ""
269
270 # type: textblock
271 #: ../src/guestfs.pod:111
272 msgid ""
273 "The code above doesn't include any error checking.  In real code you should "
274 "check return values carefully for errors.  In general all functions that "
275 "return integers return C<-1> on error, and all functions that return "
276 "pointers return C<NULL> on error.  See section L</ERROR HANDLING> below for "
277 "how to handle errors, and consult the documentation for each function call "
278 "below to see precisely how they return error indications."
279 msgstr ""
280
281 # type: =head2
282 #: ../src/guestfs.pod:119
283 msgid "DISK IMAGES"
284 msgstr ""
285
286 # type: textblock
287 #: ../src/guestfs.pod:121
288 msgid ""
289 "The image filename (C<\"guest.img\"> in the example above) could be a disk "
290 "image from a virtual machine, a L<dd(1)> copy of a physical hard disk, an "
291 "actual block device, or simply an empty file of zeroes that you have created "
292 "through L<posix_fallocate(3)>.  Libguestfs lets you do useful things to all "
293 "of these."
294 msgstr ""
295
296 # type: textblock
297 #: ../src/guestfs.pod:127
298 msgid ""
299 "You can add a disk read-only using L</guestfs_add_drive_ro>, in which case "
300 "libguestfs won't modify the file."
301 msgstr ""
302
303 # type: textblock
304 #: ../src/guestfs.pod:130
305 msgid ""
306 "Be extremely cautious if the disk image is in use, eg. if it is being used "
307 "by a virtual machine.  Adding it read-write will almost certainly cause disk "
308 "corruption, but adding it read-only is safe."
309 msgstr ""
310
311 # type: textblock
312 #: ../src/guestfs.pod:134
313 msgid ""
314 "You must add at least one disk image, and you may add multiple disk images.  "
315 "In the API, the disk images are usually referred to as C</dev/sda> (for the "
316 "first one you added), C</dev/sdb> (for the second one you added), etc."
317 msgstr ""
318
319 # type: textblock
320 #: ../src/guestfs.pod:139
321 msgid ""
322 "Once L</guestfs_launch> has been called you cannot add any more images.  You "
323 "can call L</guestfs_list_devices> to get a list of the device names, in the "
324 "order that you added them.  See also L</BLOCK DEVICE NAMING> below."
325 msgstr ""
326
327 # type: =head2
328 #: ../src/guestfs.pod:144
329 msgid "MOUNTING"
330 msgstr ""
331
332 # type: textblock
333 #: ../src/guestfs.pod:146
334 msgid ""
335 "Before you can read or write files, create directories and so on in a disk "
336 "image that contains filesystems, you have to mount those filesystems using "
337 "L</guestfs_mount>.  If you already know that a disk image contains (for "
338 "example) one partition with a filesystem on that partition, then you can "
339 "mount it directly:"
340 msgstr ""
341
342 # type: verbatim
343 #: ../src/guestfs.pod:152
344 #, no-wrap
345 msgid ""
346 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
347 "\n"
348 msgstr ""
349
350 # type: textblock
351 #: ../src/guestfs.pod:154
352 msgid ""
353 "where C</dev/sda1> means literally the first partition (C<1>) of the first "
354 "disk image that we added (C</dev/sda>).  If the disk contains Linux LVM2 "
355 "logical volumes you could refer to those instead (eg. C</dev/VG/LV>)."
356 msgstr ""
357
358 # type: textblock
359 #: ../src/guestfs.pod:158
360 msgid ""
361 "If you are given a disk image and you don't know what it contains then you "
362 "have to find out.  Libguestfs can do that too: use L</"
363 "guestfs_list_partitions> and L</guestfs_lvs> to list possible partitions and "
364 "LVs, and either try mounting each to see what is mountable, or else examine "
365 "them with L</guestfs_vfs_type> or L</guestfs_file>.  Libguestfs also has a "
366 "set of APIs for inspection of disk images (see L</INSPECTION> below).  But "
367 "you might find it easier to look at higher level programs built on top of "
368 "libguestfs, in particular L<virt-inspector(1)>."
369 msgstr ""
370
371 # type: textblock
372 #: ../src/guestfs.pod:168
373 msgid ""
374 "To mount a disk image read-only, use L</guestfs_mount_ro>.  There are "
375 "several other variations of the C<guestfs_mount_*> call."
376 msgstr ""
377
378 # type: =head2
379 #: ../src/guestfs.pod:171
380 msgid "FILESYSTEM ACCESS AND MODIFICATION"
381 msgstr ""
382
383 # type: textblock
384 #: ../src/guestfs.pod:173
385 msgid ""
386 "The majority of the libguestfs API consists of fairly low-level calls for "
387 "accessing and modifying the files, directories, symlinks etc on mounted "
388 "filesystems.  There are over a hundred such calls which you can find listed "
389 "in detail below in this man page, and we don't even pretend to cover them "
390 "all in this overview."
391 msgstr ""
392
393 # type: textblock
394 #: ../src/guestfs.pod:179
395 msgid ""
396 "Specify filenames as full paths, starting with C<\"/\"> and including the "
397 "mount point."
398 msgstr ""
399
400 # type: textblock
401 #: ../src/guestfs.pod:182
402 msgid ""
403 "For example, if you mounted a filesystem at C<\"/\"> and you want to read "
404 "the file called C<\"etc/passwd\"> then you could do:"
405 msgstr ""
406
407 # type: verbatim
408 #: ../src/guestfs.pod:185
409 #, no-wrap
410 msgid ""
411 " char *data = guestfs_cat (g, \"/etc/passwd\");\n"
412 "\n"
413 msgstr ""
414
415 # type: textblock
416 #: ../src/guestfs.pod:187
417 msgid ""
418 "This would return C<data> as a newly allocated buffer containing the full "
419 "content of that file (with some conditions: see also L</DOWNLOADING> below), "
420 "or C<NULL> if there was an error."
421 msgstr ""
422
423 # type: textblock
424 #: ../src/guestfs.pod:191
425 msgid ""
426 "As another example, to create a top-level directory on that filesystem "
427 "called C<\"var\"> you would do:"
428 msgstr ""
429
430 # type: verbatim
431 #: ../src/guestfs.pod:194
432 #, no-wrap
433 msgid ""
434 " guestfs_mkdir (g, \"/var\");\n"
435 "\n"
436 msgstr ""
437
438 # type: textblock
439 #: ../src/guestfs.pod:196
440 msgid "To create a symlink you could do:"
441 msgstr ""
442
443 # type: verbatim
444 #: ../src/guestfs.pod:198
445 #, no-wrap
446 msgid ""
447 " guestfs_ln_s (g, \"/etc/init.d/portmap\",\n"
448 "               \"/etc/rc3.d/S30portmap\");\n"
449 "\n"
450 msgstr ""
451
452 # type: textblock
453 #: ../src/guestfs.pod:201
454 msgid ""
455 "Libguestfs will reject attempts to use relative paths and there is no "
456 "concept of a current working directory."
457 msgstr ""
458
459 # type: textblock
460 #: ../src/guestfs.pod:204
461 msgid ""
462 "Libguestfs can return errors in many situations: for example if the "
463 "filesystem isn't writable, or if a file or directory that you requested "
464 "doesn't exist.  If you are using the C API (documented here)  you have to "
465 "check for those error conditions after each call.  (Other language bindings "
466 "turn these errors into exceptions)."
467 msgstr ""
468
469 # type: textblock
470 #: ../src/guestfs.pod:210
471 msgid ""
472 "File writes are affected by the per-handle umask, set by calling L</"
473 "guestfs_umask> and defaulting to 022.  See L</UMASK>."
474 msgstr ""
475
476 # type: =head2
477 #: ../src/guestfs.pod:213
478 msgid "PARTITIONING"
479 msgstr ""
480
481 # type: textblock
482 #: ../src/guestfs.pod:215
483 msgid ""
484 "Libguestfs contains API calls to read, create and modify partition tables on "
485 "disk images."
486 msgstr ""
487
488 # type: textblock
489 #: ../src/guestfs.pod:218
490 msgid ""
491 "In the common case where you want to create a single partition covering the "
492 "whole disk, you should use the L</guestfs_part_disk> call:"
493 msgstr ""
494
495 # type: verbatim
496 #: ../src/guestfs.pod:222
497 #, no-wrap
498 msgid ""
499 " const char *parttype = \"mbr\";\n"
500 " if (disk_is_larger_than_2TB)\n"
501 "   parttype = \"gpt\";\n"
502 " guestfs_part_disk (g, \"/dev/sda\", parttype);\n"
503 "\n"
504 msgstr ""
505
506 # type: textblock
507 #: ../src/guestfs.pod:227
508 msgid ""
509 "Obviously this effectively wipes anything that was on that disk image before."
510 msgstr ""
511
512 # type: =head2
513 #: ../src/guestfs.pod:230
514 msgid "LVM2"
515 msgstr ""
516
517 # type: textblock
518 #: ../src/guestfs.pod:232
519 msgid ""
520 "Libguestfs provides access to a large part of the LVM2 API, such as L</"
521 "guestfs_lvcreate> and L</guestfs_vgremove>.  It won't make much sense unless "
522 "you familiarize yourself with the concepts of physical volumes, volume "
523 "groups and logical volumes."
524 msgstr ""
525
526 # type: textblock
527 #: ../src/guestfs.pod:237
528 msgid ""
529 "This author strongly recommends reading the LVM HOWTO, online at L<http://"
530 "tldp.org/HOWTO/LVM-HOWTO/>."
531 msgstr ""
532
533 # type: =head2
534 #: ../src/guestfs.pod:240
535 msgid "DOWNLOADING"
536 msgstr ""
537
538 # type: textblock
539 #: ../src/guestfs.pod:242
540 msgid ""
541 "Use L</guestfs_cat> to download small, text only files.  This call is "
542 "limited to files which are less than 2 MB and which cannot contain any ASCII "
543 "NUL (C<\\0>) characters.  However it has a very simple to use API."
544 msgstr ""
545
546 # type: textblock
547 #: ../src/guestfs.pod:247
548 msgid ""
549 "L</guestfs_read_file> can be used to read files which contain arbitrary 8 "
550 "bit data, since it returns a (pointer, size) pair.  However it is still "
551 "limited to \"small\" files, less than 2 MB."
552 msgstr ""
553
554 # type: textblock
555 #: ../src/guestfs.pod:251
556 msgid ""
557 "L</guestfs_download> can be used to download any file, with no limits on "
558 "content or size (even files larger than 4 GB)."
559 msgstr ""
560
561 # type: textblock
562 #: ../src/guestfs.pod:254
563 msgid ""
564 "To download multiple files, see L</guestfs_tar_out> and L</guestfs_tgz_out>."
565 msgstr ""
566
567 # type: =head2
568 #: ../src/guestfs.pod:257
569 msgid "UPLOADING"
570 msgstr ""
571
572 # type: textblock
573 #: ../src/guestfs.pod:259
574 msgid ""
575 "It's often the case that you want to write a file or files to the disk image."
576 msgstr ""
577
578 # type: textblock
579 #: ../src/guestfs.pod:262
580 msgid ""
581 "To write a small file with fixed content, use L</guestfs_write>.  To create "
582 "a file of all zeroes, use L</guestfs_truncate_size> (sparse) or L</"
583 "guestfs_fallocate64> (with all disk blocks allocated).  There are a variety "
584 "of other functions for creating test files, for example L</guestfs_fill> and "
585 "L</guestfs_fill_pattern>."
586 msgstr ""
587
588 # type: textblock
589 #: ../src/guestfs.pod:268
590 msgid ""
591 "To upload a single file, use L</guestfs_upload>.  This call has no limits on "
592 "file content or size (even files larger than 4 GB)."
593 msgstr ""
594
595 # type: textblock
596 #: ../src/guestfs.pod:271
597 msgid ""
598 "To upload multiple files, see L</guestfs_tar_in> and L</guestfs_tgz_in>."
599 msgstr ""
600
601 # type: textblock
602 #: ../src/guestfs.pod:273
603 msgid ""
604 "However the fastest way to upload I<large numbers of arbitrary files> is to "
605 "turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and L<mkisofs(8)"
606 ">), then attach this using L</guestfs_add_drive_ro>.  If you add the drive "
607 "in a predictable way (eg. adding it last after all other drives) then you "
608 "can get the device name from L</guestfs_list_devices> and mount it directly "
609 "using L</guestfs_mount_ro>.  Note that squashfs images are sometimes non-"
610 "portable between kernel versions, and they don't support labels or UUIDs.  "
611 "If you want to pre-build an image or you need to mount it using a label or "
612 "UUID, use an ISO image instead."
613 msgstr ""
614
615 # type: =head2
616 #: ../src/guestfs.pod:284
617 msgid "COPYING"
618 msgstr ""
619
620 # type: textblock
621 #: ../src/guestfs.pod:286
622 msgid ""
623 "There are various different commands for copying between files and devices "
624 "and in and out of the guest filesystem.  These are summarised in the table "
625 "below."
626 msgstr ""
627
628 # type: =item
629 #: ../src/guestfs.pod:292
630 msgid "B<file> to B<file>"
631 msgstr ""
632
633 # type: textblock
634 #: ../src/guestfs.pod:294
635 msgid ""
636 "Use L</guestfs_cp> to copy a single file, or L</guestfs_cp_a> to copy "
637 "directories recursively."
638 msgstr ""
639
640 # type: =item
641 #: ../src/guestfs.pod:297
642 msgid "B<file or device> to B<file or device>"
643 msgstr ""
644
645 # type: textblock
646 #: ../src/guestfs.pod:299
647 msgid ""
648 "Use L</guestfs_dd> which efficiently uses L<dd(1)> to copy between files and "
649 "devices in the guest."
650 msgstr ""
651
652 # type: textblock
653 #: ../src/guestfs.pod:302
654 msgid "Example: duplicate the contents of an LV:"
655 msgstr ""
656
657 # type: verbatim
658 #: ../src/guestfs.pod:304
659 #, no-wrap
660 msgid ""
661 " guestfs_dd (g, \"/dev/VG/Original\", \"/dev/VG/Copy\");\n"
662 "\n"
663 msgstr ""
664
665 # type: textblock
666 #: ../src/guestfs.pod:306
667 msgid ""
668 "The destination (C</dev/VG/Copy>) must be at least as large as the source "
669 "(C</dev/VG/Original>).  To copy less than the whole source device, use L</"
670 "guestfs_copy_size>."
671 msgstr ""
672
673 # type: =item
674 #: ../src/guestfs.pod:310
675 msgid "B<file on the host> to B<file or device>"
676 msgstr ""
677
678 # type: textblock
679 #: ../src/guestfs.pod:312
680 msgid "Use L</guestfs_upload>.  See L</UPLOADING> above."
681 msgstr ""
682
683 # type: =item
684 #: ../src/guestfs.pod:314
685 msgid "B<file or device> to B<file on the host>"
686 msgstr ""
687
688 # type: textblock
689 #: ../src/guestfs.pod:316
690 msgid "Use L</guestfs_download>.  See L</DOWNLOADING> above."
691 msgstr ""
692
693 # type: =head2
694 #: ../src/guestfs.pod:320
695 msgid "LISTING FILES"
696 msgstr ""
697
698 # type: textblock
699 #: ../src/guestfs.pod:322
700 msgid ""
701 "L</guestfs_ll> is just designed for humans to read (mainly when using the "
702 "L<guestfish(1)>-equivalent command C<ll>)."
703 msgstr ""
704
705 # type: textblock
706 #: ../src/guestfs.pod:325
707 msgid ""
708 "L</guestfs_ls> is a quick way to get a list of files in a directory from "
709 "programs, as a flat list of strings."
710 msgstr ""
711
712 # type: textblock
713 #: ../src/guestfs.pod:328
714 msgid ""
715 "L</guestfs_readdir> is a programmatic way to get a list of files in a "
716 "directory, plus additional information about each one.  It is more "
717 "equivalent to using the L<readdir(3)> call on a local filesystem."
718 msgstr ""
719
720 # type: textblock
721 #: ../src/guestfs.pod:332
722 msgid ""
723 "L</guestfs_find> and L</guestfs_find0> can be used to recursively list files."
724 msgstr ""
725
726 # type: =head2
727 #: ../src/guestfs.pod:335
728 msgid "RUNNING COMMANDS"
729 msgstr ""
730
731 # type: textblock
732 #: ../src/guestfs.pod:337
733 msgid ""
734 "Although libguestfs is primarily an API for manipulating files inside guest "
735 "images, we also provide some limited facilities for running commands inside "
736 "guests."
737 msgstr ""
738
739 # type: textblock
740 #: ../src/guestfs.pod:341
741 msgid "There are many limitations to this:"
742 msgstr ""
743
744 # type: =item
745 #: ../src/guestfs.pod:345 ../src/guestfs.pod:350 ../src/guestfs.pod:355
746 #: ../src/guestfs.pod:359 ../src/guestfs.pod:364 ../src/guestfs.pod:368
747 #: ../src/guestfs.pod:373 ../src/guestfs.pod:1254 ../src/guestfs.pod:1259
748 #: ../src/guestfs.pod:1263 ../src/guestfs.pod:1365 ../src/guestfs.pod:1369
749 #: ../src/guestfs.pod:1373 ../src/guestfs.pod:1378 ../src/guestfs.pod:1386
750 #: ../src/guestfs.pod:1405 ../src/guestfs.pod:1413 ../src/guestfs.pod:1643
751 #: ../src/guestfs.pod:1649 ../src/guestfs.pod:1654 ../src/guestfs.pod:1660
752 #: ../src/guestfs.pod:1767 ../src/guestfs.pod:1771 ../src/guestfs.pod:1775
753 #: ../src/guestfs.pod:1779 ../src/guestfs-actions.pod:14
754 #: ../src/guestfs-actions.pod:21 ../src/guestfs-actions.pod:372
755 #: ../src/guestfs-actions.pod:380 ../src/guestfs-actions.pod:387
756 #: ../src/guestfs-actions.pod:394 ../src/guestfs-actions.pod:1285
757 #: ../src/guestfs-actions.pod:1289 ../src/guestfs-actions.pod:1293
758 #: ../src/guestfs-actions.pod:1297 ../src/guestfs-actions.pod:1305
759 #: ../src/guestfs-actions.pod:1309 ../src/guestfs-actions.pod:1313
760 #: ../src/guestfs-actions.pod:1323 ../src/guestfs-actions.pod:1327
761 #: ../src/guestfs-actions.pod:1331 ../src/guestfs-actions.pod:1454
762 #: ../src/guestfs-actions.pod:1458 ../src/guestfs-actions.pod:1463
763 #: ../src/guestfs-actions.pod:1468 ../src/guestfs-actions.pod:1520
764 #: ../src/guestfs-actions.pod:1524 ../src/guestfs-actions.pod:1529
765 #: ../fish/guestfish.pod:338 ../fish/guestfish.pod:342
766 #: ../fish/guestfish.pod:346 ../fish/guestfish.pod:350
767 #: ../fish/guestfish-actions.pod:15 ../fish/guestfish-actions.pod:22
768 #: ../fish/guestfish-actions.pod:306 ../fish/guestfish-actions.pod:314
769 #: ../fish/guestfish-actions.pod:321 ../fish/guestfish-actions.pod:328
770 #: ../fish/guestfish-actions.pod:1023 ../fish/guestfish-actions.pod:1027
771 #: ../fish/guestfish-actions.pod:1031 ../fish/guestfish-actions.pod:1035
772 #: ../fish/guestfish-actions.pod:1043 ../fish/guestfish-actions.pod:1047
773 #: ../fish/guestfish-actions.pod:1051 ../fish/guestfish-actions.pod:1061
774 #: ../fish/guestfish-actions.pod:1065 ../fish/guestfish-actions.pod:1069
775 #: ../fish/guestfish-actions.pod:1159 ../fish/guestfish-actions.pod:1163
776 #: ../fish/guestfish-actions.pod:1168 ../fish/guestfish-actions.pod:1173
777 #: ../fish/guestfish-actions.pod:1215 ../fish/guestfish-actions.pod:1219
778 #: ../fish/guestfish-actions.pod:1224 ../tools/virt-df.pl:144
779 #: ../tools/virt-df.pl:150 ../tools/virt-resize.pl:324
780 #: ../tools/virt-resize.pl:329 ../tools/virt-resize.pl:339
781 msgid "*"
782 msgstr ""
783
784 # type: textblock
785 #: ../src/guestfs.pod:347
786 msgid ""
787 "The kernel version that the command runs under will be different from what "
788 "it expects."
789 msgstr ""
790
791 # type: textblock
792 #: ../src/guestfs.pod:352
793 msgid ""
794 "If the command needs to communicate with daemons, then most likely they "
795 "won't be running."
796 msgstr ""
797
798 # type: textblock
799 #: ../src/guestfs.pod:357
800 msgid "The command will be running in limited memory."
801 msgstr ""
802
803 # type: textblock
804 #: ../src/guestfs.pod:361
805 msgid ""
806 "The network may not be available unless you enable it (see L</"
807 "guestfs_set_network>)."
808 msgstr ""
809
810 # type: textblock
811 #: ../src/guestfs.pod:366
812 msgid "Only supports Linux guests (not Windows, BSD, etc)."
813 msgstr ""
814
815 # type: textblock
816 #: ../src/guestfs.pod:370
817 msgid ""
818 "Architecture limitations (eg. won't work for a PPC guest on an X86 host)."
819 msgstr ""
820
821 # type: textblock
822 #: ../src/guestfs.pod:375
823 msgid ""
824 "For SELinux guests, you may need to enable SELinux and load policy first.  "
825 "See L</SELINUX> in this manpage."
826 msgstr ""
827
828 # type: textblock
829 #: ../src/guestfs.pod:380
830 msgid ""
831 "The two main API calls to run commands are L</guestfs_command> and L</"
832 "guestfs_sh> (there are also variations)."
833 msgstr ""
834
835 # type: textblock
836 #: ../src/guestfs.pod:383
837 msgid ""
838 "The difference is that L</guestfs_sh> runs commands using the shell, so any "
839 "shell globs, redirections, etc will work."
840 msgstr ""
841
842 # type: =head2
843 #: ../src/guestfs.pod:386
844 msgid "CONFIGURATION FILES"
845 msgstr ""
846
847 # type: textblock
848 #: ../src/guestfs.pod:388
849 msgid ""
850 "To read and write configuration files in Linux guest filesystems, we "
851 "strongly recommend using Augeas.  For example, Augeas understands how to "
852 "read and write, say, a Linux shadow password file or X.org configuration "
853 "file, and so avoids you having to write that code."
854 msgstr ""
855
856 # type: textblock
857 #: ../src/guestfs.pod:393
858 msgid ""
859 "The main Augeas calls are bound through the C<guestfs_aug_*> APIs.  We don't "
860 "document Augeas itself here because there is excellent documentation on the "
861 "L<http://augeas.net/> website."
862 msgstr ""
863
864 # type: textblock
865 #: ../src/guestfs.pod:397
866 msgid ""
867 "If you don't want to use Augeas (you fool!) then try calling L</"
868 "guestfs_read_lines> to get the file as a list of lines which you can iterate "
869 "over."
870 msgstr ""
871
872 # type: =head2
873 #: ../src/guestfs.pod:401
874 msgid "SELINUX"
875 msgstr ""
876
877 # type: textblock
878 #: ../src/guestfs.pod:403
879 msgid ""
880 "We support SELinux guests.  To ensure that labeling happens correctly in "
881 "SELinux guests, you need to enable SELinux and load the guest's policy:"
882 msgstr ""
883
884 # type: =item
885 #: ../src/guestfs.pod:409
886 msgid "1."
887 msgstr ""
888
889 # type: textblock
890 #: ../src/guestfs.pod:411
891 msgid "Before launching, do:"
892 msgstr ""
893
894 # type: verbatim
895 #: ../src/guestfs.pod:413
896 #, no-wrap
897 msgid ""
898 " guestfs_set_selinux (g, 1);\n"
899 "\n"
900 msgstr ""
901
902 # type: =item
903 #: ../src/guestfs.pod:415
904 msgid "2."
905 msgstr ""
906
907 # type: textblock
908 #: ../src/guestfs.pod:417
909 msgid ""
910 "After mounting the guest's filesystem(s), load the policy.  This is best "
911 "done by running the L<load_policy(8)> command in the guest itself:"
912 msgstr ""
913
914 # type: verbatim
915 #: ../src/guestfs.pod:421
916 #, no-wrap
917 msgid ""
918 " guestfs_sh (g, \"/usr/sbin/load_policy\");\n"
919 "\n"
920 msgstr ""
921
922 # type: textblock
923 #: ../src/guestfs.pod:423
924 msgid ""
925 "(Older versions of C<load_policy> require you to specify the name of the "
926 "policy file)."
927 msgstr ""
928
929 # type: =item
930 #: ../src/guestfs.pod:426
931 msgid "3."
932 msgstr ""
933
934 # type: textblock
935 #: ../src/guestfs.pod:428
936 msgid ""
937 "Optionally, set the security context for the API.  The correct security "
938 "context to use can only be known by inspecting the guest.  As an example:"
939 msgstr ""
940
941 # type: verbatim
942 #: ../src/guestfs.pod:432
943 #, no-wrap
944 msgid ""
945 " guestfs_setcon (g, \"unconfined_u:unconfined_r:unconfined_t:s0\");\n"
946 "\n"
947 msgstr ""
948
949 # type: textblock
950 #: ../src/guestfs.pod:436
951 msgid "This will work for running commands and editing existing files."
952 msgstr ""
953
954 # type: textblock
955 #: ../src/guestfs.pod:438
956 msgid ""
957 "When new files are created, you may need to label them explicitly, for "
958 "example by running the external command C<restorecon pathname>."
959 msgstr ""
960
961 # type: =head2
962 #: ../src/guestfs.pod:442
963 msgid "UMASK"
964 msgstr ""
965
966 # type: textblock
967 #: ../src/guestfs.pod:444
968 msgid ""
969 "Certain calls are affected by the current file mode creation mask (the "
970 "\"umask\").  In particular ones which create files or directories, such as "
971 "L</guestfs_touch>, L</guestfs_mknod> or L</guestfs_mkdir>.  This affects "
972 "either the default mode that the file is created with or modifies the mode "
973 "that you supply."
974 msgstr ""
975
976 # type: textblock
977 #: ../src/guestfs.pod:450
978 msgid ""
979 "The default umask is C<022>, so files are created with modes such as C<0644> "
980 "and directories with C<0755>."
981 msgstr ""
982
983 # type: textblock
984 #: ../src/guestfs.pod:453
985 msgid ""
986 "There are two ways to avoid being affected by umask.  Either set umask to 0 "
987 "(call C<guestfs_umask (g, 0)> early after launching).  Or call L</"
988 "guestfs_chmod> after creating each file or directory."
989 msgstr ""
990
991 # type: textblock
992 #: ../src/guestfs.pod:457
993 msgid "For more information about umask, see L<umask(2)>."
994 msgstr ""
995
996 # type: =head1
997 #: ../src/guestfs.pod:459 ../fish/guestfish.pod:589
998 msgid "ENCRYPTED DISKS"
999 msgstr ""
1000
1001 # type: textblock
1002 #: ../src/guestfs.pod:461
1003 msgid ""
1004 "Libguestfs allows you to access Linux guests which have been encrypted using "
1005 "whole disk encryption that conforms to the Linux Unified Key Setup (LUKS) "
1006 "standard.  This includes nearly all whole disk encryption systems used by "
1007 "modern Linux guests."
1008 msgstr ""
1009
1010 # type: textblock
1011 #: ../src/guestfs.pod:467
1012 msgid ""
1013 "Use L</guestfs_vfs_type> to identify LUKS-encrypted block devices (it "
1014 "returns the string C<crypto_LUKS>)."
1015 msgstr ""
1016
1017 # type: textblock
1018 #: ../src/guestfs.pod:470
1019 msgid ""
1020 "Then open these devices by calling L</guestfs_luks_open>.  Obviously you "
1021 "will require the passphrase!"
1022 msgstr ""
1023
1024 # type: textblock
1025 #: ../src/guestfs.pod:473
1026 msgid ""
1027 "Opening a LUKS device creates a new device mapper device called C</dev/"
1028 "mapper/mapname> (where C<mapname> is the string you supply to L</"
1029 "guestfs_luks_open>).  Reads and writes to this mapper device are decrypted "
1030 "from and encrypted to the underlying block device respectively."
1031 msgstr ""
1032
1033 # type: textblock
1034 #: ../src/guestfs.pod:479
1035 msgid ""
1036 "LVM volume groups on the device can be made visible by calling L</"
1037 "guestfs_vgscan> followed by L</guestfs_vg_activate_all>.  The logical volume"
1038 "(s) can now be mounted in the usual way."
1039 msgstr ""
1040
1041 # type: textblock
1042 #: ../src/guestfs.pod:483
1043 msgid ""
1044 "Use the reverse process to close a LUKS device.  Unmount any logical volumes "
1045 "on it, deactivate the volume groups by caling C<guestfs_vg_activate (g, 0, "
1046 "[\"/dev/VG\"])>.  Then close the mapper device by calling L</"
1047 "guestfs_luks_close> on the C</dev/mapper/mapname> device (I<not> the "
1048 "underlying encrypted block device)."
1049 msgstr ""
1050
1051 # type: =head2
1052 #: ../src/guestfs.pod:490
1053 msgid "INSPECTION"
1054 msgstr ""
1055
1056 # type: textblock
1057 #: ../src/guestfs.pod:492
1058 msgid ""
1059 "Libguestfs has APIs for inspecting an unknown disk image to find out if it "
1060 "contains operating systems.  (These APIs used to be in a separate Perl-only "
1061 "library called L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most "
1062 "frequently used part of this library has been rewritten in C and moved into "
1063 "the core code)."
1064 msgstr ""
1065
1066 # type: textblock
1067 #: ../src/guestfs.pod:498
1068 msgid ""
1069 "Add all disks belonging to the unknown virtual machine and call L</"
1070 "guestfs_launch> in the usual way."
1071 msgstr ""
1072
1073 # type: textblock
1074 #: ../src/guestfs.pod:501
1075 msgid ""
1076 "Then call L</guestfs_inspect_os>.  This function uses other libguestfs calls "
1077 "and certain heuristics, and returns a list of operating systems that were "
1078 "found.  An empty list means none were found.  A single element is the root "
1079 "filesystem of the operating system.  For dual- or multi-boot guests, "
1080 "multiple roots can be returned, each one corresponding to a separate "
1081 "operating system.  (Multi-boot virtual machines are extremely rare in the "
1082 "world of virtualization, but since this scenario can happen, we have built "
1083 "libguestfs to deal with it.)"
1084 msgstr ""
1085
1086 # type: textblock
1087 #: ../src/guestfs.pod:510
1088 msgid ""
1089 "For each root, you can then call various C<guestfs_inspect_get_*> functions "
1090 "to get additional details about that operating system.  For example, call L</"
1091 "guestfs_inspect_get_type> to return the string C<windows> or C<linux> for "
1092 "Windows and Linux-based operating systems respectively."
1093 msgstr ""
1094
1095 # type: textblock
1096 #: ../src/guestfs.pod:516
1097 msgid ""
1098 "Un*x-like and Linux-based operating systems usually consist of several "
1099 "filesystems which are mounted at boot time (for example, a separate boot "
1100 "partition mounted on C</boot>).  The inspection rules are able to detect how "
1101 "filesystems correspond to mount points.  Call "
1102 "C<guestfs_inspect_get_mountpoints> to get this mapping.  It might return a "
1103 "hash table like this example:"
1104 msgstr ""
1105
1106 # type: verbatim
1107 #: ../src/guestfs.pod:523
1108 #, no-wrap
1109 msgid ""
1110 " /boot => /dev/sda1\n"
1111 " /     => /dev/vg_guest/lv_root\n"
1112 " /usr  => /dev/vg_guest/lv_usr\n"
1113 "\n"
1114 msgstr ""
1115
1116 # type: textblock
1117 #: ../src/guestfs.pod:527
1118 msgid ""
1119 "The caller can then make calls to L</guestfs_mount_options> to mount the "
1120 "filesystems as suggested."
1121 msgstr ""
1122
1123 # type: textblock
1124 #: ../src/guestfs.pod:530
1125 msgid ""
1126 "Be careful to mount filesystems in the right order (eg. C</> before C</"
1127 "usr>).  Sorting the keys of the hash by length, shortest first, should work."
1128 msgstr ""
1129
1130 # type: textblock
1131 #: ../src/guestfs.pod:534
1132 msgid ""
1133 "Inspection currently only works for some common operating systems.  "
1134 "Contributors are welcome to send patches for other operating systems that we "
1135 "currently cannot detect."
1136 msgstr ""
1137
1138 # type: textblock
1139 #: ../src/guestfs.pod:538
1140 msgid ""
1141 "Encrypted disks must be opened before inspection.  See L</ENCRYPTED DISKS> "
1142 "for more details.  The L</guestfs_inspect_os> function just ignores any "
1143 "encrypted devices."
1144 msgstr ""
1145
1146 # type: textblock
1147 #: ../src/guestfs.pod:542
1148 msgid ""
1149 "A note on the implementation: The call L</guestfs_inspect_os> performs "
1150 "inspection and caches the results in the guest handle.  Subsequent calls to "
1151 "C<guestfs_inspect_get_*> return this cached information, but I<do not> re-"
1152 "read the disks.  If you change the content of the guest disks, you can redo "
1153 "inspection by calling L</guestfs_inspect_os> again."
1154 msgstr ""
1155
1156 # type: =head2
1157 #: ../src/guestfs.pod:549
1158 msgid "SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS"
1159 msgstr ""
1160
1161 # type: textblock
1162 #: ../src/guestfs.pod:551
1163 msgid ""
1164 "Libguestfs can mount NTFS partitions.  It does this using the L<http://www."
1165 "ntfs-3g.org/> driver."
1166 msgstr ""
1167
1168 # type: textblock
1169 #: ../src/guestfs.pod:554
1170 msgid ""
1171 "DOS and Windows still use drive letters, and the filesystems are always "
1172 "treated as case insensitive by Windows itself, and therefore you might find "
1173 "a Windows configuration file referring to a path like C<c:\\windows"
1174 "\\system32>.  When the filesystem is mounted in libguestfs, that directory "
1175 "might be referred to as C</WINDOWS/System32>."
1176 msgstr ""
1177
1178 # type: textblock
1179 #: ../src/guestfs.pod:560
1180 msgid ""
1181 "Drive letter mappings are outside the scope of libguestfs.  You have to use "
1182 "libguestfs to read the appropriate Windows Registry and configuration files, "
1183 "to determine yourself how drives are mapped (see also L<hivex(3)> and L<virt-"
1184 "inspector(1)>)."
1185 msgstr ""
1186
1187 # type: textblock
1188 #: ../src/guestfs.pod:565
1189 msgid ""
1190 "Replacing backslash characters with forward slash characters is also outside "
1191 "the scope of libguestfs, but something that you can easily do."
1192 msgstr ""
1193
1194 # type: textblock
1195 #: ../src/guestfs.pod:568
1196 msgid ""
1197 "Where we can help is in resolving the case insensitivity of paths.  For "
1198 "this, call L</guestfs_case_sensitive_path>."
1199 msgstr ""
1200
1201 # type: textblock
1202 #: ../src/guestfs.pod:571
1203 msgid ""
1204 "Libguestfs also provides some help for decoding Windows Registry \"hive\" "
1205 "files, through the library C<hivex> which is part of the libguestfs project "
1206 "although ships as a separate tarball.  You have to locate and download the "
1207 "hive file(s) yourself, and then pass them to C<hivex> functions.  See also "
1208 "the programs L<hivexml(1)>, L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-"
1209 "reg(1)> for more help on this issue."
1210 msgstr ""
1211
1212 # type: =head2
1213 #: ../src/guestfs.pod:579
1214 msgid "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES"
1215 msgstr ""
1216
1217 # type: textblock
1218 #: ../src/guestfs.pod:581
1219 msgid ""
1220 "Although we don't want to discourage you from using the C API, we will "
1221 "mention here that the same API is also available in other languages."
1222 msgstr ""
1223
1224 # type: textblock
1225 #: ../src/guestfs.pod:584
1226 msgid ""
1227 "The API is broadly identical in all supported languages.  This means that "
1228 "the C call C<guestfs_mount(g,path)> is C<$g-E<gt>mount($path)> in Perl, C<g."
1229 "mount(path)> in Python, and C<Guestfs.mount g path> in OCaml.  In other "
1230 "words, a straightforward, predictable isomorphism between each language."
1231 msgstr ""
1232
1233 # type: textblock
1234 #: ../src/guestfs.pod:590
1235 msgid ""
1236 "Error messages are automatically transformed into exceptions if the language "
1237 "supports it."
1238 msgstr ""
1239
1240 # type: textblock
1241 #: ../src/guestfs.pod:593
1242 msgid ""
1243 "We don't try to \"object orientify\" parts of the API in OO languages, "
1244 "although contributors are welcome to write higher level APIs above what we "
1245 "provide in their favourite languages if they wish."
1246 msgstr ""
1247
1248 # type: =item
1249 #: ../src/guestfs.pod:599
1250 msgid "B<C++>"
1251 msgstr ""
1252
1253 # type: textblock
1254 #: ../src/guestfs.pod:601
1255 msgid ""
1256 "You can use the I<guestfs.h> header file from C++ programs.  The C++ API is "
1257 "identical to the C API.  C++ classes and exceptions are not used."
1258 msgstr ""
1259
1260 # type: =item
1261 #: ../src/guestfs.pod:605
1262 msgid "B<C#>"
1263 msgstr ""
1264
1265 # type: textblock
1266 #: ../src/guestfs.pod:607
1267 msgid ""
1268 "The C# bindings are highly experimental.  Please read the warnings at the "
1269 "top of C<csharp/Libguestfs.cs>."
1270 msgstr ""
1271
1272 # type: =item
1273 #: ../src/guestfs.pod:610
1274 msgid "B<Haskell>"
1275 msgstr ""
1276
1277 # type: textblock
1278 #: ../src/guestfs.pod:612
1279 msgid ""
1280 "This is the only language binding that is working but incomplete.  Only "
1281 "calls which return simple integers have been bound in Haskell, and we are "
1282 "looking for help to complete this binding."
1283 msgstr ""
1284
1285 # type: =item
1286 #: ../src/guestfs.pod:616
1287 msgid "B<Java>"
1288 msgstr ""
1289
1290 # type: textblock
1291 #: ../src/guestfs.pod:618
1292 msgid ""
1293 "Full documentation is contained in the Javadoc which is distributed with "
1294 "libguestfs."
1295 msgstr ""
1296
1297 # type: =item
1298 #: ../src/guestfs.pod:621
1299 msgid "B<OCaml>"
1300 msgstr ""
1301
1302 # type: textblock
1303 #: ../src/guestfs.pod:623
1304 msgid "For documentation see the file C<guestfs.mli>."
1305 msgstr ""
1306
1307 # type: =item
1308 #: ../src/guestfs.pod:625
1309 msgid "B<Perl>"
1310 msgstr ""
1311
1312 # type: textblock
1313 #: ../src/guestfs.pod:627
1314 msgid "For documentation see L<Sys::Guestfs(3)>."
1315 msgstr ""
1316
1317 # type: =item
1318 #: ../src/guestfs.pod:629
1319 msgid "B<PHP>"
1320 msgstr ""
1321
1322 # type: textblock
1323 #: ../src/guestfs.pod:631
1324 msgid ""
1325 "For documentation see C<README-PHP> supplied with libguestfs sources or in "
1326 "the php-libguestfs package for your distribution."
1327 msgstr ""
1328
1329 # type: textblock
1330 #: ../src/guestfs.pod:634
1331 msgid "The PHP binding only works correctly on 64 bit machines."
1332 msgstr ""
1333
1334 # type: =item
1335 #: ../src/guestfs.pod:636
1336 msgid "B<Python>"
1337 msgstr ""
1338
1339 # type: textblock
1340 #: ../src/guestfs.pod:638
1341 msgid "For documentation do:"
1342 msgstr ""
1343
1344 # type: verbatim
1345 #: ../src/guestfs.pod:640
1346 #, no-wrap
1347 msgid ""
1348 " $ python\n"
1349 " >>> import guestfs\n"
1350 " >>> help (guestfs)\n"
1351 "\n"
1352 msgstr ""
1353
1354 # type: =item
1355 #: ../src/guestfs.pod:644
1356 msgid "B<Ruby>"
1357 msgstr ""
1358
1359 # type: textblock
1360 #: ../src/guestfs.pod:646
1361 msgid ""
1362 "Use the Guestfs module.  There is no Ruby-specific documentation, but you "
1363 "can find examples written in Ruby in the libguestfs source."
1364 msgstr ""
1365
1366 # type: =item
1367 #: ../src/guestfs.pod:649
1368 msgid "B<shell scripts>"
1369 msgstr ""
1370
1371 # type: textblock
1372 #: ../src/guestfs.pod:651
1373 msgid "For documentation see L<guestfish(1)>."
1374 msgstr ""
1375
1376 # type: =head2
1377 #: ../src/guestfs.pod:655
1378 msgid "LIBGUESTFS GOTCHAS"
1379 msgstr ""
1380
1381 # type: textblock
1382 #: ../src/guestfs.pod:657
1383 msgid ""
1384 "L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: \"A feature of a "
1385 "system [...] that works in the way it is documented but is counterintuitive "
1386 "and almost invites mistakes.\""
1387 msgstr ""
1388
1389 # type: textblock
1390 #: ../src/guestfs.pod:661
1391 msgid ""
1392 "Since we developed libguestfs and the associated tools, there are several "
1393 "things we would have designed differently, but are now stuck with for "
1394 "backwards compatibility or other reasons.  If there is ever a libguestfs 2.0 "
1395 "release, you can expect these to change.  Beware of them."
1396 msgstr ""
1397
1398 # type: =item
1399 #: ../src/guestfs.pod:669
1400 msgid "Autosync / forgetting to sync."
1401 msgstr ""
1402
1403 # type: textblock
1404 #: ../src/guestfs.pod:671
1405 msgid ""
1406 "When modifying a filesystem from C or another language, you B<must> unmount "
1407 "all filesystems and call L</guestfs_sync> explicitly before you close the "
1408 "libguestfs handle.  You can also call:"
1409 msgstr ""
1410
1411 # type: verbatim
1412 #: ../src/guestfs.pod:675
1413 #, no-wrap
1414 msgid ""
1415 " guestfs_set_autosync (g, 1);\n"
1416 "\n"
1417 msgstr ""
1418
1419 # type: textblock
1420 #: ../src/guestfs.pod:677
1421 msgid ""
1422 "to have the unmount/sync done automatically for you when the handle 'g' is "
1423 "closed.  (This feature is called \"autosync\", L</guestfs_set_autosync> q.v.)"
1424 msgstr ""
1425
1426 # type: textblock
1427 #: ../src/guestfs.pod:681
1428 msgid ""
1429 "If you forget to do this, then it is entirely possible that your changes "
1430 "won't be written out, or will be partially written, or (very rarely) that "
1431 "you'll get disk corruption."
1432 msgstr ""
1433
1434 # type: textblock
1435 #: ../src/guestfs.pod:685
1436 msgid ""
1437 "Note that in L<guestfish(3)> autosync is the default.  So quick and dirty "
1438 "guestfish scripts that forget to sync will work just fine, which can make "
1439 "this very puzzling if you are trying to debug a problem."
1440 msgstr ""
1441
1442 # type: =item
1443 #: ../src/guestfs.pod:689
1444 msgid "Mount option C<-o sync> should not be the default."
1445 msgstr ""
1446
1447 # type: textblock
1448 #: ../src/guestfs.pod:691
1449 msgid ""
1450 "If you use L</guestfs_mount>, then C<-o sync,noatime> are added implicitly.  "
1451 "However C<-o sync> does not add any reliability benefit, but does have a "
1452 "very large performance impact."
1453 msgstr ""
1454
1455 # type: textblock
1456 #: ../src/guestfs.pod:695
1457 msgid ""
1458 "The work around is to use L</guestfs_mount_options> and set the mount "
1459 "options that you actually want to use."
1460 msgstr ""
1461
1462 # type: =item
1463 #: ../src/guestfs.pod:698
1464 msgid "Read-only should be the default."
1465 msgstr ""
1466
1467 # type: textblock
1468 #: ../src/guestfs.pod:700
1469 msgid ""
1470 "In L<guestfish(3)>, I<--ro> should be the default, and you should have to "
1471 "specify I<--rw> if you want to make changes to the image."
1472 msgstr ""
1473
1474 # type: textblock
1475 #: ../src/guestfs.pod:703
1476 msgid "This would reduce the potential to corrupt live VM images."
1477 msgstr ""
1478
1479 # type: textblock
1480 #: ../src/guestfs.pod:705
1481 msgid ""
1482 "Note that many filesystems change the disk when you just mount and unmount, "
1483 "even if you didn't perform any writes.  You need to use L</"
1484 "guestfs_add_drive_ro> to guarantee that the disk is not changed."
1485 msgstr ""
1486
1487 # type: =item
1488 #: ../src/guestfs.pod:709
1489 msgid "guestfish command line is hard to use."
1490 msgstr ""
1491
1492 # type: textblock
1493 #: ../src/guestfs.pod:711
1494 msgid ""
1495 "C<guestfish disk.img> doesn't do what people expect (open C<disk.img> for "
1496 "examination).  It tries to run a guestfish command C<disk.img> which doesn't "
1497 "exist, so it fails.  In earlier versions of guestfish the error message was "
1498 "also unintuitive, but we have corrected this since.  Like the Bourne shell, "
1499 "we should have used C<guestfish -c command> to run commands."
1500 msgstr ""
1501
1502 # type: =item
1503 #: ../src/guestfs.pod:718
1504 msgid "guestfish megabyte modifiers don't work right on all commands"
1505 msgstr ""
1506
1507 # type: textblock
1508 #: ../src/guestfs.pod:720
1509 msgid ""
1510 "In recent guestfish you can use C<1M> to mean 1 megabyte (and similarly for "
1511 "other modifiers).  What guestfish actually does is to multiply the number "
1512 "part by the modifier part and pass the result to the C API.  However this "
1513 "doesn't work for a few APIs which aren't expecting bytes, but are already "
1514 "expecting some other unit (eg. megabytes)."
1515 msgstr ""
1516
1517 # type: textblock
1518 #: ../src/guestfs.pod:727
1519 msgid "The most common is L</guestfs_lvcreate>.  The guestfish command:"
1520 msgstr ""
1521
1522 # type: verbatim
1523 #: ../src/guestfs.pod:729
1524 #, no-wrap
1525 msgid ""
1526 " lvcreate LV VG 100M\n"
1527 "\n"
1528 msgstr ""
1529
1530 # type: textblock
1531 #: ../src/guestfs.pod:731
1532 msgid ""
1533 "does not do what you might expect.  Instead because L</guestfs_lvcreate> is "
1534 "already expecting megabytes, this tries to create a 100 I<terabyte> (100 "
1535 "megabytes * megabytes) logical volume.  The error message you get from this "
1536 "is also a little obscure."
1537 msgstr ""
1538
1539 # type: textblock
1540 #: ../src/guestfs.pod:736
1541 msgid ""
1542 "This could be fixed in the generator by specially marking parameters and "
1543 "return values which take bytes or other units."
1544 msgstr ""
1545
1546 # type: =item
1547 #: ../src/guestfs.pod:739
1548 msgid "Library should return errno with error messages."
1549 msgstr ""
1550
1551 # type: textblock
1552 #: ../src/guestfs.pod:741
1553 msgid ""
1554 "It would be a nice-to-have to be able to get the original value of 'errno' "
1555 "from inside the appliance along error paths (where set).  Currently "
1556 "L<guestmount(1)> goes through hoops to try to reverse the error message "
1557 "string into an errno, see the function error() in fuse/guestmount.c."
1558 msgstr ""
1559
1560 # type: textblock
1561 #: ../src/guestfs.pod:747
1562 msgid ""
1563 "In libguestfs 1.5.4, the protocol was changed so that the Linux errno is "
1564 "sent back from the daemon."
1565 msgstr ""
1566
1567 # type: =item
1568 #: ../src/guestfs.pod:750
1569 msgid "Ambiguity between devices and paths"
1570 msgstr ""
1571
1572 # type: textblock
1573 #: ../src/guestfs.pod:752
1574 msgid ""
1575 "There is a subtle ambiguity in the API between a device name (eg. C</dev/"
1576 "sdb2>) and a similar pathname.  A file might just happen to be called "
1577 "C<sdb2> in the directory C</dev> (consider some non-Unix VM image)."
1578 msgstr ""
1579
1580 # type: textblock
1581 #: ../src/guestfs.pod:757
1582 msgid ""
1583 "In the current API we usually resolve this ambiguity by having two separate "
1584 "calls, for example L</guestfs_checksum> and L</guestfs_checksum_device>.  "
1585 "Some API calls are ambiguous and (incorrectly) resolve the problem by "
1586 "detecting if the path supplied begins with C</dev/>."
1587 msgstr ""
1588
1589 # type: textblock
1590 #: ../src/guestfs.pod:763
1591 msgid ""
1592 "To avoid both the ambiguity and the need to duplicate some calls, we could "
1593 "make paths/devices into structured names.  One way to do this would be to "
1594 "use a notation like grub (C<hd(0,0)>), although nobody really likes this "
1595 "aspect of grub.  Another way would be to use a structured type, equivalent "
1596 "to this OCaml type:"
1597 msgstr ""
1598
1599 # type: verbatim
1600 #: ../src/guestfs.pod:769
1601 #, no-wrap
1602 msgid ""
1603 " type path = Path of string | Device of int | Partition of int * int\n"
1604 "\n"
1605 msgstr ""
1606
1607 # type: textblock
1608 #: ../src/guestfs.pod:771
1609 msgid "which would allow you to pass arguments like:"
1610 msgstr ""
1611
1612 # type: verbatim
1613 #: ../src/guestfs.pod:773
1614 #, no-wrap
1615 msgid ""
1616 " Path \"/foo/bar\"\n"
1617 " Device 1            (* /dev/sdb, or perhaps /dev/sda *)\n"
1618 " Partition (1, 2)    (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)\n"
1619 " Path \"/dev/sdb2\"    (* not a device *)\n"
1620 "\n"
1621 msgstr ""
1622
1623 # type: textblock
1624 #: ../src/guestfs.pod:778
1625 msgid ""
1626 "As you can see there are still problems to resolve even with this "
1627 "representation.  Also consider how it might work in guestfish."
1628 msgstr ""
1629
1630 # type: =head2
1631 #: ../src/guestfs.pod:783
1632 msgid "PROTOCOL LIMITS"
1633 msgstr ""
1634
1635 # type: textblock
1636 #: ../src/guestfs.pod:785
1637 msgid ""
1638 "Internally libguestfs uses a message-based protocol to pass API calls and "
1639 "their responses to and from a small \"appliance\" (see L</INTERNALS> for "
1640 "plenty more detail about this).  The maximum message size used by the "
1641 "protocol is slightly less than 4 MB.  For some API calls you may need to be "
1642 "aware of this limit.  The API calls which may be affected are individually "
1643 "documented, with a link back to this section of the documentation."
1644 msgstr ""
1645
1646 # type: textblock
1647 #: ../src/guestfs.pod:793
1648 msgid ""
1649 "A simple call such as L</guestfs_cat> returns its result (the file data) in "
1650 "a simple string.  Because this string is at some point internally encoded as "
1651 "a message, the maximum size that it can return is slightly under 4 MB.  If "
1652 "the requested file is larger than this then you will get an error."
1653 msgstr ""
1654
1655 # type: textblock
1656 #: ../src/guestfs.pod:799
1657 msgid ""
1658 "In order to transfer large files into and out of the guest filesystem, you "
1659 "need to use particular calls that support this.  The sections L</UPLOADING> "
1660 "and L</DOWNLOADING> document how to do this."
1661 msgstr ""
1662
1663 # type: textblock
1664 #: ../src/guestfs.pod:803
1665 msgid ""
1666 "You might also consider mounting the disk image using our FUSE filesystem "
1667 "support (L<guestmount(1)>)."
1668 msgstr ""
1669
1670 # type: =head2
1671 #: ../src/guestfs.pod:806
1672 msgid "KEYS AND PASSPHRASES"
1673 msgstr ""
1674
1675 # type: textblock
1676 #: ../src/guestfs.pod:808
1677 msgid ""
1678 "Certain libguestfs calls take a parameter that contains sensitive key "
1679 "material, passed in as a C string."
1680 msgstr ""
1681
1682 # type: textblock
1683 #: ../src/guestfs.pod:811
1684 msgid ""
1685 "In the future we would hope to change the libguestfs implementation so that "
1686 "keys are L<mlock(2)>-ed into physical RAM, and thus can never end up in "
1687 "swap.  However this is I<not> done at the moment, because of the complexity "
1688 "of such an implementation."
1689 msgstr ""
1690
1691 # type: textblock
1692 #: ../src/guestfs.pod:816
1693 msgid ""
1694 "Therefore you should be aware that any key parameter you pass to libguestfs "
1695 "might end up being written out to the swap partition.  If this is a concern, "
1696 "scrub the swap partition or don't use libguestfs on encrypted devices."
1697 msgstr ""
1698
1699 # type: =head1
1700 #: ../src/guestfs.pod:821
1701 msgid "CONNECTION MANAGEMENT"
1702 msgstr ""
1703
1704 # type: =head2
1705 #: ../src/guestfs.pod:823
1706 msgid "guestfs_h *"
1707 msgstr ""
1708
1709 # type: textblock
1710 #: ../src/guestfs.pod:825
1711 msgid ""
1712 "C<guestfs_h> is the opaque type representing a connection handle.  Create a "
1713 "handle by calling L</guestfs_create>.  Call L</guestfs_close> to free the "
1714 "handle and release all resources used."
1715 msgstr ""
1716
1717 # type: textblock
1718 #: ../src/guestfs.pod:829
1719 msgid ""
1720 "For information on using multiple handles and threads, see the section L</"
1721 "MULTIPLE HANDLES AND MULTIPLE THREADS> below."
1722 msgstr ""
1723
1724 # type: =head2
1725 #: ../src/guestfs.pod:832
1726 msgid "guestfs_create"
1727 msgstr ""
1728
1729 # type: verbatim
1730 #: ../src/guestfs.pod:834
1731 #, no-wrap
1732 msgid ""
1733 " guestfs_h *guestfs_create (void);\n"
1734 "\n"
1735 msgstr ""
1736
1737 # type: textblock
1738 #: ../src/guestfs.pod:836
1739 msgid "Create a connection handle."
1740 msgstr ""
1741
1742 # type: textblock
1743 #: ../src/guestfs.pod:838
1744 msgid "You have to call L</guestfs_add_drive> on the handle at least once."
1745 msgstr ""
1746
1747 # type: textblock
1748 #: ../src/guestfs.pod:840
1749 msgid ""
1750 "This function returns a non-NULL pointer to a handle on success or NULL on "
1751 "error."
1752 msgstr ""
1753
1754 # type: textblock
1755 #: ../src/guestfs.pod:843
1756 msgid "After configuring the handle, you have to call L</guestfs_launch>."
1757 msgstr ""
1758
1759 # type: textblock
1760 #: ../src/guestfs.pod:845
1761 msgid ""
1762 "You may also want to configure error handling for the handle.  See L</ERROR "
1763 "HANDLING> section below."
1764 msgstr ""
1765
1766 # type: =head2
1767 #: ../src/guestfs.pod:848
1768 msgid "guestfs_close"
1769 msgstr ""
1770
1771 # type: verbatim
1772 #: ../src/guestfs.pod:850
1773 #, no-wrap
1774 msgid ""
1775 " void guestfs_close (guestfs_h *g);\n"
1776 "\n"
1777 msgstr ""
1778
1779 # type: textblock
1780 #: ../src/guestfs.pod:852
1781 msgid "This closes the connection handle and frees up all resources used."
1782 msgstr ""
1783
1784 # type: =head1
1785 #: ../src/guestfs.pod:854
1786 msgid "ERROR HANDLING"
1787 msgstr ""
1788
1789 # type: textblock
1790 #: ../src/guestfs.pod:856
1791 msgid ""
1792 "The convention in all functions that return C<int> is that they return C<-1> "
1793 "to indicate an error.  You can get additional information on errors by "
1794 "calling L</guestfs_last_error> and/or by setting up an error handler with L</"
1795 "guestfs_set_error_handler>."
1796 msgstr ""
1797
1798 # type: textblock
1799 #: ../src/guestfs.pod:861
1800 msgid "The default error handler prints the information string to C<stderr>."
1801 msgstr ""
1802
1803 # type: textblock
1804 #: ../src/guestfs.pod:863
1805 msgid ""
1806 "Out of memory errors are handled differently.  The default action is to call "
1807 "L<abort(3)>.  If this is undesirable, then you can set a handler using L</"
1808 "guestfs_set_out_of_memory_handler>."
1809 msgstr ""
1810
1811 # type: =head2
1812 #: ../src/guestfs.pod:867
1813 msgid "guestfs_last_error"
1814 msgstr ""
1815
1816 # type: verbatim
1817 #: ../src/guestfs.pod:869
1818 #, no-wrap
1819 msgid ""
1820 " const char *guestfs_last_error (guestfs_h *g);\n"
1821 "\n"
1822 msgstr ""
1823
1824 # type: textblock
1825 #: ../src/guestfs.pod:871
1826 msgid ""
1827 "This returns the last error message that happened on C<g>.  If there has not "
1828 "been an error since the handle was created, then this returns C<NULL>."
1829 msgstr ""
1830
1831 # type: textblock
1832 #: ../src/guestfs.pod:875
1833 msgid ""
1834 "The lifetime of the returned string is until the next error occurs, or L</"
1835 "guestfs_close> is called."
1836 msgstr ""
1837
1838 # type: textblock
1839 #: ../src/guestfs.pod:878
1840 msgid ""
1841 "The error string is not localized (ie. is always in English), because this "
1842 "makes searching for error messages in search engines give the largest number "
1843 "of results."
1844 msgstr ""
1845
1846 # type: =head2
1847 #: ../src/guestfs.pod:882
1848 msgid "guestfs_set_error_handler"
1849 msgstr ""
1850
1851 # type: verbatim
1852 #: ../src/guestfs.pod:884
1853 #, no-wrap
1854 msgid ""
1855 " typedef void (*guestfs_error_handler_cb) (guestfs_h *g,\n"
1856 "                                           void *opaque,\n"
1857 "                                           const char *msg);\n"
1858 " void guestfs_set_error_handler (guestfs_h *g,\n"
1859 "                                 guestfs_error_handler_cb cb,\n"
1860 "                                 void *opaque);\n"
1861 "\n"
1862 msgstr ""
1863
1864 # type: textblock
1865 #: ../src/guestfs.pod:891
1866 msgid ""
1867 "The callback C<cb> will be called if there is an error.  The parameters "
1868 "passed to the callback are an opaque data pointer and the error message "
1869 "string."
1870 msgstr ""
1871
1872 # type: textblock
1873 #: ../src/guestfs.pod:895
1874 msgid ""
1875 "Note that the message string C<msg> is freed as soon as the callback "
1876 "function returns, so if you want to stash it somewhere you must make your "
1877 "own copy."
1878 msgstr ""
1879
1880 # type: textblock
1881 #: ../src/guestfs.pod:899
1882 msgid "The default handler prints messages on C<stderr>."
1883 msgstr ""
1884
1885 # type: textblock
1886 #: ../src/guestfs.pod:901
1887 msgid "If you set C<cb> to C<NULL> then I<no> handler is called."
1888 msgstr ""
1889
1890 # type: =head2
1891 #: ../src/guestfs.pod:903
1892 msgid "guestfs_get_error_handler"
1893 msgstr ""
1894
1895 # type: verbatim
1896 #: ../src/guestfs.pod:905
1897 #, no-wrap
1898 msgid ""
1899 " guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,\n"
1900 "                                                     void **opaque_rtn);\n"
1901 "\n"
1902 msgstr ""
1903
1904 # type: textblock
1905 #: ../src/guestfs.pod:908
1906 msgid "Returns the current error handler callback."
1907 msgstr ""
1908
1909 # type: =head2
1910 #: ../src/guestfs.pod:910
1911 msgid "guestfs_set_out_of_memory_handler"
1912 msgstr ""
1913
1914 # type: verbatim
1915 #: ../src/guestfs.pod:912
1916 #, no-wrap
1917 msgid ""
1918 " typedef void (*guestfs_abort_cb) (void);\n"
1919 " int guestfs_set_out_of_memory_handler (guestfs_h *g,\n"
1920 "                                        guestfs_abort_cb);\n"
1921 "\n"
1922 msgstr ""
1923
1924 # type: textblock
1925 #: ../src/guestfs.pod:916
1926 msgid ""
1927 "The callback C<cb> will be called if there is an out of memory situation.  "
1928 "I<Note this callback must not return>."
1929 msgstr ""
1930
1931 # type: textblock
1932 #: ../src/guestfs.pod:919
1933 msgid "The default is to call L<abort(3)>."
1934 msgstr ""
1935
1936 # type: textblock
1937 #: ../src/guestfs.pod:921
1938 msgid ""
1939 "You cannot set C<cb> to C<NULL>.  You can't ignore out of memory situations."
1940 msgstr ""
1941
1942 # type: =head2
1943 #: ../src/guestfs.pod:924
1944 msgid "guestfs_get_out_of_memory_handler"
1945 msgstr ""
1946
1947 # type: verbatim
1948 #: ../src/guestfs.pod:926
1949 #, no-wrap
1950 msgid ""
1951 " guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);\n"
1952 "\n"
1953 msgstr ""
1954
1955 # type: textblock
1956 #: ../src/guestfs.pod:928
1957 msgid "This returns the current out of memory handler."
1958 msgstr ""
1959
1960 # type: =head1
1961 #: ../src/guestfs.pod:930
1962 msgid "PATH"
1963 msgstr ""
1964
1965 # type: textblock
1966 #: ../src/guestfs.pod:932
1967 msgid ""
1968 "Libguestfs needs a kernel and initrd.img, which it finds by looking along an "
1969 "internal path."
1970 msgstr ""
1971
1972 # type: textblock
1973 #: ../src/guestfs.pod:935
1974 msgid ""
1975 "By default it looks for these in the directory C<$libdir/guestfs> (eg. C</"
1976 "usr/local/lib/guestfs> or C</usr/lib64/guestfs>)."
1977 msgstr ""
1978
1979 # type: textblock
1980 #: ../src/guestfs.pod:938
1981 msgid ""
1982 "Use L</guestfs_set_path> or set the environment variable L</LIBGUESTFS_PATH> "
1983 "to change the directories that libguestfs will search in.  The value is a "
1984 "colon-separated list of paths.  The current directory is I<not> searched "
1985 "unless the path contains an empty element or C<.>.  For example "
1986 "C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would search the current directory and "
1987 "then C</usr/lib/guestfs>."
1988 msgstr ""
1989
1990 # type: =head1
1991 #: ../src/guestfs.pod:945
1992 msgid "HIGH-LEVEL API ACTIONS"
1993 msgstr ""
1994
1995 # type: =head2
1996 #: ../src/guestfs.pod:947
1997 msgid "ABI GUARANTEE"
1998 msgstr ""
1999
2000 # type: textblock
2001 #: ../src/guestfs.pod:949
2002 msgid ""
2003 "We guarantee the libguestfs ABI (binary interface), for public, high-level "
2004 "actions as outlined in this section.  Although we will deprecate some "
2005 "actions, for example if they get replaced by newer calls, we will keep the "
2006 "old actions forever.  This allows you the developer to program in confidence "
2007 "against the libguestfs API."
2008 msgstr ""
2009
2010 # type: textblock
2011 #: ../src/guestfs.pod:955 ../fish/guestfish.pod:819
2012 msgid "@ACTIONS@"
2013 msgstr ""
2014
2015 # type: =head1
2016 #: ../src/guestfs.pod:957
2017 msgid "STRUCTURES"
2018 msgstr ""
2019
2020 # type: textblock
2021 #: ../src/guestfs.pod:959
2022 msgid "@STRUCTS@"
2023 msgstr ""
2024
2025 # type: =head1
2026 #: ../src/guestfs.pod:961
2027 msgid "AVAILABILITY"
2028 msgstr ""
2029
2030 # type: =head2
2031 #: ../src/guestfs.pod:963
2032 msgid "GROUPS OF FUNCTIONALITY IN THE APPLIANCE"
2033 msgstr ""
2034
2035 # type: textblock
2036 #: ../src/guestfs.pod:965
2037 msgid ""
2038 "Using L</guestfs_available> you can test availability of the following "
2039 "groups of functions.  This test queries the appliance to see if the "
2040 "appliance you are currently using supports the functionality."
2041 msgstr ""
2042
2043 # type: textblock
2044 #: ../src/guestfs.pod:970
2045 msgid "@AVAILABILITY@"
2046 msgstr ""
2047
2048 # type: =head2
2049 #: ../src/guestfs.pod:972
2050 msgid "GUESTFISH supported COMMAND"
2051 msgstr ""
2052
2053 # type: textblock
2054 #: ../src/guestfs.pod:974
2055 msgid ""
2056 "In L<guestfish(3)> there is a handy interactive command C<supported> which "
2057 "prints out the available groups and whether they are supported by this build "
2058 "of libguestfs.  Note however that you have to do C<run> first."
2059 msgstr ""
2060
2061 # type: =head2
2062 #: ../src/guestfs.pod:979
2063 msgid "SINGLE CALLS AT COMPILE TIME"
2064 msgstr ""
2065
2066 # type: textblock
2067 #: ../src/guestfs.pod:981
2068 msgid ""
2069 "Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols for each C API "
2070 "function, such as:"
2071 msgstr ""
2072
2073 # type: verbatim
2074 #: ../src/guestfs.pod:984
2075 #, no-wrap
2076 msgid ""
2077 " #define LIBGUESTFS_HAVE_DD 1\n"
2078 "\n"
2079 msgstr ""
2080
2081 # type: textblock
2082 #: ../src/guestfs.pod:986
2083 msgid "if L</guestfs_dd> is available."
2084 msgstr ""
2085
2086 # type: textblock
2087 #: ../src/guestfs.pod:988
2088 msgid ""
2089 "Before version 1.5.8, if you needed to test whether a single libguestfs "
2090 "function is available at compile time, we recommended using build tools such "
2091 "as autoconf or cmake.  For example in autotools you could use:"
2092 msgstr ""
2093
2094 # type: verbatim
2095 #: ../src/guestfs.pod:993
2096 #, no-wrap
2097 msgid ""
2098 " AC_CHECK_LIB([guestfs],[guestfs_create])\n"
2099 " AC_CHECK_FUNCS([guestfs_dd])\n"
2100 "\n"
2101 msgstr ""
2102
2103 # type: textblock
2104 #: ../src/guestfs.pod:996
2105 msgid ""
2106 "which would result in C<HAVE_GUESTFS_DD> being either defined or not defined "
2107 "in your program."
2108 msgstr ""
2109
2110 # type: =head2
2111 #: ../src/guestfs.pod:999
2112 msgid "SINGLE CALLS AT RUN TIME"
2113 msgstr ""
2114
2115 # type: textblock
2116 #: ../src/guestfs.pod:1001
2117 msgid ""
2118 "Testing at compile time doesn't guarantee that a function really exists in "
2119 "the library.  The reason is that you might be dynamically linked against a "
2120 "previous I<libguestfs.so> (dynamic library)  which doesn't have the call.  "
2121 "This situation unfortunately results in a segmentation fault, which is a "
2122 "shortcoming of the C dynamic linking system itself."
2123 msgstr ""
2124
2125 # type: textblock
2126 #: ../src/guestfs.pod:1008
2127 msgid ""
2128 "You can use L<dlopen(3)> to test if a function is available at run time, as "
2129 "in this example program (note that you still need the compile time check as "
2130 "well):"
2131 msgstr ""
2132
2133 # type: verbatim
2134 #: ../src/guestfs.pod:1012
2135 #, no-wrap
2136 msgid ""
2137 " #include <stdio.h>\n"
2138 " #include <stdlib.h>\n"
2139 " #include <unistd.h>\n"
2140 " #include <dlfcn.h>\n"
2141 " #include <guestfs.h>\n"
2142 " \n"
2143 msgstr ""
2144
2145 # type: verbatim
2146 #: ../src/guestfs.pod:1018
2147 #, no-wrap
2148 msgid ""
2149 " main ()\n"
2150 " {\n"
2151 " #ifdef LIBGUESTFS_HAVE_DD\n"
2152 "   void *dl;\n"
2153 "   int has_function;\n"
2154 " \n"
2155 msgstr ""
2156
2157 # type: verbatim
2158 #: ../src/guestfs.pod:1024
2159 #, no-wrap
2160 msgid ""
2161 "   /* Test if the function guestfs_dd is really available. */\n"
2162 "   dl = dlopen (NULL, RTLD_LAZY);\n"
2163 "   if (!dl) {\n"
2164 "     fprintf (stderr, \"dlopen: %s\\n\", dlerror ());\n"
2165 "     exit (EXIT_FAILURE);\n"
2166 "   }\n"
2167 "   has_function = dlsym (dl, \"guestfs_dd\") != NULL;\n"
2168 "   dlclose (dl);\n"
2169 " \n"
2170 msgstr ""
2171
2172 # type: verbatim
2173 #: ../src/guestfs.pod:1033
2174 #, no-wrap
2175 msgid ""
2176 "   if (!has_function)\n"
2177 "     printf (\"this libguestfs.so does NOT have guestfs_dd function\\n\");\n"
2178 "   else {\n"
2179 "     printf (\"this libguestfs.so has guestfs_dd function\\n\");\n"
2180 "     /* Now it's safe to call\n"
2181 "     guestfs_dd (g, \"foo\", \"bar\");\n"
2182 "     */\n"
2183 "   }\n"
2184 " #else\n"
2185 "   printf (\"guestfs_dd function was not found at compile time\\n\");\n"
2186 " #endif\n"
2187 "  }\n"
2188 "\n"
2189 msgstr ""
2190
2191 # type: textblock
2192 #: ../src/guestfs.pod:1046
2193 msgid ""
2194 "You may think the above is an awful lot of hassle, and it is.  There are "
2195 "other ways outside of the C linking system to ensure that this kind of "
2196 "incompatibility never arises, such as using package versioning:"
2197 msgstr ""
2198
2199 # type: verbatim
2200 #: ../src/guestfs.pod:1051
2201 #, no-wrap
2202 msgid ""
2203 " Requires: libguestfs >= 1.0.80\n"
2204 "\n"
2205 msgstr ""
2206
2207 # type: =end
2208 #: ../src/guestfs.pod:1053 ../src/guestfs.pod:1058
2209 msgid "html"
2210 msgstr ""
2211
2212 # type: textblock
2213 #: ../src/guestfs.pod:1055
2214 msgid ""
2215 "<!-- old anchor for the next section --> <a name="
2216 "\"state_machine_and_low_level_event_api\"/>"
2217 msgstr ""
2218
2219 # type: =head1
2220 #: ../src/guestfs.pod:1060
2221 msgid "ARCHITECTURE"
2222 msgstr ""
2223
2224 # type: textblock
2225 #: ../src/guestfs.pod:1062
2226 msgid ""
2227 "Internally, libguestfs is implemented by running an appliance (a special "
2228 "type of small virtual machine) using L<qemu(1)>.  Qemu runs as a child "
2229 "process of the main program."
2230 msgstr ""
2231
2232 # type: verbatim
2233 #: ../src/guestfs.pod:1066
2234 #, no-wrap
2235 msgid ""
2236 "  ___________________\n"
2237 " /                   \\\n"
2238 " | main program      |\n"
2239 " |                   |\n"
2240 " |                   |           child process / appliance\n"
2241 " |                   |           __________________________\n"
2242 " |                   |          / qemu                     \\\n"
2243 " +-------------------+   RPC    |      +-----------------+ |\n"
2244 " | libguestfs     <--------------------> guestfsd        | |\n"
2245 " |                   |          |      +-----------------+ |\n"
2246 " \\___________________/          |      | Linux kernel    | |\n"
2247 "                                |      +--^--------------+ |\n"
2248 "                                \\_________|________________/\n"
2249 "                                          |\n"
2250 "                                   _______v______\n"
2251 "                                  /              \\\n"
2252 "                                  | Device or    |\n"
2253 "                                  | disk image   |\n"
2254 "                                  \\______________/\n"
2255 "\n"
2256 msgstr ""
2257
2258 # type: textblock
2259 #: ../src/guestfs.pod:1086
2260 msgid ""
2261 "The library, linked to the main program, creates the child process and hence "
2262 "the appliance in the L</guestfs_launch> function."
2263 msgstr ""
2264
2265 # type: textblock
2266 #: ../src/guestfs.pod:1089
2267 msgid ""
2268 "Inside the appliance is a Linux kernel and a complete stack of userspace "
2269 "tools (such as LVM and ext2 programs) and a small controlling daemon called "
2270 "L</guestfsd>.  The library talks to L</guestfsd> using remote procedure "
2271 "calls (RPC).  There is a mostly one-to-one correspondence between libguestfs "
2272 "API calls and RPC calls to the daemon.  Lastly the disk image(s) are "
2273 "attached to the qemu process which translates device access by the "
2274 "appliance's Linux kernel into accesses to the image."
2275 msgstr ""
2276
2277 # type: textblock
2278 #: ../src/guestfs.pod:1098
2279 msgid ""
2280 "A common misunderstanding is that the appliance \"is\" the virtual machine.  "
2281 "Although the disk image you are attached to might also be used by some "
2282 "virtual machine, libguestfs doesn't know or care about this.  (But you will "
2283 "care if both libguestfs's qemu process and your virtual machine are trying "
2284 "to update the disk image at the same time, since these usually results in "
2285 "massive disk corruption)."
2286 msgstr ""
2287
2288 # type: =head1
2289 #: ../src/guestfs.pod:1105
2290 msgid "STATE MACHINE"
2291 msgstr ""
2292
2293 # type: textblock
2294 #: ../src/guestfs.pod:1107
2295 msgid "libguestfs uses a state machine to model the child process:"
2296 msgstr ""
2297
2298 # type: verbatim
2299 #: ../src/guestfs.pod:1109
2300 #, no-wrap
2301 msgid ""
2302 "                         |\n"
2303 "                    guestfs_create\n"
2304 "                         |\n"
2305 "                         |\n"
2306 "                     ____V_____\n"
2307 "                    /          \\\n"
2308 "                    |  CONFIG  |\n"
2309 "                    \\__________/\n"
2310 "                     ^ ^   ^  \\\n"
2311 "                    /  |    \\  \\ guestfs_launch\n"
2312 "                   /   |    _\\__V______\n"
2313 "                  /    |   /           \\\n"
2314 "                 /     |   | LAUNCHING |\n"
2315 "                /      |   \\___________/\n"
2316 "               /       |       /\n"
2317 "              /        |  guestfs_launch\n"
2318 "             /         |     /\n"
2319 "    ______  /        __|____V\n"
2320 "   /      \\ ------> /        \\\n"
2321 "   | BUSY |         | READY  |\n"
2322 "   \\______/ <------ \\________/\n"
2323 "\n"
2324 msgstr ""
2325
2326 # type: textblock
2327 #: ../src/guestfs.pod:1131
2328 msgid ""
2329 "The normal transitions are (1) CONFIG (when the handle is created, but there "
2330 "is no child process), (2) LAUNCHING (when the child process is booting up), "
2331 "(3) alternating between READY and BUSY as commands are issued to, and "
2332 "carried out by, the child process."
2333 msgstr ""
2334
2335 # type: textblock
2336 #: ../src/guestfs.pod:1136
2337 msgid ""
2338 "The guest may be killed by L</guestfs_kill_subprocess>, or may die "
2339 "asynchronously at any time (eg. due to some internal error), and that causes "
2340 "the state to transition back to CONFIG."
2341 msgstr ""
2342
2343 # type: textblock
2344 #: ../src/guestfs.pod:1140
2345 msgid ""
2346 "Configuration commands for qemu such as L</guestfs_add_drive> can only be "
2347 "issued when in the CONFIG state."
2348 msgstr ""
2349
2350 # type: textblock
2351 #: ../src/guestfs.pod:1143
2352 msgid ""
2353 "The API offers one call that goes from CONFIG through LAUNCHING to READY.  "
2354 "L</guestfs_launch> blocks until the child process is READY to accept "
2355 "commands (or until some failure or timeout).  L</guestfs_launch> internally "
2356 "moves the state from CONFIG to LAUNCHING while it is running."
2357 msgstr ""
2358
2359 # type: textblock
2360 #: ../src/guestfs.pod:1149
2361 msgid ""
2362 "API actions such as L</guestfs_mount> can only be issued when in the READY "
2363 "state.  These API calls block waiting for the command to be carried out (ie. "
2364 "the state to transition to BUSY and then back to READY).  There are no non-"
2365 "blocking versions, and no way to issue more than one command per handle at "
2366 "the same time."
2367 msgstr ""
2368
2369 # type: textblock
2370 #: ../src/guestfs.pod:1155
2371 msgid ""
2372 "Finally, the child process sends asynchronous messages back to the main "
2373 "program, such as kernel log messages.  You can register a callback to "
2374 "receive these messages."
2375 msgstr ""
2376
2377 # type: =head2
2378 #: ../src/guestfs.pod:1159
2379 msgid "SETTING CALLBACKS TO HANDLE EVENTS"
2380 msgstr ""
2381
2382 # type: textblock
2383 #: ../src/guestfs.pod:1161
2384 msgid ""
2385 "The child process generates events in some situations.  Current events "
2386 "include: receiving a log message, the child process exits."
2387 msgstr ""
2388
2389 # type: textblock
2390 #: ../src/guestfs.pod:1164
2391 msgid ""
2392 "Use the C<guestfs_set_*_callback> functions to set a callback for different "
2393 "types of events."
2394 msgstr ""
2395
2396 # type: textblock
2397 #: ../src/guestfs.pod:1167
2398 msgid ""
2399 "Only I<one callback of each type> can be registered for each handle.  "
2400 "Calling C<guestfs_set_*_callback> again overwrites the previous callback of "
2401 "that type.  Cancel all callbacks of this type by calling this function with "
2402 "C<cb> set to C<NULL>."
2403 msgstr ""
2404
2405 # type: =head2
2406 #: ../src/guestfs.pod:1172
2407 msgid "guestfs_set_log_message_callback"
2408 msgstr ""
2409
2410 # type: verbatim
2411 #: ../src/guestfs.pod:1174
2412 #, no-wrap
2413 msgid ""
2414 " typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,\n"
2415 "                                         char *buf, int len);\n"
2416 " void guestfs_set_log_message_callback (guestfs_h *g,\n"
2417 "                                        guestfs_log_message_cb cb,\n"
2418 "                                        void *opaque);\n"
2419 "\n"
2420 msgstr ""
2421
2422 # type: textblock
2423 #: ../src/guestfs.pod:1180
2424 msgid ""
2425 "The callback function C<cb> will be called whenever qemu or the guest writes "
2426 "anything to the console."
2427 msgstr ""
2428
2429 # type: textblock
2430 #: ../src/guestfs.pod:1183
2431 msgid "Use this function to capture kernel messages and similar."
2432 msgstr ""
2433
2434 # type: textblock
2435 #: ../src/guestfs.pod:1185
2436 msgid ""
2437 "Normally there is no log message handler, and log messages are just "
2438 "discarded."
2439 msgstr ""
2440
2441 # type: =head2
2442 #: ../src/guestfs.pod:1188
2443 msgid "guestfs_set_subprocess_quit_callback"
2444 msgstr ""
2445
2446 # type: verbatim
2447 #: ../src/guestfs.pod:1190
2448 #, no-wrap
2449 msgid ""
2450 " typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);\n"
2451 " void guestfs_set_subprocess_quit_callback (guestfs_h *g,\n"
2452 "                                            guestfs_subprocess_quit_cb cb,\n"
2453 "                                            void *opaque);\n"
2454 "\n"
2455 msgstr ""
2456
2457 # type: textblock
2458 #: ../src/guestfs.pod:1195
2459 msgid ""
2460 "The callback function C<cb> will be called when the child process quits, "
2461 "either asynchronously or if killed by L</guestfs_kill_subprocess>.  (This "
2462 "corresponds to a transition from any state to the CONFIG state)."
2463 msgstr ""
2464
2465 # type: =head2
2466 #: ../src/guestfs.pod:1200
2467 msgid "guestfs_set_launch_done_callback"
2468 msgstr ""
2469
2470 # type: verbatim
2471 #: ../src/guestfs.pod:1202
2472 #, no-wrap
2473 msgid ""
2474 " typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);\n"
2475 " void guestfs_set_launch_done_callback (guestfs_h *g,\n"
2476 "                                        guestfs_launch_done_cb cb,\n"
2477 "                                        void *opaque);\n"
2478 "\n"
2479 msgstr ""
2480
2481 # type: textblock
2482 #: ../src/guestfs.pod:1207
2483 msgid ""
2484 "The callback function C<cb> will be called when the child process becomes "
2485 "ready first time after it has been launched.  (This corresponds to a "
2486 "transition from LAUNCHING to the READY state)."
2487 msgstr ""
2488
2489 # type: =head2
2490 #: ../src/guestfs.pod:1211
2491 msgid "guestfs_set_close_callback"
2492 msgstr ""
2493
2494 # type: verbatim
2495 #: ../src/guestfs.pod:1213
2496 #, no-wrap
2497 msgid ""
2498 " typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);\n"
2499 " void guestfs_set_close_callback (guestfs_h *g,\n"
2500 "                                  guestfs_close_cb cb,\n"
2501 "                                  void *opaque);\n"
2502 "\n"
2503 msgstr ""
2504
2505 # type: textblock
2506 #: ../src/guestfs.pod:1218
2507 msgid ""
2508 "The callback function C<cb> will be called while the handle is being closed "
2509 "(synchronously from L</guestfs_close>)."
2510 msgstr ""
2511
2512 # type: textblock
2513 #: ../src/guestfs.pod:1221
2514 msgid ""
2515 "Note that libguestfs installs an L<atexit(3)> handler to try to clean up "
2516 "handles that are open when the program exits.  This means that this callback "
2517 "might be called indirectly from L<exit(3)>, which can cause unexpected "
2518 "problems in higher-level languages (eg. if your HLL interpreter has already "
2519 "been cleaned up by the time this is called, and if your callback then jumps "
2520 "into some HLL function)."
2521 msgstr ""
2522
2523 # type: =head2
2524 #: ../src/guestfs.pod:1229
2525 msgid "guestfs_set_progress_callback"
2526 msgstr ""
2527
2528 # type: verbatim
2529 #: ../src/guestfs.pod:1231
2530 #, no-wrap
2531 msgid ""
2532 " typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque,\n"
2533 "                                      int proc_nr, int serial,\n"
2534 "                                      uint64_t position, uint64_t total);\n"
2535 " void guestfs_set_progress_callback (guestfs_h *g,\n"
2536 "                                     guestfs_progress_cb cb,\n"
2537 "                                     void *opaque);\n"
2538 "\n"
2539 msgstr ""
2540
2541 # type: textblock
2542 #: ../src/guestfs.pod:1238
2543 msgid ""
2544 "Some long-running operations can generate progress messages.  If this "
2545 "callback is registered, then it will be called each time a progress message "
2546 "is generated (usually two seconds after the operation started, and three "
2547 "times per second thereafter until it completes, although the frequency may "
2548 "change in future versions)."
2549 msgstr ""
2550
2551 # type: textblock
2552 #: ../src/guestfs.pod:1244
2553 msgid ""
2554 "The callback receives two numbers: C<position> and C<total>.  The units of "
2555 "C<total> are not defined, although for some operations C<total> may relate "
2556 "in some way to the amount of data to be transferred (eg. in bytes or "
2557 "megabytes), and C<position> may be the portion which has been transferred."
2558 msgstr ""
2559
2560 # type: textblock
2561 #: ../src/guestfs.pod:1250
2562 msgid "The only defined and stable parts of the API are:"
2563 msgstr ""
2564
2565 # type: textblock
2566 #: ../src/guestfs.pod:1256
2567 msgid ""
2568 "The callback can display to the user some type of progress bar or indicator "
2569 "which shows the ratio of C<position>:C<total>."
2570 msgstr ""
2571
2572 # type: textblock
2573 #: ../src/guestfs.pod:1261
2574 msgid "0 E<lt>= C<position> E<lt>= C<total>"
2575 msgstr ""
2576
2577 # type: textblock
2578 #: ../src/guestfs.pod:1265
2579 msgid ""
2580 "If any progress notification is sent during a call, then a final progress "
2581 "notification is always sent when C<position> = C<total>."
2582 msgstr ""
2583
2584 # type: textblock
2585 #: ../src/guestfs.pod:1268
2586 msgid ""
2587 "This is to simplify caller code, so callers can easily set the progress "
2588 "indicator to \"100%\" at the end of the operation, without requiring special "
2589 "code to detect this case."
2590 msgstr ""
2591
2592 # type: textblock
2593 #: ../src/guestfs.pod:1274
2594 msgid ""
2595 "The callback also receives the procedure number and serial number of the "
2596 "call.  These are only useful for debugging protocol issues, and the callback "
2597 "can normally ignore them.  The callback may want to print these numbers in "
2598 "error messages or debugging messages."
2599 msgstr ""
2600
2601 # type: =head1
2602 #: ../src/guestfs.pod:1279
2603 msgid "PRIVATE DATA AREA"
2604 msgstr ""
2605
2606 # type: textblock
2607 #: ../src/guestfs.pod:1281
2608 msgid ""
2609 "You can attach named pieces of private data to the libguestfs handle, and "
2610 "fetch them by name for the lifetime of the handle.  This is called the "
2611 "private data area and is only available from the C API."
2612 msgstr ""
2613
2614 # type: textblock
2615 #: ../src/guestfs.pod:1285
2616 msgid "To attach a named piece of data, use the following call:"
2617 msgstr ""
2618
2619 # type: verbatim
2620 #: ../src/guestfs.pod:1287
2621 #, no-wrap
2622 msgid ""
2623 " void guestfs_set_private (guestfs_h *g, const char *key, void *data);\n"
2624 "\n"
2625 msgstr ""
2626
2627 # type: textblock
2628 #: ../src/guestfs.pod:1289
2629 msgid ""
2630 "C<key> is the name to associate with this data, and C<data> is an arbitrary "
2631 "pointer (which can be C<NULL>).  Any previous item with the same name is "
2632 "overwritten."
2633 msgstr ""
2634
2635 # type: textblock
2636 #: ../src/guestfs.pod:1293
2637 msgid ""
2638 "You can use any C<key> you want, but names beginning with an underscore "
2639 "character are reserved for internal libguestfs purposes (for implementing "
2640 "language bindings).  It is recommended to prefix the name with some unique "
2641 "string to avoid collisions with other users."
2642 msgstr ""
2643
2644 # type: textblock
2645 #: ../src/guestfs.pod:1298
2646 msgid "To retrieve the pointer, use:"
2647 msgstr ""
2648
2649 # type: verbatim
2650 #: ../src/guestfs.pod:1300
2651 #, no-wrap
2652 msgid ""
2653 " void *guestfs_get_private (guestfs_h *g, const char *key);\n"
2654 "\n"
2655 msgstr ""
2656
2657 # type: textblock
2658 #: ../src/guestfs.pod:1302
2659 msgid ""
2660 "This function returns C<NULL> if either no data is found associated with "
2661 "C<key>, or if the user previously set the C<key>'s C<data> pointer to "
2662 "C<NULL>."
2663 msgstr ""
2664
2665 # type: textblock
2666 #: ../src/guestfs.pod:1306
2667 msgid ""
2668 "Libguestfs does not try to look at or interpret the C<data> pointer in any "
2669 "way.  As far as libguestfs is concerned, it need not be a valid pointer at "
2670 "all.  In particular, libguestfs does I<not> try to free the data when the "
2671 "handle is closed.  If the data must be freed, then the caller must either "
2672 "free it before calling L</guestfs_close> or must set up a close callback to "
2673 "do it (see L</guestfs_set_close_callback>, and note that only one callback "
2674 "can be registered for a handle)."
2675 msgstr ""
2676
2677 # type: textblock
2678 #: ../src/guestfs.pod:1314
2679 msgid ""
2680 "The private data area is implemented using a hash table, and should be "
2681 "reasonably efficient for moderate numbers of keys."
2682 msgstr ""
2683
2684 # type: =head1
2685 #: ../src/guestfs.pod:1317
2686 msgid "BLOCK DEVICE NAMING"
2687 msgstr ""
2688
2689 # type: textblock
2690 #: ../src/guestfs.pod:1319
2691 msgid ""
2692 "In the kernel there is now quite a profusion of schemata for naming block "
2693 "devices (in this context, by I<block device> I mean a physical or virtual "
2694 "hard drive).  The original Linux IDE driver used names starting with C</dev/"
2695 "hd*>.  SCSI devices have historically used a different naming scheme, C</dev/"
2696 "sd*>.  When the Linux kernel I<libata> driver became a popular replacement "
2697 "for the old IDE driver (particularly for SATA devices) those devices also "
2698 "used the C</dev/sd*> scheme.  Additionally we now have virtual machines with "
2699 "paravirtualized drivers.  This has created several different naming systems, "
2700 "such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen PV disks."
2701 msgstr ""
2702
2703 # type: textblock
2704 #: ../src/guestfs.pod:1331
2705 msgid ""
2706 "As discussed above, libguestfs uses a qemu appliance running an embedded "
2707 "Linux kernel to access block devices.  We can run a variety of appliances "
2708 "based on a variety of Linux kernels."
2709 msgstr ""
2710
2711 # type: textblock
2712 #: ../src/guestfs.pod:1335
2713 msgid ""
2714 "This causes a problem for libguestfs because many API calls use device or "
2715 "partition names.  Working scripts and the recipe (example) scripts that we "
2716 "make available over the internet could fail if the naming scheme changes."
2717 msgstr ""
2718
2719 # type: textblock
2720 #: ../src/guestfs.pod:1340
2721 msgid ""
2722 "Therefore libguestfs defines C</dev/sd*> as the I<standard naming scheme>.  "
2723 "Internally C</dev/sd*> names are translated, if necessary, to other names as "
2724 "required.  For example, under RHEL 5 which uses the C</dev/hd*> scheme, any "
2725 "device parameter C</dev/sda2> is translated to C</dev/hda2> transparently."
2726 msgstr ""
2727
2728 # type: textblock
2729 #: ../src/guestfs.pod:1346
2730 msgid ""
2731 "Note that this I<only> applies to parameters.  The L</guestfs_list_devices>, "
2732 "L</guestfs_list_partitions> and similar calls return the true names of the "
2733 "devices and partitions as known to the appliance."
2734 msgstr ""
2735
2736 # type: =head2
2737 #: ../src/guestfs.pod:1351
2738 msgid "ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION"
2739 msgstr ""
2740
2741 # type: textblock
2742 #: ../src/guestfs.pod:1353
2743 msgid ""
2744 "Usually this translation is transparent.  However in some (very rare)  cases "
2745 "you may need to know the exact algorithm.  Such cases include where you use "
2746 "L</guestfs_config> to add a mixture of virtio and IDE devices to the qemu-"
2747 "based appliance, so have a mixture of C</dev/sd*> and C</dev/vd*> devices."
2748 msgstr ""
2749
2750 # type: textblock
2751 #: ../src/guestfs.pod:1359
2752 msgid ""
2753 "The algorithm is applied only to I<parameters> which are known to be either "
2754 "device or partition names.  Return values from functions such as L</"
2755 "guestfs_list_devices> are never changed."
2756 msgstr ""
2757
2758 # type: textblock
2759 #: ../src/guestfs.pod:1367
2760 msgid "Is the string a parameter which is a device or partition name?"
2761 msgstr ""
2762
2763 # type: textblock
2764 #: ../src/guestfs.pod:1371
2765 msgid "Does the string begin with C</dev/sd>?"
2766 msgstr ""
2767
2768 # type: textblock
2769 #: ../src/guestfs.pod:1375
2770 msgid ""
2771 "Does the named device exist? If so, we use that device.  However if I<not> "
2772 "then we continue with this algorithm."
2773 msgstr ""
2774
2775 # type: textblock
2776 #: ../src/guestfs.pod:1380
2777 msgid "Replace initial C</dev/sd> string with C</dev/hd>."
2778 msgstr ""
2779
2780 # type: textblock
2781 #: ../src/guestfs.pod:1382
2782 msgid "For example, change C</dev/sda2> to C</dev/hda2>."
2783 msgstr ""
2784
2785 # type: textblock
2786 #: ../src/guestfs.pod:1384
2787 msgid "If that named device exists, use it.  If not, continue."
2788 msgstr ""
2789
2790 # type: textblock
2791 #: ../src/guestfs.pod:1388
2792 msgid "Replace initial C</dev/sd> string with C</dev/vd>."
2793 msgstr ""
2794
2795 # type: textblock
2796 #: ../src/guestfs.pod:1390
2797 msgid "If that named device exists, use it.  If not, return an error."
2798 msgstr ""
2799
2800 # type: =head2
2801 #: ../src/guestfs.pod:1394
2802 msgid "PORTABILITY CONCERNS"
2803 msgstr ""
2804
2805 # type: textblock
2806 #: ../src/guestfs.pod:1396
2807 msgid ""
2808 "Although the standard naming scheme and automatic translation is useful for "
2809 "simple programs and guestfish scripts, for larger programs it is best not to "
2810 "rely on this mechanism."
2811 msgstr ""
2812
2813 # type: textblock
2814 #: ../src/guestfs.pod:1400
2815 msgid ""
2816 "Where possible for maximum future portability programs using libguestfs "
2817 "should use these future-proof techniques:"
2818 msgstr ""
2819
2820 # type: textblock
2821 #: ../src/guestfs.pod:1407
2822 msgid ""
2823 "Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list actual "
2824 "device names, and then use those names directly."
2825 msgstr ""
2826
2827 # type: textblock
2828 #: ../src/guestfs.pod:1410
2829 msgid ""
2830 "Since those device names exist by definition, they will never be translated."
2831 msgstr ""
2832
2833 # type: textblock
2834 #: ../src/guestfs.pod:1415
2835 msgid ""
2836 "Use higher level ways to identify filesystems, such as LVM names, UUIDs and "
2837 "filesystem labels."
2838 msgstr ""
2839
2840 # type: =head1
2841 #: ../src/guestfs.pod:1420
2842 msgid "INTERNALS"
2843 msgstr ""
2844
2845 # type: =head2
2846 #: ../src/guestfs.pod:1422
2847 msgid "COMMUNICATION PROTOCOL"
2848 msgstr ""
2849
2850 # type: textblock
2851 #: ../src/guestfs.pod:1424
2852 msgid ""
2853 "Don't rely on using this protocol directly.  This section documents how it "
2854 "currently works, but it may change at any time."
2855 msgstr ""
2856
2857 # type: textblock
2858 #: ../src/guestfs.pod:1427
2859 msgid ""
2860 "The protocol used to talk between the library and the daemon running inside "
2861 "the qemu virtual machine is a simple RPC mechanism built on top of XDR (RFC "
2862 "1014, RFC 1832, RFC 4506)."
2863 msgstr ""
2864
2865 # type: textblock
2866 #: ../src/guestfs.pod:1431
2867 msgid ""
2868 "The detailed format of structures is in C<src/guestfs_protocol.x> (note: "
2869 "this file is automatically generated)."
2870 msgstr ""
2871
2872 # type: textblock
2873 #: ../src/guestfs.pod:1434
2874 msgid ""
2875 "There are two broad cases, ordinary functions that don't have any C<FileIn> "
2876 "and C<FileOut> parameters, which are handled with very simple request/reply "
2877 "messages.  Then there are functions that have any C<FileIn> or C<FileOut> "
2878 "parameters, which use the same request and reply messages, but they may also "
2879 "be followed by files sent using a chunked encoding."
2880 msgstr ""
2881
2882 # type: =head3
2883 #: ../src/guestfs.pod:1441
2884 msgid "ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)"
2885 msgstr ""
2886
2887 # type: textblock
2888 #: ../src/guestfs.pod:1443
2889 msgid "For ordinary functions, the request message is:"
2890 msgstr ""
2891
2892 # type: verbatim
2893 #: ../src/guestfs.pod:1445
2894 #, no-wrap
2895 msgid ""
2896 " total length (header + arguments,\n"
2897 "      but not including the length word itself)\n"
2898 " struct guestfs_message_header (encoded as XDR)\n"
2899 " struct guestfs_<foo>_args (encoded as XDR)\n"
2900 "\n"
2901 msgstr ""
2902
2903 # type: textblock
2904 #: ../src/guestfs.pod:1450
2905 msgid ""
2906 "The total length field allows the daemon to allocate a fixed size buffer "
2907 "into which it slurps the rest of the message.  As a result, the total length "
2908 "is limited to C<GUESTFS_MESSAGE_MAX> bytes (currently 4MB), which means the "
2909 "effective size of any request is limited to somewhere under this size."
2910 msgstr ""
2911
2912 # type: textblock
2913 #: ../src/guestfs.pod:1456
2914 msgid ""
2915 "Note also that many functions don't take any arguments, in which case the "
2916 "C<guestfs_I<foo>_args> is completely omitted."
2917 msgstr ""
2918
2919 # type: textblock
2920 #: ../src/guestfs.pod:1459
2921 msgid ""
2922 "The header contains the procedure number (C<guestfs_proc>) which is how the "
2923 "receiver knows what type of args structure to expect, or none at all."
2924 msgstr ""
2925
2926 # type: textblock
2927 #: ../src/guestfs.pod:1463
2928 msgid "The reply message for ordinary functions is:"
2929 msgstr ""
2930
2931 # type: verbatim
2932 #: ../src/guestfs.pod:1465
2933 #, no-wrap
2934 msgid ""
2935 " total length (header + ret,\n"
2936 "      but not including the length word itself)\n"
2937 " struct guestfs_message_header (encoded as XDR)\n"
2938 " struct guestfs_<foo>_ret (encoded as XDR)\n"
2939 "\n"
2940 msgstr ""
2941
2942 # type: textblock
2943 #: ../src/guestfs.pod:1470
2944 msgid ""
2945 "As above the C<guestfs_I<foo>_ret> structure may be completely omitted for "
2946 "functions that return no formal return values."
2947 msgstr ""
2948
2949 # type: textblock
2950 #: ../src/guestfs.pod:1473
2951 msgid ""
2952 "As above the total length of the reply is limited to C<GUESTFS_MESSAGE_MAX>."
2953 msgstr ""
2954
2955 # type: textblock
2956 #: ../src/guestfs.pod:1476
2957 msgid ""
2958 "In the case of an error, a flag is set in the header, and the reply message "
2959 "is slightly changed:"
2960 msgstr ""
2961
2962 # type: verbatim
2963 #: ../src/guestfs.pod:1479
2964 #, no-wrap
2965 msgid ""
2966 " total length (header + error,\n"
2967 "      but not including the length word itself)\n"
2968 " struct guestfs_message_header (encoded as XDR)\n"
2969 " struct guestfs_message_error (encoded as XDR)\n"
2970 "\n"
2971 msgstr ""
2972
2973 # type: textblock
2974 #: ../src/guestfs.pod:1484
2975 msgid ""
2976 "The C<guestfs_message_error> structure contains the error message as a "
2977 "string."
2978 msgstr ""
2979
2980 # type: =head3
2981 #: ../src/guestfs.pod:1487
2982 msgid "FUNCTIONS THAT HAVE FILEIN PARAMETERS"
2983 msgstr ""
2984
2985 # type: textblock
2986 #: ../src/guestfs.pod:1489
2987 msgid ""
2988 "A C<FileIn> parameter indicates that we transfer a file I<into> the guest.  "
2989 "The normal request message is sent (see above).  However this is followed by "
2990 "a sequence of file chunks."
2991 msgstr ""
2992
2993 # type: verbatim
2994 #: ../src/guestfs.pod:1493
2995 #, no-wrap
2996 msgid ""
2997 " total length (header + arguments,\n"
2998 "      but not including the length word itself,\n"
2999 "      and not including the chunks)\n"
3000 " struct guestfs_message_header (encoded as XDR)\n"
3001 " struct guestfs_<foo>_args (encoded as XDR)\n"
3002 " sequence of chunks for FileIn param #0\n"
3003 " sequence of chunks for FileIn param #1 etc.\n"
3004 "\n"
3005 msgstr ""
3006
3007 # type: textblock
3008 #: ../src/guestfs.pod:1501
3009 msgid "The \"sequence of chunks\" is:"
3010 msgstr ""
3011
3012 # type: verbatim
3013 #: ../src/guestfs.pod:1503
3014 #, no-wrap
3015 msgid ""
3016 " length of chunk (not including length word itself)\n"
3017 " struct guestfs_chunk (encoded as XDR)\n"
3018 " length of chunk\n"
3019 " struct guestfs_chunk (encoded as XDR)\n"
3020 "   ...\n"
3021 " length of chunk\n"
3022 " struct guestfs_chunk (with data.data_len == 0)\n"
3023 "\n"
3024 msgstr ""
3025
3026 # type: textblock
3027 #: ../src/guestfs.pod:1511
3028 msgid ""
3029 "The final chunk has the C<data_len> field set to zero.  Additionally a flag "
3030 "is set in the final chunk to indicate either successful completion or early "
3031 "cancellation."
3032 msgstr ""
3033
3034 # type: textblock
3035 #: ../src/guestfs.pod:1515
3036 msgid ""
3037 "At time of writing there are no functions that have more than one FileIn "
3038 "parameter.  However this is (theoretically) supported, by sending the "
3039 "sequence of chunks for each FileIn parameter one after another (from left to "
3040 "right)."
3041 msgstr ""
3042
3043 # type: textblock
3044 #: ../src/guestfs.pod:1520
3045 msgid ""
3046 "Both the library (sender) I<and> the daemon (receiver) may cancel the "
3047 "transfer.  The library does this by sending a chunk with a special flag set "
3048 "to indicate cancellation.  When the daemon sees this, it cancels the whole "
3049 "RPC, does I<not> send any reply, and goes back to reading the next request."
3050 msgstr ""
3051
3052 # type: textblock
3053 #: ../src/guestfs.pod:1526
3054 msgid ""
3055 "The daemon may also cancel.  It does this by writing a special word "
3056 "C<GUESTFS_CANCEL_FLAG> to the socket.  The library listens for this during "
3057 "the transfer, and if it gets it, it will cancel the transfer (it sends a "
3058 "cancel chunk).  The special word is chosen so that even if cancellation "
3059 "happens right at the end of the transfer (after the library has finished "
3060 "writing and has started listening for the reply), the \"spurious\" cancel "
3061 "flag will not be confused with the reply message."
3062 msgstr ""
3063
3064 # type: textblock
3065 #: ../src/guestfs.pod:1535
3066 msgid ""
3067 "This protocol allows the transfer of arbitrary sized files (no 32 bit "
3068 "limit), and also files where the size is not known in advance (eg. from "
3069 "pipes or sockets).  However the chunks are rather small "
3070 "(C<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the daemon need "
3071 "to keep much in memory."
3072 msgstr ""
3073
3074 # type: =head3
3075 #: ../src/guestfs.pod:1541
3076 msgid "FUNCTIONS THAT HAVE FILEOUT PARAMETERS"
3077 msgstr ""
3078
3079 # type: textblock
3080 #: ../src/guestfs.pod:1543
3081 msgid ""
3082 "The protocol for FileOut parameters is exactly the same as for FileIn "
3083 "parameters, but with the roles of daemon and library reversed."
3084 msgstr ""
3085
3086 # type: verbatim
3087 #: ../src/guestfs.pod:1546
3088 #, no-wrap
3089 msgid ""
3090 " total length (header + ret,\n"
3091 "      but not including the length word itself,\n"
3092 "      and not including the chunks)\n"
3093 " struct guestfs_message_header (encoded as XDR)\n"
3094 " struct guestfs_<foo>_ret (encoded as XDR)\n"
3095 " sequence of chunks for FileOut param #0\n"
3096 " sequence of chunks for FileOut param #1 etc.\n"
3097 "\n"
3098 msgstr ""
3099
3100 # type: =head3
3101 #: ../src/guestfs.pod:1554
3102 msgid "INITIAL MESSAGE"
3103 msgstr ""
3104
3105 # type: textblock
3106 #: ../src/guestfs.pod:1556
3107 msgid ""
3108 "When the daemon launches it sends an initial word (C<GUESTFS_LAUNCH_FLAG>) "
3109 "which indicates that the guest and daemon is alive.  This is what L</"
3110 "guestfs_launch> waits for."
3111 msgstr ""
3112
3113 # type: =head3
3114 #: ../src/guestfs.pod:1560
3115 msgid "PROGRESS NOTIFICATION MESSAGES"
3116 msgstr ""
3117
3118 # type: textblock
3119 #: ../src/guestfs.pod:1562
3120 msgid ""
3121 "The daemon may send progress notification messages at any time.  These are "
3122 "distinguished by the normal length word being replaced by "
3123 "C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message."
3124 msgstr ""
3125
3126 # type: textblock
3127 #: ../src/guestfs.pod:1566
3128 msgid ""
3129 "The library turns them into progress callbacks (see "
3130 "C<guestfs_set_progress_callback>) if there is a callback registered, or "
3131 "discards them if not."
3132 msgstr ""
3133
3134 # type: textblock
3135 #: ../src/guestfs.pod:1570
3136 msgid ""
3137 "The daemon self-limits the frequency of progress messages it sends (see "
3138 "C<daemon/proto.c:notify_progress>).  Not all calls generate progress "
3139 "messages."
3140 msgstr ""
3141
3142 # type: =head1
3143 #: ../src/guestfs.pod:1574
3144 msgid "MULTIPLE HANDLES AND MULTIPLE THREADS"
3145 msgstr ""
3146
3147 # type: textblock
3148 #: ../src/guestfs.pod:1576
3149 msgid ""
3150 "All high-level libguestfs actions are synchronous.  If you want to use "
3151 "libguestfs asynchronously then you must create a thread."
3152 msgstr ""
3153
3154 # type: textblock
3155 #: ../src/guestfs.pod:1579
3156 msgid ""
3157 "Only use the handle from a single thread.  Either use the handle exclusively "
3158 "from one thread, or provide your own mutex so that two threads cannot issue "
3159 "calls on the same handle at the same time."
3160 msgstr ""
3161
3162 # type: textblock
3163 #: ../src/guestfs.pod:1583
3164 msgid ""
3165 "See the graphical program guestfs-browser for one possible architecture for "
3166 "multithreaded programs using libvirt and libguestfs."
3167 msgstr ""
3168
3169 # type: =head1
3170 #: ../src/guestfs.pod:1586
3171 msgid "QEMU WRAPPERS"
3172 msgstr ""
3173
3174 # type: textblock
3175 #: ../src/guestfs.pod:1588
3176 msgid ""
3177 "If you want to compile your own qemu, run qemu from a non-standard location, "
3178 "or pass extra arguments to qemu, then you can write a shell-script wrapper "
3179 "around qemu."
3180 msgstr ""
3181
3182 # type: textblock
3183 #: ../src/guestfs.pod:1592
3184 msgid ""
3185 "There is one important rule to remember: you I<must C<exec qemu>> as the "
3186 "last command in the shell script (so that qemu replaces the shell and "
3187 "becomes the direct child of the libguestfs-using program).  If you don't do "
3188 "this, then the qemu process won't be cleaned up correctly."
3189 msgstr ""
3190
3191 # type: textblock
3192 #: ../src/guestfs.pod:1597
3193 msgid ""
3194 "Here is an example of a wrapper, where I have built my own copy of qemu from "
3195 "source:"
3196 msgstr ""
3197
3198 # type: verbatim
3199 #: ../src/guestfs.pod:1600
3200 #, no-wrap
3201 msgid ""
3202 " #!/bin/sh -\n"
3203 " qemudir=/home/rjones/d/qemu\n"
3204 " exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios \"$@\"\n"
3205 "\n"
3206 msgstr ""
3207
3208 # type: textblock
3209 #: ../src/guestfs.pod:1604
3210 msgid ""
3211 "Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>, and "
3212 "then use it by setting the LIBGUESTFS_QEMU environment variable.  For "
3213 "example:"
3214 msgstr ""
3215
3216 # type: verbatim
3217 #: ../src/guestfs.pod:1608
3218 #, no-wrap
3219 msgid ""
3220 " LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish\n"
3221 "\n"
3222 msgstr ""
3223
3224 # type: textblock
3225 #: ../src/guestfs.pod:1610
3226 msgid ""
3227 "Note that libguestfs also calls qemu with the -help and -version options in "
3228 "order to determine features."
3229 msgstr ""
3230
3231 # type: =head1
3232 #: ../src/guestfs.pod:1613
3233 msgid "LIBGUESTFS VERSION NUMBERS"
3234 msgstr ""
3235
3236 # type: textblock
3237 #: ../src/guestfs.pod:1615
3238 msgid ""
3239 "Since April 2010, libguestfs has started to make separate development and "
3240 "stable releases, along with corresponding branches in our git repository.  "
3241 "These separate releases can be identified by version number:"
3242 msgstr ""
3243
3244 # type: verbatim
3245 #: ../src/guestfs.pod:1620
3246 #, no-wrap
3247 msgid ""
3248 "                 even numbers for stable: 1.2.x, 1.4.x, ...\n"
3249 "       .-------- odd numbers for development: 1.3.x, 1.5.x, ...\n"
3250 "       |\n"
3251 "       v\n"
3252 " 1  .  3  .  5\n"
3253 " ^           ^\n"
3254 " |           |\n"
3255 " |           `-------- sub-version\n"
3256 " |\n"
3257 " `------ always '1' because we don't change the ABI\n"
3258 "\n"
3259 msgstr ""
3260
3261 # type: textblock
3262 #: ../src/guestfs.pod:1631
3263 msgid "Thus \"1.3.5\" is the 5th update to the development branch \"1.3\"."
3264 msgstr ""
3265
3266 # type: textblock
3267 #: ../src/guestfs.pod:1633
3268 msgid ""
3269 "As time passes we cherry pick fixes from the development branch and backport "
3270 "those into the stable branch, the effect being that the stable branch should "
3271 "get more stable and less buggy over time.  So the stable releases are ideal "
3272 "for people who don't need new features but would just like the software to "
3273 "work."
3274 msgstr ""
3275
3276 # type: textblock
3277 #: ../src/guestfs.pod:1639
3278 msgid "Our criteria for backporting changes are:"
3279 msgstr ""
3280
3281 # type: textblock
3282 #: ../src/guestfs.pod:1645
3283 msgid ""
3284 "Documentation changes which don't affect any code are backported unless the "
3285 "documentation refers to a future feature which is not in stable."
3286 msgstr ""
3287
3288 # type: textblock
3289 #: ../src/guestfs.pod:1651
3290 msgid ""
3291 "Bug fixes which are not controversial, fix obvious problems, and have been "
3292 "well tested are backported."
3293 msgstr ""
3294
3295 # type: textblock
3296 #: ../src/guestfs.pod:1656
3297 msgid ""
3298 "Simple rearrangements of code which shouldn't affect how it works get "
3299 "backported.  This is so that the code in the two branches doesn't get too "
3300 "far out of step, allowing us to backport future fixes more easily."
3301 msgstr ""
3302
3303 # type: textblock
3304 #: ../src/guestfs.pod:1662
3305 msgid ""
3306 "We I<don't> backport new features, new APIs, new tools etc, except in one "
3307 "exceptional case: the new feature is required in order to implement an "
3308 "important bug fix."
3309 msgstr ""
3310
3311 # type: textblock
3312 #: ../src/guestfs.pod:1668
3313 msgid ""
3314 "A new stable branch starts when we think the new features in development are "
3315 "substantial and compelling enough over the current stable branch to warrant "
3316 "it.  When that happens we create new stable and development versions 1.N.0 "
3317 "and 1.(N+1).0 [N is even].  The new dot-oh release won't necessarily be so "
3318 "stable at this point, but by backporting fixes from development, that branch "
3319 "will stabilize over time."
3320 msgstr ""
3321
3322 # type: =head1
3323 #: ../src/guestfs.pod:1676 ../fish/guestfish.pod:826
3324 #: ../test-tool/libguestfs-test-tool.pod:104 ../tools/virt-edit.pl:312
3325 #: ../tools/virt-rescue.pl:226
3326 msgid "ENVIRONMENT VARIABLES"
3327 msgstr ""
3328
3329 # type: =item
3330 #: ../src/guestfs.pod:1680 ../fish/guestfish.pod:852
3331 msgid "LIBGUESTFS_APPEND"
3332 msgstr ""
3333
3334 # type: textblock
3335 #: ../src/guestfs.pod:1682 ../fish/guestfish.pod:854
3336 msgid "Pass additional options to the guest kernel."
3337 msgstr ""
3338
3339 # type: =item
3340 #: ../src/guestfs.pod:1684 ../fish/guestfish.pod:856
3341 msgid "LIBGUESTFS_DEBUG"
3342 msgstr ""
3343
3344 # type: textblock
3345 #: ../src/guestfs.pod:1686
3346 msgid ""
3347 "Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This has the same "
3348 "effect as calling C<guestfs_set_verbose (g, 1)>."
3349 msgstr ""
3350
3351 # type: =item
3352 #: ../src/guestfs.pod:1689 ../fish/guestfish.pod:861
3353 msgid "LIBGUESTFS_MEMSIZE"
3354 msgstr ""
3355
3356 # type: textblock
3357 #: ../src/guestfs.pod:1691 ../fish/guestfish.pod:863
3358 msgid ""
3359 "Set the memory allocated to the qemu process, in megabytes.  For example:"
3360 msgstr ""
3361
3362 # type: verbatim
3363 #: ../src/guestfs.pod:1694 ../fish/guestfish.pod:866
3364 #, no-wrap
3365 msgid ""
3366 " LIBGUESTFS_MEMSIZE=700\n"
3367 "\n"
3368 msgstr ""
3369
3370 # type: =item
3371 #: ../src/guestfs.pod:1696 ../fish/guestfish.pod:868
3372 msgid "LIBGUESTFS_PATH"
3373 msgstr ""
3374
3375 # type: textblock
3376 #: ../src/guestfs.pod:1698
3377 msgid ""
3378 "Set the path that libguestfs uses to search for kernel and initrd.img.  See "
3379 "the discussion of paths in section PATH above."
3380 msgstr ""
3381
3382 # type: =item
3383 #: ../src/guestfs.pod:1701 ../fish/guestfish.pod:873
3384 msgid "LIBGUESTFS_QEMU"
3385 msgstr ""
3386
3387 # type: textblock
3388 #: ../src/guestfs.pod:1703 ../fish/guestfish.pod:875
3389 msgid ""
3390 "Set the default qemu binary that libguestfs uses.  If not set, then the qemu "
3391 "which was found at compile time by the configure script is used."
3392 msgstr ""
3393
3394 # type: textblock
3395 #: ../src/guestfs.pod:1707
3396 msgid "See also L</QEMU WRAPPERS> above."
3397 msgstr ""
3398
3399 # type: =item
3400 #: ../src/guestfs.pod:1709 ../fish/guestfish.pod:879
3401 msgid "LIBGUESTFS_TRACE"
3402 msgstr ""
3403
3404 # type: textblock
3405 #: ../src/guestfs.pod:1711
3406 msgid ""
3407 "Set C<LIBGUESTFS_TRACE=1> to enable command traces.  This has the same "
3408 "effect as calling C<guestfs_set_trace (g, 1)>."
3409 msgstr ""
3410
3411 # type: =item
3412 #: ../src/guestfs.pod:1714 ../fish/guestfish.pod:888
3413 msgid "TMPDIR"
3414 msgstr ""
3415
3416 # type: textblock
3417 #: ../src/guestfs.pod:1716 ../fish/guestfish.pod:890
3418 msgid "Location of temporary directory, defaults to C</tmp>."
3419 msgstr ""
3420
3421 # type: textblock
3422 #: ../src/guestfs.pod:1718 ../fish/guestfish.pod:892
3423 msgid ""
3424 "If libguestfs was compiled to use the supermin appliance then the real "
3425 "appliance is cached in this directory, shared between all handles belonging "
3426 "to the same EUID.  You can use C<$TMPDIR> to configure another directory to "
3427 "use in case C</tmp> is not large enough."
3428 msgstr ""
3429
3430 # type: =head1
3431 #: ../src/guestfs.pod:1726 ../fish/guestfish.pod:950
3432 #: ../test-tool/libguestfs-test-tool.pod:109 ../fuse/guestmount.pod:178
3433 #: ../inspector/virt-inspector.pl:846 ../tools/virt-edit.pl:325
3434 #: ../tools/virt-win-reg.pl:461 ../tools/virt-df.pl:536
3435 #: ../tools/virt-ls.pl:210 ../tools/virt-resize.pl:1399
3436 #: ../tools/virt-list-filesystems.pl:191 ../tools/virt-cat.pl:163
3437 #: ../tools/virt-tar.pl:257 ../tools/virt-rescue.pl:231
3438 #: ../tools/virt-make-fs.pl:527 ../tools/virt-list-partitions.pl:229
3439 msgid "SEE ALSO"
3440 msgstr ""
3441
3442 # type: textblock
3443 #: ../src/guestfs.pod:1728
3444 msgid ""
3445 "L<guestfish(1)>, L<guestmount(1)>, L<virt-cat(1)>, L<virt-df(1)>, L<virt-edit"
3446 "(1)>, L<virt-inspector(1)>, L<virt-list-filesystems(1)>, L<virt-list-"
3447 "partitions(1)>, L<virt-ls(1)>, L<virt-make-fs(1)>, L<virt-rescue(1)>, L<virt-"
3448 "tar(1)>, L<virt-win-reg(1)>, L<qemu(1)>, L<febootstrap(1)>, L<hivex(3)>, "
3449 "L<http://libguestfs.org/>."
3450 msgstr ""
3451
3452 # type: textblock
3453 #: ../src/guestfs.pod:1746
3454 msgid ""
3455 "Tools with a similar purpose: L<fdisk(8)>, L<parted(8)>, L<kpartx(8)>, L<lvm"
3456 "(8)>, L<disktype(1)>."
3457 msgstr ""
3458
3459 # type: =head1
3460 #: ../src/guestfs.pod:1753 ../tools/virt-win-reg.pl:476
3461 #: ../tools/virt-make-fs.pl:541
3462 msgid "BUGS"
3463 msgstr ""
3464
3465 # type: textblock
3466 #: ../src/guestfs.pod:1755
3467 msgid "To get a list of bugs against libguestfs use this link:"
3468 msgstr ""
3469
3470 # type: textblock
3471 #: ../src/guestfs.pod:1757
3472 msgid ""
3473 "L<https://bugzilla.redhat.com/buglist.cgi?"
3474 "component=libguestfs&product=Virtualization+Tools>"
3475 msgstr ""
3476
3477 # type: textblock
3478 #: ../src/guestfs.pod:1759
3479 msgid "To report a new bug against libguestfs use this link:"
3480 msgstr ""
3481
3482 # type: textblock
3483 #: ../src/guestfs.pod:1761
3484 msgid ""
3485 "L<https://bugzilla.redhat.com/enter_bug.cgi?"
3486 "component=libguestfs&product=Virtualization+Tools>"
3487 msgstr ""
3488
3489 # type: textblock
3490 #: ../src/guestfs.pod:1763
3491 msgid "When reporting a bug, please check:"
3492 msgstr ""
3493
3494 # type: textblock
3495 #: ../src/guestfs.pod:1769
3496 msgid "That the bug hasn't been reported already."
3497 msgstr ""
3498
3499 # type: textblock
3500 #: ../src/guestfs.pod:1773
3501 msgid "That you are testing a recent version."
3502 msgstr ""
3503
3504 # type: textblock
3505 #: ../src/guestfs.pod:1777
3506 msgid "Describe the bug accurately, and give a way to reproduce it."
3507 msgstr ""
3508
3509 # type: textblock
3510 #: ../src/guestfs.pod:1781
3511 msgid ""
3512 "Run libguestfs-test-tool and paste the B<complete, unedited> output into the "
3513 "bug report."
3514 msgstr ""
3515
3516 # type: =head1
3517 #: ../src/guestfs.pod:1786 ../fish/guestfish.pod:967
3518 #: ../test-tool/libguestfs-test-tool.pod:115 ../fuse/guestmount.pod:189
3519 #: ../inspector/virt-inspector.pl:855
3520 msgid "AUTHORS"
3521 msgstr ""
3522
3523 # type: textblock
3524 #: ../src/guestfs.pod:1788 ../fish/guestfish.pod:969
3525 #: ../test-tool/libguestfs-test-tool.pod:117 ../fuse/guestmount.pod:191
3526 msgid "Richard W.M. Jones (C<rjones at redhat dot com>)"
3527 msgstr ""
3528
3529 # type: =head1
3530 #: ../src/guestfs.pod:1790 ../fish/guestfish.pod:971
3531 #: ../test-tool/libguestfs-test-tool.pod:119 ../fuse/guestmount.pod:193
3532 #: ../inspector/virt-inspector.pl:861 ../tools/virt-edit.pl:341
3533 #: ../tools/virt-win-reg.pl:491 ../tools/virt-df.pl:549
3534 #: ../tools/virt-ls.pl:225 ../tools/virt-resize.pl:1420
3535 #: ../tools/virt-list-filesystems.pl:207 ../tools/virt-cat.pl:177
3536 #: ../tools/virt-tar.pl:272 ../tools/virt-rescue.pl:245
3537 #: ../tools/virt-make-fs.pl:556 ../tools/virt-list-partitions.pl:244
3538 msgid "COPYRIGHT"
3539 msgstr ""
3540
3541 # type: textblock
3542 #: ../src/guestfs.pod:1792 ../fish/guestfish.pod:973
3543 msgid "Copyright (C) 2009-2010 Red Hat Inc.  L<http://libguestfs.org/>"
3544 msgstr ""
3545
3546 # type: textblock
3547 #: ../src/guestfs.pod:1795
3548 msgid ""
3549 "This library is free software; you can redistribute it and/or modify it "
3550 "under the terms of the GNU Lesser General Public License as published by the "
3551 "Free Software Foundation; either version 2 of the License, or (at your "
3552 "option) any later version."
3553 msgstr ""
3554
3555 # type: textblock
3556 #: ../src/guestfs.pod:1800
3557 msgid ""
3558 "This library is distributed in the hope that it will be useful, but WITHOUT "
3559 "ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or "
3560 "FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License "
3561 "for more details."
3562 msgstr ""
3563
3564 # type: textblock
3565 #: ../src/guestfs.pod:1805
3566 msgid ""
3567 "You should have received a copy of the GNU Lesser General Public License "
3568 "along with this library; if not, write to the Free Software Foundation, "
3569 "Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA"
3570 msgstr ""
3571
3572 # type: =head2
3573 #: ../src/guestfs-actions.pod:1
3574 msgid "guestfs_add_cdrom"
3575 msgstr ""
3576
3577 # type: verbatim
3578 #: ../src/guestfs-actions.pod:3
3579 #, no-wrap
3580 msgid ""
3581 " int guestfs_add_cdrom (guestfs_h *g,\n"
3582 "\t\tconst char *filename);\n"
3583 "\n"
3584 msgstr ""
3585
3586 # type: textblock
3587 #: ../src/guestfs-actions.pod:6 ../fish/guestfish-actions.pod:7
3588 msgid "This function adds a virtual CD-ROM disk image to the guest."
3589 msgstr ""
3590
3591 # type: textblock
3592 #: ../src/guestfs-actions.pod:8 ../fish/guestfish-actions.pod:9
3593 msgid "This is equivalent to the qemu parameter C<-cdrom filename>."
3594 msgstr ""
3595
3596 # type: textblock
3597 #: ../src/guestfs-actions.pod:10 ../src/guestfs-actions.pod:1516
3598 #: ../fish/guestfish-actions.pod:11 ../fish/guestfish-actions.pod:1211
3599 msgid "Notes:"
3600 msgstr ""
3601
3602 # type: textblock
3603 #: ../src/guestfs-actions.pod:16
3604 msgid ""
3605 "This call checks for the existence of C<filename>.  This stops you from "
3606 "specifying other types of drive which are supported by qemu such as C<nbd:> "
3607 "and C<http:> URLs.  To specify those, use the general C<guestfs_config> call "
3608 "instead."
3609 msgstr ""
3610
3611 # type: textblock
3612 #: ../src/guestfs-actions.pod:23
3613 msgid ""
3614 "If you just want to add an ISO file (often you use this as an efficient way "
3615 "to transfer large files into the guest), then you should probably use "
3616 "C<guestfs_add_drive_ro> instead."
3617 msgstr ""
3618
3619 # type: textblock
3620 #: ../src/guestfs-actions.pod:29 ../src/guestfs-actions.pod:63
3621 #: ../src/guestfs-actions.pod:92 ../src/guestfs-actions.pod:103
3622 #: ../src/guestfs-actions.pod:114 ../src/guestfs-actions.pod:124
3623 #: ../src/guestfs-actions.pod:135 ../src/guestfs-actions.pod:238
3624 #: ../src/guestfs-actions.pod:255 ../src/guestfs-actions.pod:266
3625 #: ../src/guestfs-actions.pod:302 ../src/guestfs-actions.pod:324
3626 #: ../src/guestfs-actions.pod:339 ../src/guestfs-actions.pod:403
3627 #: ../src/guestfs-actions.pod:430 ../src/guestfs-actions.pod:441
3628 #: ../src/guestfs-actions.pod:453 ../src/guestfs-actions.pod:534
3629 #: ../src/guestfs-actions.pod:549 ../src/guestfs-actions.pod:560
3630 #: ../src/guestfs-actions.pod:571 ../src/guestfs-actions.pod:717
3631 #: ../src/guestfs-actions.pod:734 ../src/guestfs-actions.pod:749
3632 #: ../src/guestfs-actions.pod:824 ../src/guestfs-actions.pod:839
3633 #: ../src/guestfs-actions.pod:855 ../src/guestfs-actions.pod:866
3634 #: ../src/guestfs-actions.pod:883 ../src/guestfs-actions.pod:916
3635 #: ../src/guestfs-actions.pod:974 ../src/guestfs-actions.pod:1002
3636 #: ../src/guestfs-actions.pod:1024 ../src/guestfs-actions.pod:1055
3637 #: ../src/guestfs-actions.pod:1143 ../src/guestfs-actions.pod:1174
3638 #: ../src/guestfs-actions.pod:1374 ../src/guestfs-actions.pod:1393
3639 #: ../src/guestfs-actions.pod:1474 ../src/guestfs-actions.pod:1822
3640 #: ../src/guestfs-actions.pod:1945 ../src/guestfs-actions.pod:2000
3641 #: ../src/guestfs-actions.pod:2030 ../src/guestfs-actions.pod:2439
3642 #: ../src/guestfs-actions.pod:2451 ../src/guestfs-actions.pod:2468
3643 #: ../src/guestfs-actions.pod:2576 ../src/guestfs-actions.pod:2587
3644 #: ../src/guestfs-actions.pod:2597 ../src/guestfs-actions.pod:2608
3645 #: ../src/guestfs-actions.pod:2620 ../src/guestfs-actions.pod:2650
3646 #: ../src/guestfs-actions.pod:2714 ../src/guestfs-actions.pod:2731
3647 #: ../src/guestfs-actions.pod:2745 ../src/guestfs-actions.pod:2765
3648 #: ../src/guestfs-actions.pod:2785 ../src/guestfs-actions.pod:2814
3649 #: ../src/guestfs-actions.pod:2830 ../src/guestfs-actions.pod:2846
3650 #: ../src/guestfs-actions.pod:2858 ../src/guestfs-actions.pod:2867
3651 #: ../src/guestfs-actions.pod:2900 ../src/guestfs-actions.pod:2913
3652 #: ../src/guestfs-actions.pod:2923 ../src/guestfs-actions.pod:2935
3653 #: ../src/guestfs-actions.pod:2949 ../src/guestfs-actions.pod:3029
3654 #: ../src/guestfs-actions.pod:3046 ../src/guestfs-actions.pod:3056
3655 #: ../src/guestfs-actions.pod:3101 ../src/guestfs-actions.pod:3116
3656 #: ../src/guestfs-actions.pod:3131 ../src/guestfs-actions.pod:3144
3657 #: ../src/guestfs-actions.pod:3155 ../src/guestfs-actions.pod:3166
3658 #: ../src/guestfs-actions.pod:3180 ../src/guestfs-actions.pod:3192
3659 #: ../src/guestfs-actions.pod:3209 ../src/guestfs-actions.pod:3240
3660 #: ../src/guestfs-actions.pod:3268 ../src/guestfs-actions.pod:3284
3661 #: ../src/guestfs-actions.pod:3300 ../src/guestfs-actions.pod:3309
3662 #: ../src/guestfs-actions.pod:3323 ../src/guestfs-actions.pod:3333
3663 #: ../src/guestfs-actions.pod:3345 ../src/guestfs-actions.pod:3357
3664 #: ../src/guestfs-actions.pod:3389 ../src/guestfs-actions.pod:3401
3665 #: ../src/guestfs-actions.pod:3418 ../src/guestfs-actions.pod:3429
3666 #: ../src/guestfs-actions.pod:3443 ../src/guestfs-actions.pod:3483
3667 #: ../src/guestfs-actions.pod:3514 ../src/guestfs-actions.pod:3525
3668 #: ../src/guestfs-actions.pod:3550 ../src/guestfs-actions.pod:3564
3669 #: ../src/guestfs-actions.pod:3579 ../src/guestfs-actions.pod:3701
3670 #: ../src/guestfs-actions.pod:3753 ../src/guestfs-actions.pod:3772
3671 #: ../src/guestfs-actions.pod:3787 ../src/guestfs-actions.pod:3813
3672 #: ../src/guestfs-actions.pod:3870 ../src/guestfs-actions.pod:3884
3673 #: ../src/guestfs-actions.pod:3894 ../src/guestfs-actions.pod:3905
3674 #: ../src/guestfs-actions.pod:4160 ../src/guestfs-actions.pod:4176
3675 #: ../src/guestfs-actions.pod:4187 ../src/guestfs-actions.pod:4196
3676 #: ../src/guestfs-actions.pod:4207 ../src/guestfs-actions.pod:4216
3677 #: ../src/guestfs-actions.pod:4227 ../src/guestfs-actions.pod:4240
3678 #: ../src/guestfs-actions.pod:4258 ../src/guestfs-actions.pod:4274
3679 #: ../src/guestfs-actions.pod:4290 ../src/guestfs-actions.pod:4305
3680 #: ../src/guestfs-actions.pod:4325 ../src/guestfs-actions.pod:4340
3681 #: ../src/guestfs-actions.pod:4356 ../src/guestfs-actions.pod:4374
3682 #: ../src/guestfs-actions.pod:4390 ../src/guestfs-actions.pod:4404
3683 #: ../src/guestfs-actions.pod:4429 ../src/guestfs-actions.pod:4450
3684 #: ../src/guestfs-actions.pod:4466 ../src/guestfs-actions.pod:4487
3685 #: ../src/guestfs-actions.pod:4499 ../src/guestfs-actions.pod:4511
3686 #: ../src/guestfs-actions.pod:4527 ../src/guestfs-actions.pod:4561
3687 #: ../src/guestfs-actions.pod:4581 ../src/guestfs-actions.pod:4604
3688 #: ../src/guestfs-actions.pod:4694 ../src/guestfs-actions.pod:4800
3689 #: ../src/guestfs-actions.pod:4809 ../src/guestfs-actions.pod:4819
3690 #: ../src/guestfs-actions.pod:4829 ../src/guestfs-actions.pod:4848
3691 #: ../src/guestfs-actions.pod:4858 ../src/guestfs-actions.pod:4868
3692 #: ../src/guestfs-actions.pod:4878 ../src/guestfs-actions.pod:4890
3693 #: ../src/guestfs-actions.pod:4940 ../src/guestfs-actions.pod:4954
3694 #: ../src/guestfs-actions.pod:4967 ../src/guestfs-actions.pod:4980
3695 #: ../src/guestfs-actions.pod:4994 ../src/guestfs-actions.pod:5004
3696 #: ../src/guestfs-actions.pod:5021 ../src/guestfs-actions.pod:5051
3697 #: ../src/guestfs-actions.pod:5062 ../src/guestfs-actions.pod:5097
3698 #: ../src/guestfs-actions.pod:5107 ../src/guestfs-actions.pod:5122
3699 #: ../src/guestfs-actions.pod:5148 ../src/guestfs-actions.pod:5176
3700 #: ../src/guestfs-actions.pod:5280 ../src/guestfs-actions.pod:5295
3701 #: ../src/guestfs-actions.pod:5306 ../src/guestfs-actions.pod:5352
3702 #: ../src/guestfs-actions.pod:5362 ../src/guestfs-actions.pod:5399
3703 #: ../src/guestfs-actions.pod:5426 ../src/guestfs-actions.pod:5468
3704 #: ../src/guestfs-actions.pod:5491 ../src/guestfs-actions.pod:5548
3705 #: ../src/guestfs-actions.pod:5564 ../src/guestfs-actions.pod:5590
3706 msgid "This function returns 0 on success or -1 on error."
3707 msgstr ""
3708
3709 # type: =head2
3710 #: ../src/guestfs-actions.pod:31
3711 msgid "guestfs_add_drive"
3712 msgstr ""
3713
3714 # type: verbatim
3715 #: ../src/guestfs-actions.pod:33
3716 #, no-wrap
3717 msgid ""
3718 " int guestfs_add_drive (guestfs_h *g,\n"
3719 "\t\tconst char *filename);\n"
3720 "\n"
3721 msgstr ""
3722
3723 # type: textblock
3724 #: ../src/guestfs-actions.pod:36 ../fish/guestfish-actions.pod:36
3725 msgid ""
3726 "This function adds a virtual machine disk image C<filename> to the guest.  "
3727 "The first time you call this function, the disk appears as IDE disk 0 (C</"
3728 "dev/sda>) in the guest, the second time as C</dev/sdb>, and so on."
3729 msgstr ""
3730
3731 # type: textblock
3732 #: ../src/guestfs-actions.pod:41 ../fish/guestfish-actions.pod:41
3733 msgid ""
3734 "You don't necessarily need to be root when using libguestfs.  However you "
3735 "obviously do need sufficient permissions to access the filename for whatever "
3736 "operations you want to perform (ie. read access if you just want to read the "
3737 "image or write access if you want to modify the image)."
3738 msgstr ""
3739
3740 # type: textblock
3741 #: ../src/guestfs-actions.pod:47 ../fish/guestfish-actions.pod:47
3742 msgid ""
3743 "This is equivalent to the qemu parameter C<-drive file=filename,cache=off,"
3744 "if=...>."
3745 msgstr ""
3746
3747 # type: textblock
3748 #: ../src/guestfs-actions.pod:50 ../fish/guestfish-actions.pod:50
3749 msgid ""
3750 "C<cache=off> is omitted in cases where it is not supported by the underlying "
3751 "filesystem."
3752 msgstr ""
3753
3754 # type: textblock
3755 #: ../src/guestfs-actions.pod:53 ../src/guestfs-actions.pod:82
3756 msgid ""
3757 "C<if=...> is set at compile time by the configuration option C<./configure --"
3758 "with-drive-if=...>.  In the rare case where you might need to change this at "
3759 "run time, use C<guestfs_add_drive_with_if> or "
3760 "C<guestfs_add_drive_ro_with_if>."
3761 msgstr ""
3762
3763 # type: textblock
3764 #: ../src/guestfs-actions.pod:58 ../src/guestfs-actions.pod:87
3765 msgid ""
3766 "Note that this call checks for the existence of C<filename>.  This stops you "
3767 "from specifying other types of drive which are supported by qemu such as "
3768 "C<nbd:> and C<http:> URLs.  To specify those, use the general "
3769 "C<guestfs_config> call instead."
3770 msgstr ""
3771
3772 # type: =head2
3773 #: ../src/guestfs-actions.pod:65
3774 msgid "guestfs_add_drive_ro"
3775 msgstr ""
3776
3777 # type: verbatim
3778 #: ../src/guestfs-actions.pod:67
3779 #, no-wrap
3780 msgid ""
3781 " int guestfs_add_drive_ro (guestfs_h *g,\n"
3782 "\t\tconst char *filename);\n"
3783 "\n"
3784 msgstr ""
3785
3786 # type: textblock
3787 #: ../src/guestfs-actions.pod:70 ../fish/guestfish-actions.pod:69
3788 msgid "This adds a drive in snapshot mode, making it effectively read-only."
3789 msgstr ""
3790
3791 # type: textblock
3792 #: ../src/guestfs-actions.pod:73 ../fish/guestfish-actions.pod:72
3793 msgid ""
3794 "Note that writes to the device are allowed, and will be seen for the "
3795 "duration of the guestfs handle, but they are written to a temporary file "
3796 "which is discarded as soon as the guestfs handle is closed.  We don't "
3797 "currently have any method to enable changes to be committed, although qemu "
3798 "can support this."
3799 msgstr ""
3800
3801 # type: textblock
3802 #: ../src/guestfs-actions.pod:79 ../fish/guestfish-actions.pod:78
3803 msgid ""
3804 "This is equivalent to the qemu parameter C<-drive file=filename,snapshot=on,"
3805 "if=...>."
3806 msgstr ""
3807
3808 # type: =head2
3809 #: ../src/guestfs-actions.pod:94
3810 msgid "guestfs_add_drive_ro_with_if"
3811 msgstr ""
3812
3813 # type: verbatim
3814 #: ../src/guestfs-actions.pod:96
3815 #, no-wrap
3816 msgid ""
3817 " int guestfs_add_drive_ro_with_if (guestfs_h *g,\n"
3818 "\t\tconst char *filename,\n"
3819 "\t\tconst char *iface);\n"
3820 "\n"
3821 msgstr ""
3822
3823 # type: textblock
3824 #: ../src/guestfs-actions.pod:100
3825 msgid ""
3826 "This is the same as C<guestfs_add_drive_ro> but it allows you to specify the "
3827 "QEMU interface emulation to use at run time."
3828 msgstr ""
3829
3830 # type: =head2
3831 #: ../src/guestfs-actions.pod:105
3832 msgid "guestfs_add_drive_with_if"
3833 msgstr ""
3834
3835 # type: verbatim
3836 #: ../src/guestfs-actions.pod:107
3837 #, no-wrap
3838 msgid ""
3839 " int guestfs_add_drive_with_if (guestfs_h *g,\n"
3840 "\t\tconst char *filename,\n"
3841 "\t\tconst char *iface);\n"
3842 "\n"
3843 msgstr ""
3844
3845 # type: textblock
3846 #: ../src/guestfs-actions.pod:111
3847 msgid ""
3848 "This is the same as C<guestfs_add_drive> but it allows you to specify the "
3849 "QEMU interface emulation to use at run time."
3850 msgstr ""
3851
3852 # type: =head2
3853 #: ../src/guestfs-actions.pod:116
3854 msgid "guestfs_aug_clear"
3855 msgstr ""
3856
3857 # type: verbatim
3858 #: ../src/guestfs-actions.pod:118
3859 #, no-wrap
3860 msgid ""
3861 " int guestfs_aug_clear (guestfs_h *g,\n"
3862 "\t\tconst char *augpath);\n"
3863 "\n"
3864 msgstr ""
3865
3866 # type: textblock
3867 #: ../src/guestfs-actions.pod:121 ../fish/guestfish-actions.pod:109
3868 msgid ""
3869 "Set the value associated with C<path> to C<NULL>.  This is the same as the "
3870 "L<augtool(1)> C<clear> command."
3871 msgstr ""
3872
3873 # type: =head2
3874 #: ../src/guestfs-actions.pod:126
3875 msgid "guestfs_aug_close"
3876 msgstr ""
3877
3878 # type: verbatim
3879 #: ../src/guestfs-actions.pod:128
3880 #, no-wrap
3881 msgid ""
3882 " int guestfs_aug_close (guestfs_h *g);\n"
3883 "\n"
3884 msgstr ""
3885
3886 # type: textblock
3887 #: ../src/guestfs-actions.pod:130
3888 msgid ""
3889 "Close the current Augeas handle and free up any resources used by it.  After "
3890 "calling this, you have to call C<guestfs_aug_init> again before you can use "
3891 "any other Augeas functions."
3892 msgstr ""
3893
3894 # type: =head2
3895 #: ../src/guestfs-actions.pod:137
3896 msgid "guestfs_aug_defnode"
3897 msgstr ""
3898
3899 # type: verbatim
3900 #: ../src/guestfs-actions.pod:139
3901 #, no-wrap
3902 msgid ""
3903 " struct guestfs_int_bool *guestfs_aug_defnode (guestfs_h *g,\n"
3904 "\t\tconst char *name,\n"
3905 "\t\tconst char *expr,\n"
3906 "\t\tconst char *val);\n"
3907 "\n"
3908 msgstr ""
3909
3910 # type: textblock
3911 #: ../src/guestfs-actions.pod:144 ../fish/guestfish-actions.pod:125
3912 msgid ""
3913 "Defines a variable C<name> whose value is the result of evaluating C<expr>."
3914 msgstr ""
3915
3916 # type: textblock
3917 #: ../src/guestfs-actions.pod:147
3918 msgid ""
3919 "If C<expr> evaluates to an empty nodeset, a node is created, equivalent to "
3920 "calling C<guestfs_aug_set> C<expr>, C<value>.  C<name> will be the nodeset "
3921 "containing that single node."
3922 msgstr ""
3923
3924 # type: textblock
3925 #: ../src/guestfs-actions.pod:151 ../fish/guestfish-actions.pod:132
3926 msgid ""
3927 "On success this returns a pair containing the number of nodes in the "
3928 "nodeset, and a boolean flag if a node was created."
3929 msgstr ""
3930
3931 # type: textblock
3932 #: ../src/guestfs-actions.pod:155
3933 msgid ""
3934 "This function returns a C<struct guestfs_int_bool *>, or NULL if there was "
3935 "an error.  I<The caller must call C<guestfs_free_int_bool> after use>."
3936 msgstr ""
3937
3938 # type: =head2
3939 #: ../src/guestfs-actions.pod:159
3940 msgid "guestfs_aug_defvar"
3941 msgstr ""
3942
3943 # type: verbatim
3944 #: ../src/guestfs-actions.pod:161
3945 #, no-wrap
3946 msgid ""
3947 " int guestfs_aug_defvar (guestfs_h *g,\n"
3948 "\t\tconst char *name,\n"
3949 "\t\tconst char *expr);\n"
3950 "\n"
3951 msgstr ""
3952
3953 # type: textblock
3954 #: ../src/guestfs-actions.pod:165 ../fish/guestfish-actions.pod:140
3955 msgid ""
3956 "Defines an Augeas variable C<name> whose value is the result of evaluating "
3957 "C<expr>.  If C<expr> is NULL, then C<name> is undefined."
3958 msgstr ""
3959
3960 # type: textblock
3961 #: ../src/guestfs-actions.pod:169 ../fish/guestfish-actions.pod:144
3962 msgid ""
3963 "On success this returns the number of nodes in C<expr>, or C<0> if C<expr> "
3964 "evaluates to something which is not a nodeset."
3965 msgstr ""
3966
3967 # type: textblock
3968 #: ../src/guestfs-actions.pod:172 ../src/guestfs-actions.pod:313
3969 #: ../src/guestfs-actions.pod:467 ../src/guestfs-actions.pod:492
3970 #: ../src/guestfs-actions.pod:507 ../src/guestfs-actions.pod:523
3971 #: ../src/guestfs-actions.pod:1041 ../src/guestfs-actions.pod:1356
3972 #: ../src/guestfs-actions.pod:1538 ../src/guestfs-actions.pod:1619
3973 #: ../src/guestfs-actions.pod:1650 ../src/guestfs-actions.pod:1693
3974 #: ../src/guestfs-actions.pod:1710 ../src/guestfs-actions.pod:1935
3975 #: ../src/guestfs-actions.pod:2147 ../src/guestfs-actions.pod:2165
3976 #: ../src/guestfs-actions.pod:3503 ../src/guestfs-actions.pod:3610
3977 #: ../src/guestfs-actions.pod:3964 ../src/guestfs-actions.pod:3987
3978 #: ../src/guestfs-actions.pod:5086 ../src/guestfs-actions.pod:5436
3979 #: ../src/guestfs-actions.pod:5446 ../src/guestfs-actions.pod:5456
3980 msgid "On error this function returns -1."
3981 msgstr ""
3982
3983 # type: =head2
3984 #: ../src/guestfs-actions.pod:174
3985 msgid "guestfs_aug_get"
3986 msgstr ""
3987
3988 # type: verbatim
3989 #: ../src/guestfs-actions.pod:176
3990 #, no-wrap
3991 msgid ""
3992 " char *guestfs_aug_get (guestfs_h *g,\n"
3993 "\t\tconst char *augpath);\n"
3994 "\n"
3995 msgstr ""
3996
3997 # type: textblock
3998 #: ../src/guestfs-actions.pod:179 ../fish/guestfish-actions.pod:151
3999 msgid ""
4000 "Look up the value associated with C<path>.  If C<path> matches exactly one "
4001 "node, the C<value> is returned."
4002 msgstr ""
4003
4004 # type: textblock
4005 #: ../src/guestfs-actions.pod:182 ../src/guestfs-actions.pod:610
4006 #: ../src/guestfs-actions.pod:625 ../src/guestfs-actions.pod:682
4007 #: ../src/guestfs-actions.pod:695 ../src/guestfs-actions.pod:786
4008 #: ../src/guestfs-actions.pod:899 ../src/guestfs-actions.pod:928
4009 #: ../src/guestfs-actions.pod:942 ../src/guestfs-actions.pod:958
4010 #: ../src/guestfs-actions.pod:1069 ../src/guestfs-actions.pod:1233
4011 #: ../src/guestfs-actions.pod:1342 ../src/guestfs-actions.pod:1487
4012 #: ../src/guestfs-actions.pod:1501 ../src/guestfs-actions.pod:1577
4013 #: ../src/guestfs-actions.pod:1595 ../src/guestfs-actions.pod:1729
4014 #: ../src/guestfs-actions.pod:1868 ../src/guestfs-actions.pod:2049
4015 #: ../src/guestfs-actions.pod:2099 ../src/guestfs-actions.pod:2215
4016 #: ../src/guestfs-actions.pod:2250 ../src/guestfs-actions.pod:2565
4017 #: ../src/guestfs-actions.pod:2986 ../src/guestfs-actions.pod:3082
4018 #: ../src/guestfs-actions.pod:3625 ../src/guestfs-actions.pod:3801
4019 #: ../src/guestfs-actions.pod:3942 ../src/guestfs-actions.pod:4103
4020 #: ../src/guestfs-actions.pod:4146 ../src/guestfs-actions.pod:4622
4021 #: ../src/guestfs-actions.pod:4635 ../src/guestfs-actions.pod:4649
4022 #: ../src/guestfs-actions.pod:4670 ../src/guestfs-actions.pod:5229
4023 #: ../src/guestfs-actions.pod:5245 ../src/guestfs-actions.pod:5260
4024 #: ../src/guestfs-actions.pod:5408 ../src/guestfs-actions.pod:5638
4025 msgid ""
4026 "This function returns a string, or NULL on error.  I<The caller must free "
4027 "the returned string after use>."
4028 msgstr ""
4029
4030 # type: =head2
4031 #: ../src/guestfs-actions.pod:185
4032 msgid "guestfs_aug_init"
4033 msgstr ""
4034
4035 # type: verbatim
4036 #: ../src/guestfs-actions.pod:187
4037 #, no-wrap
4038 msgid ""
4039 " int guestfs_aug_init (guestfs_h *g,\n"
4040 "\t\tconst char *root,\n"
4041 "\t\tint flags);\n"
4042 "\n"
4043 msgstr ""
4044
4045 # type: textblock
4046 #: ../src/guestfs-actions.pod:191 ../fish/guestfish-actions.pod:158
4047 msgid ""
4048 "Create a new Augeas handle for editing configuration files.  If there was "
4049 "any previous Augeas handle associated with this guestfs session, then it is "
4050 "closed."
4051 msgstr ""
4052
4053 # type: textblock
4054 #: ../src/guestfs-actions.pod:195
4055 msgid "You must call this before using any other C<guestfs_aug_*> commands."
4056 msgstr ""
4057
4058 # type: textblock
4059 #: ../src/guestfs-actions.pod:198 ../fish/guestfish-actions.pod:165
4060 msgid ""
4061 "C<root> is the filesystem root.  C<root> must not be NULL, use C</> instead."
4062 msgstr ""
4063
4064 # type: textblock
4065 #: ../src/guestfs-actions.pod:201 ../fish/guestfish-actions.pod:168
4066 msgid ""
4067 "The flags are the same as the flags defined in E<lt>augeas.hE<gt>, the "
4068 "logical I<or> of the following integers:"
4069 msgstr ""
4070
4071 # type: =item
4072 #: ../src/guestfs-actions.pod:207 ../fish/guestfish-actions.pod:174
4073 msgid "C<AUG_SAVE_BACKUP> = 1"
4074 msgstr ""