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