1guestfs(3) Virtualization Support guestfs(3)
2
6 guestfs - Library for accessing and modifying virtual machine images
7
9 #include <guestfs.h>
10 guestfs_h *g = guestfs_create ();
12 guestfs_add_drive (g, "guest.img");
13 guestfs_launch (g);
14 guestfs_mount (g, "/dev/sda1", "/");
15 guestfs_touch (g, "/hello");
16 guestfs_umount (g, "/");
17 guestfs_close (g);
18 cc prog.c -o prog -lguestfs
20 or:
21 cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
22
24 Libguestfs is a library for accessing and modifying guest disk images.
25 Amongst the things this is good for: making batch configuration changes
26 to guests, getting disk used/free statistics (see also: virt-df),
27 migrating between virtualization systems (see also: virt-p2v),
28 performing partial backups, performing partial guest clones, cloning
29 guests and changing registry/UUID/hostname info, and much else besides.
30 Libguestfs uses Linux kernel and qemu code, and can access any type of
32 guest filesystem that Linux and qemu can, including but not limited to:
33 ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
34 schemes, qcow, qcow2, vmdk.
35 Libguestfs provides ways to enumerate guest storage (eg. partitions,
37 LVs, what filesystem is in each LV, etc.). It can also run commands in
38 the context of the guest. Also you can access filesystems over FUSE.
39 Libguestfs is a library that can be linked with C and C++ management
41 programs (or management programs written in OCaml, Perl, Python, Ruby,
42 Java, PHP, Haskell or C#). You can also use it from shell scripts or
43 the command line.
44 You don't need to be root to use libguestfs, although obviously you do
46 need enough permissions to access the disk images.
47 Libguestfs is a large API because it can do many things. For a gentle
49 introduction, please read the "API OVERVIEW" section next.
50 There are also some example programs in the guestfs-examples(3) manual
52 page.
53
55 This section provides a gentler overview of the libguestfs API. We
56 also try to group API calls together, where that may not be obvious
57 from reading about the individual calls in the main section of this
58 manual.
59 HANDLES
61 Before you can use libguestfs calls, you have to create a handle. Then
62 you must add at least one disk image to the handle, followed by
63 launching the handle, then performing whatever operations you want, and
64 finally closing the handle. By convention we use the single letter "g"
65 for the name of the handle variable, although of course you can use any
66 name you want.
67 The general structure of all libguestfs-using programs looks like this:
69 guestfs_h *g = guestfs_create ();
71 /* Call guestfs_add_drive additional times if there are
73 * multiple disk images.
74 */
75 guestfs_add_drive (g, "guest.img");
76 /* Most manipulation calls won't work until you've launched
78 * the handle 'g'. You have to do this _after_ adding drives
79 * and _before_ other commands.
80 */
81 guestfs_launch (g);
82 /* Now you can examine what partitions, LVs etc are available.
84 */
85 char **partitions = guestfs_list_partitions (g);
86 char **logvols = guestfs_lvs (g);
87 /* To access a filesystem in the image, you must mount it.
89 */
90 guestfs_mount (g, "/dev/sda1", "/");
91 /* Now you can perform filesystem actions on the guest
93 * disk image.
94 */
95 guestfs_touch (g, "/hello");
96 /* This is only needed for libguestfs < 1.5.24. Since then
98 * it is done automatically when you close the handle. See
99 * discussion of autosync in this page.
100 */
101 guestfs_sync (g);
102 /* Close the handle 'g'. */
104 guestfs_close (g);
105 The code above doesn't include any error checking. In real code you
107 should check return values carefully for errors. In general all
108 functions that return integers return "-1" on error, and all functions
109 that return pointers return "NULL" on error. See section "ERROR
110 HANDLING" below for how to handle errors, and consult the documentation
111 for each function call below to see precisely how they return error
112 indications. See guestfs-examples(3) for fully worked examples.
113 DISK IMAGES
115 The image filename ("guest.img" in the example above) could be a disk
116 image from a virtual machine, a dd(1) copy of a physical hard disk, an
117 actual block device, or simply an empty file of zeroes that you have
118 created through posix_fallocate(3). Libguestfs lets you do useful
119 things to all of these.
120 The call you should use in modern code for adding drives is
122 "guestfs_add_drive_opts". To add a disk image, allowing writes, and
123 specifying that the format is raw, do:
124 guestfs_add_drive_opts (g, filename,
126 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
127 -1);
128 You can add a disk read-only using:
130 guestfs_add_drive_opts (g, filename,
132 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
133 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
134 -1);
135 or by calling the older function "guestfs_add_drive_ro". In either
137 case libguestfs won't modify the file.
138 Be extremely cautious if the disk image is in use, eg. if it is being
140 used by a virtual machine. Adding it read-write will almost certainly
141 cause disk corruption, but adding it read-only is safe.
142 You must add at least one disk image, and you may add multiple disk
144 images. In the API, the disk images are usually referred to as
145 "/dev/sda" (for the first one you added), "/dev/sdb" (for the second
146 one you added), etc.
147 Once "guestfs_launch" has been called you cannot add any more images.
149 You can call "guestfs_list_devices" to get a list of the device names,
150 in the order that you added them. See also "BLOCK DEVICE NAMING"
151 below.
152 MOUNTING
154 Before you can read or write files, create directories and so on in a
155 disk image that contains filesystems, you have to mount those
156 filesystems using "guestfs_mount_options" or "guestfs_mount_ro". If
157 you already know that a disk image contains (for example) one partition
158 with a filesystem on that partition, then you can mount it directly:
159 guestfs_mount_options (g, "", "/dev/sda1", "/");
161 where "/dev/sda1" means literally the first partition (1) of the first
163 disk image that we added ("/dev/sda"). If the disk contains Linux LVM2
164 logical volumes you could refer to those instead (eg. "/dev/VG/LV").
165 Note that these are libguestfs virtual devices, and are nothing to do
166 with host devices.
167 If you are given a disk image and you don't know what it contains then
169 you have to find out. Libguestfs can do that too: use
170 "guestfs_list_partitions" and "guestfs_lvs" to list possible partitions
171 and LVs, and either try mounting each to see what is mountable, or else
172 examine them with "guestfs_vfs_type" or "guestfs_file". To list just
173 filesystems, use "guestfs_list_filesystems".
174 Libguestfs also has a set of APIs for inspection of unknown disk images
176 (see "INSPECTION" below). But you might find it easier to look at
177 higher level programs built on top of libguestfs, in particular
178 virt-inspector(1).
179 To mount a filesystem read-only, use "guestfs_mount_ro". There are
181 several other variations of the "guestfs_mount_*" call.
182 FILESYSTEM ACCESS AND MODIFICATION
184 The majority of the libguestfs API consists of fairly low-level calls
185 for accessing and modifying the files, directories, symlinks etc on
186 mounted filesystems. There are over a hundred such calls which you can
187 find listed in detail below in this man page, and we don't even pretend
188 to cover them all in this overview.
189 Specify filenames as full paths, starting with "/" and including the
191 mount point.
192 For example, if you mounted a filesystem at "/" and you want to read
194 the file called "etc/passwd" then you could do:
195 char *data = guestfs_cat (g, "/etc/passwd");
197 This would return "data" as a newly allocated buffer containing the
199 full content of that file (with some conditions: see also "DOWNLOADING"
200 below), or "NULL" if there was an error.
201 As another example, to create a top-level directory on that filesystem
203 called "var" you would do:
204 guestfs_mkdir (g, "/var");
206 To create a symlink you could do:
208 guestfs_ln_s (g, "/etc/init.d/portmap",
210 "/etc/rc3.d/S30portmap");
211 Libguestfs will reject attempts to use relative paths and there is no
213 concept of a current working directory.
214 Libguestfs can return errors in many situations: for example if the
216 filesystem isn't writable, or if a file or directory that you requested
217 doesn't exist. If you are using the C API (documented here) you have
218 to check for those error conditions after each call. (Other language
219 bindings turn these errors into exceptions).
220 File writes are affected by the per-handle umask, set by calling
222 "guestfs_umask" and defaulting to 022. See "UMASK".
223 PARTITIONING
225 Libguestfs contains API calls to read, create and modify partition
226 tables on disk images.
227 In the common case where you want to create a single partition covering
229 the whole disk, you should use the "guestfs_part_disk" call:
230 const char *parttype = "mbr";
232 if (disk_is_larger_than_2TB)
233 parttype = "gpt";
234 guestfs_part_disk (g, "/dev/sda", parttype);
235 Obviously this effectively wipes anything that was on that disk image
237 before.
238 LVM2
240 Libguestfs provides access to a large part of the LVM2 API, such as
241 "guestfs_lvcreate" and "guestfs_vgremove". It won't make much sense
242 unless you familiarize yourself with the concepts of physical volumes,
243 volume groups and logical volumes.
244 This author strongly recommends reading the LVM HOWTO, online at
246 http://tldp.org/HOWTO/LVM-HOWTO/ <http://tldp.org/HOWTO/LVM-HOWTO/>.
247 DOWNLOADING
249 Use "guestfs_cat" to download small, text only files. This call is
250 limited to files which are less than 2 MB and which cannot contain any
251 ASCII NUL ("\0") characters. However the API is very simple to use.
252 "guestfs_read_file" can be used to read files which contain arbitrary 8
254 bit data, since it returns a (pointer, size) pair. However it is still
255 limited to "small" files, less than 2 MB.
256 "guestfs_download" can be used to download any file, with no limits on
258 content or size (even files larger than 4 GB).
259 To download multiple files, see "guestfs_tar_out" and
261 "guestfs_tgz_out".
262 UPLOADING
264 It's often the case that you want to write a file or files to the disk
265 image.
266 To write a small file with fixed content, use "guestfs_write". To
268 create a file of all zeroes, use "guestfs_truncate_size" (sparse) or
269 "guestfs_fallocate64" (with all disk blocks allocated). There are a
270 variety of other functions for creating test files, for example
271 "guestfs_fill" and "guestfs_fill_pattern".
272 To upload a single file, use "guestfs_upload". This call has no limits
274 on file content or size (even files larger than 4 GB).
275 To upload multiple files, see "guestfs_tar_in" and "guestfs_tgz_in".
277 However the fastest way to upload large numbers of arbitrary files is
279 to turn them into a squashfs or CD ISO (see mksquashfs(8) and
280 mkisofs(8)), then attach this using "guestfs_add_drive_ro". If you add
281 the drive in a predictable way (eg. adding it last after all other
282 drives) then you can get the device name from "guestfs_list_devices"
283 and mount it directly using "guestfs_mount_ro". Note that squashfs
284 images are sometimes non-portable between kernel versions, and they
285 don't support labels or UUIDs. If you want to pre-build an image or
286 you need to mount it using a label or UUID, use an ISO image instead.
287 COPYING
289 There are various different commands for copying between files and
290 devices and in and out of the guest filesystem. These are summarised
291 in the table below.
292 file to file
294 Use "guestfs_cp" to copy a single file, or "guestfs_cp_a" to copy
295 directories recursively.
296 file or device to file or device
298 Use "guestfs_dd" which efficiently uses dd(1) to copy between files
299 and devices in the guest.
300 Example: duplicate the contents of an LV:
302 guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy");
304 The destination ("/dev/VG/Copy") must be at least as large as the
306 source ("/dev/VG/Original"). To copy less than the whole source
307 device, use "guestfs_copy_size".
308 file on the host to file or device
310 Use "guestfs_upload". See "UPLOADING" above.
311 file or device to file on the host
313 Use "guestfs_download". See "DOWNLOADING" above.
314 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
316 Calls like "guestfs_upload", "guestfs_download", "guestfs_tar_in",
317 "guestfs_tar_out" etc appear to only take filenames as arguments, so it
318 appears you can only upload and download to files. However many
319 Un*x-like hosts let you use the special device files "/dev/stdin",
320 "/dev/stdout", "/dev/stderr" and "/dev/fd/N" to read and write from
321 stdin, stdout, stderr, and arbitrary file descriptor N.
322 For example, virt-cat(1) writes its output to stdout by doing:
324 guestfs_download (g, filename, "/dev/stdout");
326 and you can write tar output to a pipe "fd" by doing:
328 char devfd[64];
330 snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
331 guestfs_tar_out (g, "/", devfd);
332 LISTING FILES
334 "guestfs_ll" is just designed for humans to read (mainly when using the
335 guestfish(1)-equivalent command "ll").
336 "guestfs_ls" is a quick way to get a list of files in a directory from
338 programs, as a flat list of strings.
339 "guestfs_readdir" is a programmatic way to get a list of files in a
341 directory, plus additional information about each one. It is more
342 equivalent to using the readdir(3) call on a local filesystem.
343 "guestfs_find" and "guestfs_find0" can be used to recursively list
345 files.
346 RUNNING COMMANDS
348 Although libguestfs is primarily an API for manipulating files inside
349 guest images, we also provide some limited facilities for running
350 commands inside guests.
351 There are many limitations to this:
353 · The kernel version that the command runs under will be different
355 from what it expects.
356 · If the command needs to communicate with daemons, then most likely
358 they won't be running.
359 · The command will be running in limited memory.
361 · The network may not be available unless you enable it (see
363 "guestfs_set_network").
364 · Only supports Linux guests (not Windows, BSD, etc).
366 · Architecture limitations (eg. won't work for a PPC guest on an X86
368 host).
369 · For SELinux guests, you may need to enable SELinux and load policy
371 first. See "SELINUX" in this manpage.
372 · Security: It is not safe to run commands from untrusted, possibly
374 malicious guests. These commands may attempt to exploit your
375 program by sending unexpected output. They could also try to
376 exploit the Linux kernel or qemu provided by the libguestfs
377 appliance. They could use the network provided by the libguestfs
378 appliance to bypass ordinary network partitions and firewalls.
379 They could use the elevated privileges or different SELinux context
380 of your program to their advantage.
381 A secure alternative is to use libguestfs to install a "firstboot"
383 script (a script which runs when the guest next boots normally),
384 and to have this script run the commands you want in the normal
385 context of the running guest, network security and so on. For
386 information about other security issues, see "SECURITY".
387 The two main API calls to run commands are "guestfs_command" and
389 "guestfs_sh" (there are also variations).
390 The difference is that "guestfs_sh" runs commands using the shell, so
392 any shell globs, redirections, etc will work.
393 CONFIGURATION FILES
395 To read and write configuration files in Linux guest filesystems, we
396 strongly recommend using Augeas. For example, Augeas understands how
397 to read and write, say, a Linux shadow password file or X.org
398 configuration file, and so avoids you having to write that code.
399 The main Augeas calls are bound through the "guestfs_aug_*" APIs. We
401 don't document Augeas itself here because there is excellent
402 documentation on the <http://augeas.net/> website.
403 If you don't want to use Augeas (you fool!) then try calling
405 "guestfs_read_lines" to get the file as a list of lines which you can
406 iterate over.
407 SELINUX
409 We support SELinux guests. To ensure that labeling happens correctly
410 in SELinux guests, you need to enable SELinux and load the guest's
411 policy:
412 1. Before launching, do:
414 guestfs_set_selinux (g, 1);
416 2. After mounting the guest's filesystem(s), load the policy. This is
418 best done by running the load_policy(8) command in the guest
419 itself:
420 guestfs_sh (g, "/usr/sbin/load_policy");
422 (Older versions of "load_policy" require you to specify the name of
424 the policy file).
425 3. Optionally, set the security context for the API. The correct
427 security context to use can only be known by inspecting the guest.
428 As an example:
429 guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
431 This will work for running commands and editing existing files.
433 When new files are created, you may need to label them explicitly, for
435 example by running the external command "restorecon pathname".
436 UMASK
438 Certain calls are affected by the current file mode creation mask (the
439 "umask"). In particular ones which create files or directories, such
440 as "guestfs_touch", "guestfs_mknod" or "guestfs_mkdir". This affects
441 either the default mode that the file is created with or modifies the
442 mode that you supply.
443 The default umask is 022, so files are created with modes such as 0644
445 and directories with 0755.
446 There are two ways to avoid being affected by umask. Either set umask
448 to 0 (call "guestfs_umask (g, 0)" early after launching). Or call
449 "guestfs_chmod" after creating each file or directory.
450 For more information about umask, see umask(2).
452 ENCRYPTED DISKS
454 Libguestfs allows you to access Linux guests which have been encrypted
455 using whole disk encryption that conforms to the Linux Unified Key
456 Setup (LUKS) standard. This includes nearly all whole disk encryption
457 systems used by modern Linux guests.
458 Use "guestfs_vfs_type" to identify LUKS-encrypted block devices (it
460 returns the string "crypto_LUKS").
461 Then open these devices by calling "guestfs_luks_open". Obviously you
463 will require the passphrase!
464 Opening a LUKS device creates a new device mapper device called
466 "/dev/mapper/mapname" (where "mapname" is the string you supply to
467 "guestfs_luks_open"). Reads and writes to this mapper device are
468 decrypted from and encrypted to the underlying block device
469 respectively.
470 LVM volume groups on the device can be made visible by calling
472 "guestfs_vgscan" followed by "guestfs_vg_activate_all". The logical
473 volume(s) can now be mounted in the usual way.
474 Use the reverse process to close a LUKS device. Unmount any logical
476 volumes on it, deactivate the volume groups by caling
477 "guestfs_vg_activate (g, 0, ["/dev/VG"])". Then close the mapper
478 device by calling "guestfs_luks_close" on the "/dev/mapper/mapname"
479 device (not the underlying encrypted block device).
480 INSPECTION
482 Libguestfs has APIs for inspecting an unknown disk image to find out if
483 it contains operating systems. (These APIs used to be in a separate
484 Perl-only library called Sys::Guestfs::Lib(3) but since version 1.5.3
485 the most frequently used part of this library has been rewritten in C
486 and moved into the core code).
487 Add all disks belonging to the unknown virtual machine and call
489 "guestfs_launch" in the usual way.
490 Then call "guestfs_inspect_os". This function uses other libguestfs
492 calls and certain heuristics, and returns a list of operating systems
493 that were found. An empty list means none were found. A single
494 element is the root filesystem of the operating system. For dual- or
495 multi-boot guests, multiple roots can be returned, each one
496 corresponding to a separate operating system. (Multi-boot virtual
497 machines are extremely rare in the world of virtualization, but since
498 this scenario can happen, we have built libguestfs to deal with it.)
499 For each root, you can then call various "guestfs_inspect_get_*"
501 functions to get additional details about that operating system. For
502 example, call "guestfs_inspect_get_type" to return the string "windows"
503 or "linux" for Windows and Linux-based operating systems respectively.
504 Un*x-like and Linux-based operating systems usually consist of several
506 filesystems which are mounted at boot time (for example, a separate
507 boot partition mounted on "/boot"). The inspection rules are able to
508 detect how filesystems correspond to mount points. Call
509 "guestfs_inspect_get_mountpoints" to get this mapping. It might return
510 a hash table like this example:
511 /boot => /dev/sda1
513 / => /dev/vg_guest/lv_root
514 /usr => /dev/vg_guest/lv_usr
515 The caller can then make calls to "guestfs_mount_options" to mount the
517 filesystems as suggested.
518 Be careful to mount filesystems in the right order (eg. "/" before
520 "/usr"). Sorting the keys of the hash by length, shortest first,
521 should work.
522 Inspection currently only works for some common operating systems.
524 Contributors are welcome to send patches for other operating systems
525 that we currently cannot detect.
526 Encrypted disks must be opened before inspection. See "ENCRYPTED
528 DISKS" for more details. The "guestfs_inspect_os" function just
529 ignores any encrypted devices.
530 A note on the implementation: The call "guestfs_inspect_os" performs
532 inspection and caches the results in the guest handle. Subsequent
533 calls to "guestfs_inspect_get_*" return this cached information, but do
534 not re-read the disks. If you change the content of the guest disks,
535 you can redo inspection by calling "guestfs_inspect_os" again.
536 ("guestfs_inspect_list_applications" works a little differently from
537 the other calls and does read the disks. See documentation for that
538 function for details).
539 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
541 Libguestfs can mount NTFS partitions. It does this using the
542 http://www.ntfs-3g.org/ <http://www.ntfs-3g.org/> driver.
543 DRIVE LETTERS AND PATHS
545 DOS and Windows still use drive letters, and the filesystems are always
547 treated as case insensitive by Windows itself, and therefore you might
548 find a Windows configuration file referring to a path like
549 "c:\windows\system32". When the filesystem is mounted in libguestfs,
550 that directory might be referred to as "/WINDOWS/System32".
551 Drive letter mappings are outside the scope of libguestfs. You have to
553 use libguestfs to read the appropriate Windows Registry and
554 configuration files, to determine yourself how drives are mapped (see
555 also hivex(3) and virt-inspector(1)).
556 Replacing backslash characters with forward slash characters is also
558 outside the scope of libguestfs, but something that you can easily do.
559 Where we can help is in resolving the case insensitivity of paths. For
561 this, call "guestfs_case_sensitive_path".
562 ACCESSING THE WINDOWS REGISTRY
564 Libguestfs also provides some help for decoding Windows Registry "hive"
566 files, through the library "hivex" which is part of the libguestfs
567 project although ships as a separate tarball. You have to locate and
568 download the hive file(s) yourself, and then pass them to "hivex"
569 functions. See also the programs hivexml(1), hivexsh(1),
570 hivexregedit(1) and virt-win-reg(1) for more help on this issue.
571 SYMLINKS ON NTFS-3G FILESYSTEMS
573 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
575 provide something which looks like a Linux symlink. The way it tries
576 to do the rewriting is described here:
577 http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
579 <http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-
580 symbolic-links/>
581 The essential problem is that ntfs-3g simply does not have enough
583 information to do a correct job. NTFS links can contain drive letters
584 and references to external device GUIDs that ntfs-3g has no way of
585 resolving. It is almost certainly the case that libguestfs callers
586 should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
587 NTFS volumes).
588 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
590 "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
591 attribute, and read the raw reparse data from that (you can find the
592 format documented in various places around the web).
593 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
595 There are other useful extended attributes that can be read from
597 ntfs-3g filesystems (using "guestfs_getxattr"). See:
598 http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
600 <http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/>
601 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
603 Although we don't want to discourage you from using the C API, we will
604 mention here that the same API is also available in other languages.
605 The API is broadly identical in all supported languages. This means
607 that the C call "guestfs_add_drive_ro(g,file)" is
608 "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
609 and "g#add_drive_ro file" in OCaml. In other words, a straightforward,
610 predictable isomorphism between each language.
611 Error messages are automatically transformed into exceptions if the
613 language supports it.
614 We don't try to "object orientify" parts of the API in OO languages,
616 although contributors are welcome to write higher level APIs above what
617 we provide in their favourite languages if they wish.
618 C++ You can use the guestfs.h header file from C++ programs. The C++
620 API is identical to the C API. C++ classes and exceptions are not
621 used.
622 C# The C# bindings are highly experimental. Please read the warnings
624 at the top of "csharp/Libguestfs.cs".
625 Haskell
627 This is the only language binding that is working but incomplete.
628 Only calls which return simple integers have been bound in Haskell,
629 and we are looking for help to complete this binding.
630 Java
632 Full documentation is contained in the Javadoc which is distributed
633 with libguestfs.
634 OCaml
636 See guestfs-ocaml(3).
637 Perl
639 See Sys::Guestfs(3).
640 PHP For documentation see "README-PHP" supplied with libguestfs sources
642 or in the php-libguestfs package for your distribution.
643 The PHP binding only works correctly on 64 bit machines.
645 Python
647 See guestfs-python(3).
648 Ruby
650 See guestfs-ruby(3).
651 shell scripts
653 See guestfish(1).
654 LIBGUESTFS GOTCHAS
656 <http://en.wikipedia.org/wiki/Gotcha_(programming)>: "A feature of a
657 system [...] that works in the way it is documented but is
658 counterintuitive and almost invites mistakes."
659 Since we developed libguestfs and the associated tools, there are
661 several things we would have designed differently, but are now stuck
662 with for backwards compatibility or other reasons. If there is ever a
663 libguestfs 2.0 release, you can expect these to change. Beware of
664 them.
665 Autosync / forgetting to sync.
667 When modifying a filesystem from C or another language, you must
668 unmount all filesystems and call "guestfs_sync" explicitly before
669 you close the libguestfs handle. You can also call:
670 guestfs_set_autosync (g, 1);
672 to have the unmount/sync done automatically for you when the handle
674 'g' is closed. (This feature is called "autosync",
675 "guestfs_set_autosync" q.v.)
676 If you forget to do this, then it is entirely possible that your
678 changes won't be written out, or will be partially written, or
679 (very rarely) that you'll get disk corruption.
680 Note that in guestfish(3) autosync is the default. So quick and
682 dirty guestfish scripts that forget to sync will work just fine,
683 which can make this very puzzling if you are trying to debug a
684 problem.
685 Update: Autosync is enabled by default for all API users starting
687 from libguestfs 1.5.24.
688 Mount option "-o sync" should not be the default.
690 If you use "guestfs_mount", then "-o sync,noatime" are added
691 implicitly. However "-o sync" does not add any reliability
692 benefit, but does have a very large performance impact.
693 The work around is to use "guestfs_mount_options" and set the mount
695 options that you actually want to use.
696 Read-only should be the default.
698 In guestfish(3), --ro should be the default, and you should have to
699 specify --rw if you want to make changes to the image.
700 This would reduce the potential to corrupt live VM images.
702 Note that many filesystems change the disk when you just mount and
704 unmount, even if you didn't perform any writes. You need to use
705 "guestfs_add_drive_ro" to guarantee that the disk is not changed.
706 guestfish command line is hard to use.
708 "guestfish disk.img" doesn't do what people expect (open "disk.img"
709 for examination). It tries to run a guestfish command "disk.img"
710 which doesn't exist, so it fails. In earlier versions of guestfish
711 the error message was also unintuitive, but we have corrected this
712 since. Like the Bourne shell, we should have used "guestfish -c
713 command" to run commands.
714 guestfish megabyte modifiers don't work right on all commands
716 In recent guestfish you can use "1M" to mean 1 megabyte (and
717 similarly for other modifiers). What guestfish actually does is to
718 multiply the number part by the modifier part and pass the result
719 to the C API. However this doesn't work for a few APIs which
720 aren't expecting bytes, but are already expecting some other unit
721 (eg. megabytes).
722 The most common is "guestfs_lvcreate". The guestfish command:
724 lvcreate LV VG 100M
726 does not do what you might expect. Instead because
728 "guestfs_lvcreate" is already expecting megabytes, this tries to
729 create a 100 terabyte (100 megabytes * megabytes) logical volume.
730 The error message you get from this is also a little obscure.
731 This could be fixed in the generator by specially marking
733 parameters and return values which take bytes or other units.
734 Ambiguity between devices and paths
736 There is a subtle ambiguity in the API between a device name (eg.
737 "/dev/sdb2") and a similar pathname. A file might just happen to
738 be called "sdb2" in the directory "/dev" (consider some non-Unix VM
739 image).
740 In the current API we usually resolve this ambiguity by having two
742 separate calls, for example "guestfs_checksum" and
743 "guestfs_checksum_device". Some API calls are ambiguous and
744 (incorrectly) resolve the problem by detecting if the path supplied
745 begins with "/dev/".
746 To avoid both the ambiguity and the need to duplicate some calls,
748 we could make paths/devices into structured names. One way to do
749 this would be to use a notation like grub ("hd(0,0)"), although
750 nobody really likes this aspect of grub. Another way would be to
751 use a structured type, equivalent to this OCaml type:
752 type path = Path of string | Device of int | Partition of int * int
754 which would allow you to pass arguments like:
756 Path "/foo/bar"
758 Device 1 (* /dev/sdb, or perhaps /dev/sda *)
759 Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
760 Path "/dev/sdb2" (* not a device *)
761 As you can see there are still problems to resolve even with this
763 representation. Also consider how it might work in guestfish.
764 PROTOCOL LIMITS
766 Internally libguestfs uses a message-based protocol to pass API calls
767 and their responses to and from a small "appliance" (see "INTERNALS"
768 for plenty more detail about this). The maximum message size used by
769 the protocol is slightly less than 4 MB. For some API calls you may
770 need to be aware of this limit. The API calls which may be affected
771 are individually documented, with a link back to this section of the
772 documentation.
773 A simple call such as "guestfs_cat" returns its result (the file data)
775 in a simple string. Because this string is at some point internally
776 encoded as a message, the maximum size that it can return is slightly
777 under 4 MB. If the requested file is larger than this then you will
778 get an error.
779 In order to transfer large files into and out of the guest filesystem,
781 you need to use particular calls that support this. The sections
782 "UPLOADING" and "DOWNLOADING" document how to do this.
783 You might also consider mounting the disk image using our FUSE
785 filesystem support (guestmount(1)).
786 KEYS AND PASSPHRASES
788 Certain libguestfs calls take a parameter that contains sensitive key
789 material, passed in as a C string.
790 In the future we would hope to change the libguestfs implementation so
792 that keys are mlock(2)-ed into physical RAM, and thus can never end up
793 in swap. However this is not done at the moment, because of the
794 complexity of such an implementation.
795 Therefore you should be aware that any key parameter you pass to
797 libguestfs might end up being written out to the swap partition. If
798 this is a concern, scrub the swap partition or don't use libguestfs on
799 encrypted devices.
800 MULTIPLE HANDLES AND MULTIPLE THREADS
802 All high-level libguestfs actions are synchronous. If you want to use
803 libguestfs asynchronously then you must create a thread.
804 Only use the handle from a single thread. Either use the handle
806 exclusively from one thread, or provide your own mutex so that two
807 threads cannot issue calls on the same handle at the same time.
808 See the graphical program guestfs-browser for one possible architecture
810 for multithreaded programs using libvirt and libguestfs.
811 PATH
813 Libguestfs needs a supermin appliance, which it finds by looking along
814 an internal path.
815 By default it looks for these in the directory "$libdir/guestfs" (eg.
817 "/usr/local/lib/guestfs" or "/usr/lib64/guestfs").
818 Use "guestfs_set_path" or set the environment variable
820 "LIBGUESTFS_PATH" to change the directories that libguestfs will search
821 in. The value is a colon-separated list of paths. The current
822 directory is not searched unless the path contains an empty element or
823 ".". For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
824 current directory and then "/usr/lib/guestfs".
825 QEMU WRAPPERS
827 If you want to compile your own qemu, run qemu from a non-standard
828 location, or pass extra arguments to qemu, then you can write a shell-
829 script wrapper around qemu.
830 There is one important rule to remember: you must "exec qemu" as the
832 last command in the shell script (so that qemu replaces the shell and
833 becomes the direct child of the libguestfs-using program). If you
834 don't do this, then the qemu process won't be cleaned up correctly.
835 Here is an example of a wrapper, where I have built my own copy of qemu
837 from source:
838 #!/bin/sh -
840 qemudir=/home/rjones/d/qemu
841 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
842 Save this script as "/tmp/qemu.wrapper" (or wherever), "chmod +x", and
844 then use it by setting the LIBGUESTFS_QEMU environment variable. For
845 example:
846 LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
848 Note that libguestfs also calls qemu with the -help and -version
850 options in order to determine features.
851 ABI GUARANTEE
853 We guarantee the libguestfs ABI (binary interface), for public, high-
854 level actions as outlined in this section. Although we will deprecate
855 some actions, for example if they get replaced by newer calls, we will
856 keep the old actions forever. This allows you the developer to program
857 in confidence against the libguestfs API.
858 BLOCK DEVICE NAMING
860 In the kernel there is now quite a profusion of schemata for naming
861 block devices (in this context, by block device I mean a physical or
862 virtual hard drive). The original Linux IDE driver used names starting
863 with "/dev/hd*". SCSI devices have historically used a different
864 naming scheme, "/dev/sd*". When the Linux kernel libata driver became
865 a popular replacement for the old IDE driver (particularly for SATA
866 devices) those devices also used the "/dev/sd*" scheme. Additionally
867 we now have virtual machines with paravirtualized drivers. This has
868 created several different naming systems, such as "/dev/vd*" for virtio
869 disks and "/dev/xvd*" for Xen PV disks.
870 As discussed above, libguestfs uses a qemu appliance running an
872 embedded Linux kernel to access block devices. We can run a variety of
873 appliances based on a variety of Linux kernels.
874 This causes a problem for libguestfs because many API calls use device
876 or partition names. Working scripts and the recipe (example) scripts
877 that we make available over the internet could fail if the naming
878 scheme changes.
879 Therefore libguestfs defines "/dev/sd*" as the standard naming scheme.
881 Internally "/dev/sd*" names are translated, if necessary, to other
882 names as required. For example, under RHEL 5 which uses the "/dev/hd*"
883 scheme, any device parameter "/dev/sda2" is translated to "/dev/hda2"
884 transparently.
885 Note that this only applies to parameters. The "guestfs_list_devices",
887 "guestfs_list_partitions" and similar calls return the true names of
888 the devices and partitions as known to the appliance.
889 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
891 Usually this translation is transparent. However in some (very rare)
893 cases you may need to know the exact algorithm. Such cases include
894 where you use "guestfs_config" to add a mixture of virtio and IDE
895 devices to the qemu-based appliance, so have a mixture of "/dev/sd*"
896 and "/dev/vd*" devices.
897 The algorithm is applied only to parameters which are known to be
899 either device or partition names. Return values from functions such as
900 "guestfs_list_devices" are never changed.
901 · Is the string a parameter which is a device or partition name?
903 · Does the string begin with "/dev/sd"?
905 · Does the named device exist? If so, we use that device. However
907 if not then we continue with this algorithm.
908 · Replace initial "/dev/sd" string with "/dev/hd".
910 For example, change "/dev/sda2" to "/dev/hda2".
912 If that named device exists, use it. If not, continue.
914 · Replace initial "/dev/sd" string with "/dev/vd".
916 If that named device exists, use it. If not, return an error.
918 PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING
920 Although the standard naming scheme and automatic translation is useful
922 for simple programs and guestfish scripts, for larger programs it is
923 best not to rely on this mechanism.
924 Where possible for maximum future portability programs using libguestfs
926 should use these future-proof techniques:
927 · Use "guestfs_list_devices" or "guestfs_list_partitions" to list
929 actual device names, and then use those names directly.
930 Since those device names exist by definition, they will never be
932 translated.
933 · Use higher level ways to identify filesystems, such as LVM names,
935 UUIDs and filesystem labels.
936
938 This section discusses security implications of using libguestfs,
939 particularly with untrusted or malicious guests or disk images.
940 GENERAL SECURITY CONSIDERATIONS
942 Be careful with any files or data that you download from a guest (by
943 "download" we mean not just the "guestfs_download" command but any
944 command that reads files, filenames, directories or anything else from
945 a disk image). An attacker could manipulate the data to fool your
946 program into doing the wrong thing. Consider cases such as:
947 · the data (file etc) not being present
949 · being present but empty
951 · being much larger than normal
953 · containing arbitrary 8 bit data
955 · being in an unexpected character encoding
957 · containing homoglyphs.
959 SECURITY OF MOUNTING FILESYSTEMS
961 When you mount a filesystem under Linux, mistakes in the kernel
962 filesystem (VFS) module can sometimes be escalated into exploits by
963 deliberately creating a malicious, malformed filesystem. These
964 exploits are very severe for two reasons. Firstly there are very many
965 filesystem drivers in the kernel, and many of them are infrequently
966 used and not much developer attention has been paid to the code. Linux
967 userspace helps potential crackers by detecting the filesystem type and
968 automatically choosing the right VFS driver, even if that filesystem
969 type is obscure or unexpected for the administrator. Secondly, a
970 kernel-level exploit is like a local root exploit (worse in some ways),
971 giving immediate and total access to the system right down to the
972 hardware level.
973 That explains why you should never mount a filesystem from an untrusted
975 guest on your host kernel. How about libguestfs? We run a Linux
976 kernel inside a qemu virtual machine, usually running as a non-root
977 user. The attacker would need to write a filesystem which first
978 exploited the kernel, and then exploited either qemu virtualization
979 (eg. a faulty qemu driver) or the libguestfs protocol, and finally to
980 be as serious as the host kernel exploit it would need to escalate its
981 privileges to root. This multi-step escalation, performed by a static
982 piece of data, is thought to be extremely hard to do, although we never
983 say 'never' about security issues.
984 In any case callers can reduce the attack surface by forcing the
986 filesystem type when mounting (use "guestfs_mount_vfs").
987 PROTOCOL SECURITY
989 The protocol is designed to be secure, being based on RFC 4506 (XDR)
990 with a defined upper message size. However a program that uses
991 libguestfs must also take care - for example you can write a program
992 that downloads a binary from a disk image and executes it locally, and
993 no amount of protocol security will save you from the consequences.
994 INSPECTION SECURITY
996 Parts of the inspection API (see "INSPECTION") return untrusted strings
997 directly from the guest, and these could contain any 8 bit data.
998 Callers should be careful to escape these before printing them to a
999 structured file (for example, use HTML escaping if creating a web
1000 page).
1001 Guest configuration may be altered in unusual ways by the administrator
1003 of the virtual machine, and may not reflect reality (particularly for
1004 untrusted or actively malicious guests). For example we parse the
1005 hostname from configuration files like "/etc/sysconfig/network" that we
1006 find in the guest, but the guest administrator can easily manipulate
1007 these files to provide the wrong hostname.
1008 The inspection API parses guest configuration using two external
1010 libraries: Augeas (Linux configuration) and hivex (Windows Registry).
1011 Both are designed to be robust in the face of malicious data, although
1012 denial of service attacks are still possible, for example with
1013 oversized configuration files.
1014 RUNNING UNTRUSTED GUEST COMMANDS
1016 Be very cautious about running commands from the guest. By running a
1017 command in the guest, you are giving CPU time to a binary that you do
1018 not control, under the same user account as the library, albeit wrapped
1019 in qemu virtualization. More information and alternatives can be found
1020 in the section "RUNNING COMMANDS".
1021 CVE-2010-3851
1023 https://bugzilla.redhat.com/642934
1024 This security bug concerns the automatic disk format detection that
1026 qemu does on disk images.
1027 A raw disk image is just the raw bytes, there is no header. Other disk
1029 images like qcow2 contain a special header. Qemu deals with this by
1030 looking for one of the known headers, and if none is found then
1031 assuming the disk image must be raw.
1032 This allows a guest which has been given a raw disk image to write some
1034 other header. At next boot (or when the disk image is accessed by
1035 libguestfs) qemu would do autodetection and think the disk image format
1036 was, say, qcow2 based on the header written by the guest.
1037 This in itself would not be a problem, but qcow2 offers many features,
1039 one of which is to allow a disk image to refer to another image (called
1040 the "backing disk"). It does this by placing the path to the backing
1041 disk into the qcow2 header. This path is not validated and could point
1042 to any host file (eg. "/etc/passwd"). The backing disk is then exposed
1043 through "holes" in the qcow2 disk image, which of course is completely
1044 under the control of the attacker.
1045 In libguestfs this is rather hard to exploit except under two
1047 circumstances:
1048 1. You have enabled the network or have opened the disk in write mode.
1050 2. You are also running untrusted code from the guest (see "RUNNING
1052 COMMANDS").
1053 The way to avoid this is to specify the expected disk format when
1055 adding disks (the optional "format" option to
1056 "guestfs_add_drive_opts"). You should always do this if the disk is
1057 raw format, and it's a good idea for other cases too.
1058 For disks added from libvirt using calls like "guestfs_add_domain", the
1060 format is fetched from libvirt and passed through.
1061 For libguestfs tools, use the --format command line parameter as
1063 appropriate.
1064
1066 guestfs_h *
1067 "guestfs_h" is the opaque type representing a connection handle.
1068 Create a handle by calling "guestfs_create". Call "guestfs_close" to
1069 free the handle and release all resources used.
1070 For information on using multiple handles and threads, see the section
1072 "MULTIPLE HANDLES AND MULTIPLE THREADS" below.
1073 guestfs_create
1075 guestfs_h *guestfs_create (void);
1076 Create a connection handle.
1078 You have to call "guestfs_add_drive_opts" (or one of the equivalent
1080 calls) on the handle at least once.
1081 This function returns a non-NULL pointer to a handle on success or NULL
1083 on error.
1084 After configuring the handle, you have to call "guestfs_launch".
1086 You may also want to configure error handling for the handle. See
1088 "ERROR HANDLING" section below.
1089 guestfs_close
1091 void guestfs_close (guestfs_h *g);
1092 This closes the connection handle and frees up all resources used.
1094
1096 API functions can return errors. For example, almost all functions
1097 that return "int" will return "-1" to indicate an error.
1098 Additional information is available for errors: an error message string
1100 and optionally an error number (errno) if the thing that failed was a
1101 system call.
1102 You can get at the additional information about the last error on the
1104 handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1105 setting up an error handler with "guestfs_set_error_handler".
1106 When the handle is created, a default error handler is installed which
1108 prints the error message string to "stderr". For small short-running
1109 command line programs it is sufficient to do:
1110 if (guestfs_launch (g) == -1)
1112 exit (EXIT_FAILURE);
1113 since the default error handler will ensure that an error message has
1115 been printed to "stderr" before the program exits.
1116 For other programs the caller will almost certainly want to install an
1118 alternate error handler or do error handling in-line like this:
1119 g = guestfs_create ();
1121 /* This disables the default behaviour of printing errors
1123 on stderr. */
1124 guestfs_set_error_handler (g, NULL, NULL);
1125 if (guestfs_launch (g) == -1) {
1127 /* Examine the error message and print it etc. */
1128 char *msg = guestfs_last_error (g);
1129 int errnum = guestfs_last_errno (g);
1130 fprintf (stderr, "%s\n", msg);
1131 /* ... */
1132 }
1133 Out of memory errors are handled differently. The default action is to
1135 call abort(3). If this is undesirable, then you can set a handler
1136 using "guestfs_set_out_of_memory_handler".
1137 "guestfs_create" returns "NULL" if the handle cannot be created, and
1139 because there is no handle if this happens there is no way to get
1140 additional error information. However "guestfs_create" is supposed to
1141 be a lightweight operation which can only fail because of insufficient
1142 memory (it returns NULL in this case).
1143 guestfs_last_error
1145 const char *guestfs_last_error (guestfs_h *g);
1146 This returns the last error message that happened on "g". If there has
1148 not been an error since the handle was created, then this returns
1149 "NULL".
1150 The lifetime of the returned string is until the next error occurs, or
1152 "guestfs_close" is called.
1153 guestfs_last_errno
1155 int guestfs_last_errno (guestfs_h *g);
1156 This returns the last error number (errno) that happened on "g".
1158 If successful, an errno integer not equal to zero is returned.
1160 If no error, this returns 0. This call can return 0 in three
1162 situations:
1163 1. There has not been any error on the handle.
1165 2. There has been an error but the errno was meaningless. This
1167 corresponds to the case where the error did not come from a failed
1168 system call, but for some other reason.
1169 3. There was an error from a failed system call, but for some reason
1171 the errno was not captured and returned. This usually indicates a
1172 bug in libguestfs.
1173 Libguestfs tries to convert the errno from inside the applicance into a
1175 corresponding errno for the caller (not entirely trivial: the appliance
1176 might be running a completely different operating system from the
1177 library and error numbers are not standardized across Un*xen). If this
1178 could not be done, then the error is translated to "EINVAL". In
1179 practice this should only happen in very rare circumstances.
1180 guestfs_set_error_handler
1182 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1183 void *opaque,
1184 const char *msg);
1185 void guestfs_set_error_handler (guestfs_h *g,
1186 guestfs_error_handler_cb cb,
1187 void *opaque);
1188 The callback "cb" will be called if there is an error. The parameters
1190 passed to the callback are an opaque data pointer and the error message
1191 string.
1192 "errno" is not passed to the callback. To get that the callback must
1194 call "guestfs_last_errno".
1195 Note that the message string "msg" is freed as soon as the callback
1197 function returns, so if you want to stash it somewhere you must make
1198 your own copy.
1199 The default handler prints messages on "stderr".
1201 If you set "cb" to "NULL" then no handler is called.
1203 guestfs_get_error_handler
1205 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1206 void **opaque_rtn);
1207 Returns the current error handler callback.
1209 guestfs_set_out_of_memory_handler
1211 typedef void (*guestfs_abort_cb) (void);
1212 void guestfs_set_out_of_memory_handler (guestfs_h *g,
1213 guestfs_abort_cb);
1214 The callback "cb" will be called if there is an out of memory
1216 situation. Note this callback must not return.
1217 The default is to call abort(3).
1219 You cannot set "cb" to "NULL". You can't ignore out of memory
1221 situations.
1222 guestfs_get_out_of_memory_handler
1224 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1225 This returns the current out of memory handler.
1227
1229 guestfs_add_cdrom
1230 int
1231 guestfs_add_cdrom (guestfs_h *g,
1232 const char *filename);
1233 This function adds a virtual CD-ROM disk image to the guest.
1235 This is equivalent to the qemu parameter "-cdrom filename".
1237 Notes:
1239 · This call checks for the existence of "filename". This stops you
1241 from specifying other types of drive which are supported by qemu
1242 such as "nbd:" and "http:" URLs. To specify those, use the general
1243 "guestfs_config" call instead.
1244 · If you just want to add an ISO file (often you use this as an
1246 efficient way to transfer large files into the guest), then you
1247 should probably use "guestfs_add_drive_ro" instead.
1248 This function returns 0 on success or -1 on error.
1250 This function is deprecated. In new code, use the
1252 "guestfs_add_drive_opts" call instead.
1253 Deprecated functions will not be removed from the API, but the fact
1255 that they are deprecated indicates that there are problems with correct
1256 use of these functions.
1257 (Added in 0.3)
1259 guestfs_add_domain
1261 int
1262 guestfs_add_domain (guestfs_h *g,
1263 const char *dom,
1264 ...);
1265 You may supply a list of optional arguments to this call. Use zero or
1267 more of the following pairs of parameters, and terminate the list with
1268 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
1269 GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
1271 GUESTFS_ADD_DOMAIN_READONLY, int readonly,
1272 GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
1273 This function adds the disk(s) attached to the named libvirt domain
1275 "dom". It works by connecting to libvirt, requesting the domain and
1276 domain XML from libvirt, parsing it for disks, and calling
1277 "guestfs_add_drive_opts" on each one.
1278 The number of disks added is returned. This operation is atomic: if an
1280 error is returned, then no disks are added.
1281 This function does some minimal checks to make sure the libvirt domain
1283 is not running (unless "readonly" is true). In a future version we
1284 will try to acquire the libvirt lock on each disk.
1285 Disks must be accessible locally. This often means that adding disks
1287 from a remote libvirt connection (see <http://libvirt.org/remote.html>)
1288 will fail unless those disks are accessible via the same device path
1289 locally too.
1290 The optional "libvirturi" parameter sets the libvirt URI (see
1292 <http://libvirt.org/uri.html>). If this is not set then we connect to
1293 the default libvirt URI (or one set through an environment variable,
1294 see the libvirt documentation for full details).
1295 The other optional parameters are passed directly through to
1297 "guestfs_add_drive_opts".
1298 On error this function returns -1.
1300 (Added in 1.7.4)
1302 guestfs_add_domain_va
1304 int
1305 guestfs_add_domain_va (guestfs_h *g,
1306 const char *dom,
1307 va_list args);
1308 This is the "va_list variant" of "guestfs_add_domain".
1310 See "CALLS WITH OPTIONAL ARGUMENTS".
1312 guestfs_add_domain_argv
1314 int
1315 guestfs_add_domain_argv (guestfs_h *g,
1316 const char *dom,
1317 const struct guestfs_add_domain_argv *optargs);
1318 This is the "argv variant" of "guestfs_add_domain".
1320 See "CALLS WITH OPTIONAL ARGUMENTS".
1322 guestfs_add_drive
1324 int
1325 guestfs_add_drive (guestfs_h *g,
1326 const char *filename);
1327 This function is the equivalent of calling "guestfs_add_drive_opts"
1329 with no optional parameters, so the disk is added writable, with the
1330 format being detected automatically.
1331 Automatic detection of the format opens you up to a potential security
1333 hole when dealing with untrusted raw-format images. See CVE-2010-3851
1334 and RHBZ#642934. Specifying the format closes this security hole.
1335 Therefore you should think about replacing calls to this function with
1336 calls to "guestfs_add_drive_opts", and specifying the format.
1337 This function returns 0 on success or -1 on error.
1339 (Added in 0.3)
1341 guestfs_add_drive_opts
1343 int
1344 guestfs_add_drive_opts (guestfs_h *g,
1345 const char *filename,
1346 ...);
1347 You may supply a list of optional arguments to this call. Use zero or
1349 more of the following pairs of parameters, and terminate the list with
1350 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
1351 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
1353 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
1354 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
1355 This function adds a virtual machine disk image "filename" to
1357 libguestfs. The first time you call this function, the disk appears as
1358 "/dev/sda", the second time as "/dev/sdb", and so on.
1359 You don't necessarily need to be root when using libguestfs. However
1361 you obviously do need sufficient permissions to access the filename for
1362 whatever operations you want to perform (ie. read access if you just
1363 want to read the image or write access if you want to modify the
1364 image).
1365 This call checks that "filename" exists.
1367 The optional arguments are:
1369 "readonly"
1371 If true then the image is treated as read-only. Writes are still
1372 allowed, but they are stored in a temporary snapshot overlay which
1373 is discarded at the end. The disk that you add is not modified.
1374 "format"
1376 This forces the image format. If you omit this (or use
1377 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
1378 automatically detected. Possible formats include "raw" and
1379 "qcow2".
1380 Automatic detection of the format opens you up to a potential
1382 security hole when dealing with untrusted raw-format images. See
1383 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
1384 security hole.
1385 "iface"
1387 This rarely-used option lets you emulate the behaviour of the
1388 deprecated "guestfs_add_drive_with_if" call (q.v.)
1389 This function returns 0 on success or -1 on error.
1391 (Added in 1.5.23)
1393 guestfs_add_drive_opts_va
1395 int
1396 guestfs_add_drive_opts_va (guestfs_h *g,
1397 const char *filename,
1398 va_list args);
1399 This is the "va_list variant" of "guestfs_add_drive_opts".
1401 See "CALLS WITH OPTIONAL ARGUMENTS".
1403 guestfs_add_drive_opts_argv
1405 int
1406 guestfs_add_drive_opts_argv (guestfs_h *g,
1407 const char *filename,
1408 const struct guestfs_add_drive_opts_argv *optargs);
1409 This is the "argv variant" of "guestfs_add_drive_opts".
1411 See "CALLS WITH OPTIONAL ARGUMENTS".
1413 guestfs_add_drive_ro
1415 int
1416 guestfs_add_drive_ro (guestfs_h *g,
1417 const char *filename);
1418 This function is the equivalent of calling "guestfs_add_drive_opts"
1420 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
1421 so the disk is added read-only, with the format being detected
1422 automatically.
1423 This function returns 0 on success or -1 on error.
1425 (Added in 1.0.38)
1427 guestfs_add_drive_ro_with_if
1429 int
1430 guestfs_add_drive_ro_with_if (guestfs_h *g,
1431 const char *filename,
1432 const char *iface);
1433 This is the same as "guestfs_add_drive_ro" but it allows you to specify
1435 the QEMU interface emulation to use at run time.
1436 This function returns 0 on success or -1 on error.
1438 This function is deprecated. In new code, use the
1440 "guestfs_add_drive_opts" call instead.
1441 Deprecated functions will not be removed from the API, but the fact
1443 that they are deprecated indicates that there are problems with correct
1444 use of these functions.
1445 (Added in 1.0.84)
1447 guestfs_add_drive_with_if
1449 int
1450 guestfs_add_drive_with_if (guestfs_h *g,
1451 const char *filename,
1452 const char *iface);
1453 This is the same as "guestfs_add_drive" but it allows you to specify
1455 the QEMU interface emulation to use at run time.
1456 This function returns 0 on success or -1 on error.
1458 This function is deprecated. In new code, use the
1460 "guestfs_add_drive_opts" call instead.
1461 Deprecated functions will not be removed from the API, but the fact
1463 that they are deprecated indicates that there are problems with correct
1464 use of these functions.
1465 (Added in 1.0.84)
1467 guestfs_aug_clear
1469 int
1470 guestfs_aug_clear (guestfs_h *g,
1471 const char *augpath);
1472 Set the value associated with "path" to "NULL". This is the same as
1474 the augtool(1) "clear" command.
1475 This function returns 0 on success or -1 on error.
1477 (Added in 1.3.4)
1479 guestfs_aug_close
1481 int
1482 guestfs_aug_close (guestfs_h *g);
1483 Close the current Augeas handle and free up any resources used by it.
1485 After calling this, you have to call "guestfs_aug_init" again before
1486 you can use any other Augeas functions.
1487 This function returns 0 on success or -1 on error.
1489 (Added in 0.7)
1491 guestfs_aug_defnode
1493 struct guestfs_int_bool *
1494 guestfs_aug_defnode (guestfs_h *g,
1495 const char *name,
1496 const char *expr,
1497 const char *val);
1498 Defines a variable "name" whose value is the result of evaluating
1500 "expr".
1501 If "expr" evaluates to an empty nodeset, a node is created, equivalent
1503 to calling "guestfs_aug_set" "expr", "value". "name" will be the
1504 nodeset containing that single node.
1505 On success this returns a pair containing the number of nodes in the
1507 nodeset, and a boolean flag if a node was created.
1508 This function returns a "struct guestfs_int_bool *", or NULL if there
1510 was an error. The caller must call "guestfs_free_int_bool" after use.
1511 (Added in 0.7)
1513 guestfs_aug_defvar
1515 int
1516 guestfs_aug_defvar (guestfs_h *g,
1517 const char *name,
1518 const char *expr);
1519 Defines an Augeas variable "name" whose value is the result of
1521 evaluating "expr". If "expr" is NULL, then "name" is undefined.
1522 On success this returns the number of nodes in "expr", or 0 if "expr"
1524 evaluates to something which is not a nodeset.
1525 On error this function returns -1.
1527 (Added in 0.7)
1529 guestfs_aug_get
1531 char *
1532 guestfs_aug_get (guestfs_h *g,
1533 const char *augpath);
1534 Look up the value associated with "path". If "path" matches exactly
1536 one node, the "value" is returned.
1537 This function returns a string, or NULL on error. The caller must free
1539 the returned string after use.
1540 (Added in 0.7)
1542 guestfs_aug_init
1544 int
1545 guestfs_aug_init (guestfs_h *g,
1546 const char *root,
1547 int flags);
1548 Create a new Augeas handle for editing configuration files. If there
1550 was any previous Augeas handle associated with this guestfs session,
1551 then it is closed.
1552 You must call this before using any other "guestfs_aug_*" commands.
1554 "root" is the filesystem root. "root" must not be NULL, use "/"
1556 instead.
1557 The flags are the same as the flags defined in <augeas.h>, the logical
1559 or of the following integers:
1560 "AUG_SAVE_BACKUP" = 1
1562 Keep the original file with a ".augsave" extension.
1563 "AUG_SAVE_NEWFILE" = 2
1565 Save changes into a file with extension ".augnew", and do not
1566 overwrite original. Overrides "AUG_SAVE_BACKUP".
1567 "AUG_TYPE_CHECK" = 4
1569 Typecheck lenses.
1570 This option is only useful when debugging Augeas lenses. Use of
1572 this option may require additional memory for the libguestfs
1573 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
1574 environment variable or call "guestfs_set_memsize".
1575 "AUG_NO_STDINC" = 8
1577 Do not use standard load path for modules.
1578 "AUG_SAVE_NOOP" = 16
1580 Make save a no-op, just record what would have been changed.
1581 "AUG_NO_LOAD" = 32
1583 Do not load the tree in "guestfs_aug_init".
1584 To close the handle, you can call "guestfs_aug_close".
1586 To find out more about Augeas, see <http://augeas.net/>.
1588 This function returns 0 on success or -1 on error.
1590 (Added in 0.7)
1592 guestfs_aug_insert
1594 int
1595 guestfs_aug_insert (guestfs_h *g,
1596 const char *augpath,
1597 const char *label,
1598 int before);
1599 Create a new sibling "label" for "path", inserting it into the tree
1601 before or after "path" (depending on the boolean flag "before").
1602 "path" must match exactly one existing node in the tree, and "label"
1604 must be a label, ie. not contain "/", "*" or end with a bracketed index
1605 "[N]".
1606 This function returns 0 on success or -1 on error.
1608 (Added in 0.7)
1610 guestfs_aug_load
1612 int
1613 guestfs_aug_load (guestfs_h *g);
1614 Load files into the tree.
1616 See "aug_load" in the Augeas documentation for the full gory details.
1618 This function returns 0 on success or -1 on error.
1620 (Added in 0.7)
1622 guestfs_aug_ls
1624 char **
1625 guestfs_aug_ls (guestfs_h *g,
1626 const char *augpath);
1627 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
1629 sorting the resulting nodes into alphabetical order.
1630 This function returns a NULL-terminated array of strings (like
1632 environ(3)), or NULL if there was an error. The caller must free the
1633 strings and the array after use.
1634 (Added in 0.8)
1636 guestfs_aug_match
1638 char **
1639 guestfs_aug_match (guestfs_h *g,
1640 const char *augpath);
1641 Returns a list of paths which match the path expression "path". The
1643 returned paths are sufficiently qualified so that they match exactly
1644 one node in the current tree.
1645 This function returns a NULL-terminated array of strings (like
1647 environ(3)), or NULL if there was an error. The caller must free the
1648 strings and the array after use.
1649 (Added in 0.7)
1651 guestfs_aug_mv
1653 int
1654 guestfs_aug_mv (guestfs_h *g,
1655 const char *src,
1656 const char *dest);
1657 Move the node "src" to "dest". "src" must match exactly one node.
1659 "dest" is overwritten if it exists.
1660 This function returns 0 on success or -1 on error.
1662 (Added in 0.7)
1664 guestfs_aug_rm
1666 int
1667 guestfs_aug_rm (guestfs_h *g,
1668 const char *augpath);
1669 Remove "path" and all of its children.
1671 On success this returns the number of entries which were removed.
1673 On error this function returns -1.
1675 (Added in 0.7)
1677 guestfs_aug_save
1679 int
1680 guestfs_aug_save (guestfs_h *g);
1681 This writes all pending changes to disk.
1683 The flags which were passed to "guestfs_aug_init" affect exactly how
1685 files are saved.
1686 This function returns 0 on success or -1 on error.
1688 (Added in 0.7)
1690 guestfs_aug_set
1692 int
1693 guestfs_aug_set (guestfs_h *g,
1694 const char *augpath,
1695 const char *val);
1696 Set the value associated with "path" to "val".
1698 In the Augeas API, it is possible to clear a node by setting the value
1700 to NULL. Due to an oversight in the libguestfs API you cannot do that
1701 with this call. Instead you must use the "guestfs_aug_clear" call.
1702 This function returns 0 on success or -1 on error.
1704 (Added in 0.7)
1706 guestfs_available
1708 int
1709 guestfs_available (guestfs_h *g,
1710 char *const *groups);
1711 This command is used to check the availability of some groups of
1713 functionality in the appliance, which not all builds of the libguestfs
1714 appliance will be able to provide.
1715 The libguestfs groups, and the functions that those groups correspond
1717 to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch
1718 this list at runtime by calling "guestfs_available_all_groups".
1719 The argument "groups" is a list of group names, eg: "["inotify",
1721 "augeas"]" would check for the availability of the Linux inotify
1722 functions and Augeas (configuration file editing) functions.
1723 The command returns no error if all requested groups are available.
1725 It fails with an error if one or more of the requested groups is
1727 unavailable in the appliance.
1728 If an unknown group name is included in the list of groups then an
1730 error is always returned.
1731 Notes:
1733 · You must call "guestfs_launch" before calling this function.
1735 The reason is because we don't know what groups are supported by
1737 the appliance/daemon until it is running and can be queried.
1738 · If a group of functions is available, this does not necessarily
1740 mean that they will work. You still have to check for errors when
1741 calling individual API functions even if they are available.
1742 · It is usually the job of distro packagers to build complete
1744 functionality into the libguestfs appliance. Upstream libguestfs,
1745 if built from source with all requirements satisfied, will support
1746 everything.
1747 · This call was added in version 1.0.80. In previous versions of
1749 libguestfs all you could do would be to speculatively execute a
1750 command to find out if the daemon implemented it. See also
1751 "guestfs_version".
1752 This function returns 0 on success or -1 on error.
1754 (Added in 1.0.80)
1756 guestfs_available_all_groups
1758 char **
1759 guestfs_available_all_groups (guestfs_h *g);
1760 This command returns a list of all optional groups that this daemon
1762 knows about. Note this returns both supported and unsupported groups.
1763 To find out which ones the daemon can actually support you have to call
1764 "guestfs_available" on each member of the returned list.
1765 See also "guestfs_available" and "AVAILABILITY" in guestfs(3).
1767 This function returns a NULL-terminated array of strings (like
1769 environ(3)), or NULL if there was an error. The caller must free the
1770 strings and the array after use.
1771 (Added in 1.3.15)
1773 guestfs_base64_in
1775 int
1776 guestfs_base64_in (guestfs_h *g,
1777 const char *base64file,
1778 const char *filename);
1779 This command uploads base64-encoded data from "base64file" to
1781 "filename".
1782 This function returns 0 on success or -1 on error.
1784 (Added in 1.3.5)
1786 guestfs_base64_out
1788 int
1789 guestfs_base64_out (guestfs_h *g,
1790 const char *filename,
1791 const char *base64file);
1792 This command downloads the contents of "filename", writing it out to
1794 local file "base64file" encoded as base64.
1795 This function returns 0 on success or -1 on error.
1797 (Added in 1.3.5)
1799 guestfs_blockdev_flushbufs
1801 int
1802 guestfs_blockdev_flushbufs (guestfs_h *g,
1803 const char *device);
1804 This tells the kernel to flush internal buffers associated with
1806 "device".
1807 This uses the blockdev(8) command.
1809 This function returns 0 on success or -1 on error.
1811 (Added in 0.9.3)
1813 guestfs_blockdev_getbsz
1815 int
1816 guestfs_blockdev_getbsz (guestfs_h *g,
1817 const char *device);
1818 This returns the block size of a device.
1820 (Note this is different from both size in blocks and filesystem block
1822 size).
1823 This uses the blockdev(8) command.
1825 On error this function returns -1.
1827 (Added in 0.9.3)
1829 guestfs_blockdev_getro
1831 int
1832 guestfs_blockdev_getro (guestfs_h *g,
1833 const char *device);
1834 Returns a boolean indicating if the block device is read-only (true if
1836 read-only, false if not).
1837 This uses the blockdev(8) command.
1839 This function returns a C truth value on success or -1 on error.
1841 (Added in 0.9.3)
1843 guestfs_blockdev_getsize64
1845 int64_t
1846 guestfs_blockdev_getsize64 (guestfs_h *g,
1847 const char *device);
1848 This returns the size of the device in bytes.
1850 See also "guestfs_blockdev_getsz".
1852 This uses the blockdev(8) command.
1854 On error this function returns -1.
1856 (Added in 0.9.3)
1858 guestfs_blockdev_getss
1860 int
1861 guestfs_blockdev_getss (guestfs_h *g,
1862 const char *device);
1863 This returns the size of sectors on a block device. Usually 512, but
1865 can be larger for modern devices.
1866 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
1868 for that).
1869 This uses the blockdev(8) command.
1871 On error this function returns -1.
1873 (Added in 0.9.3)
1875 guestfs_blockdev_getsz
1877 int64_t
1878 guestfs_blockdev_getsz (guestfs_h *g,
1879 const char *device);
1880 This returns the size of the device in units of 512-byte sectors (even
1882 if the sectorsize isn't 512 bytes ... weird).
1883 See also "guestfs_blockdev_getss" for the real sector size of the
1885 device, and "guestfs_blockdev_getsize64" for the more useful size in
1886 bytes.
1887 This uses the blockdev(8) command.
1889 On error this function returns -1.
1891 (Added in 0.9.3)
1893 guestfs_blockdev_rereadpt
1895 int
1896 guestfs_blockdev_rereadpt (guestfs_h *g,
1897 const char *device);
1898 Reread the partition table on "device".
1900 This uses the blockdev(8) command.
1902 This function returns 0 on success or -1 on error.
1904 (Added in 0.9.3)
1906 guestfs_blockdev_setbsz
1908 int
1909 guestfs_blockdev_setbsz (guestfs_h *g,
1910 const char *device,
1911 int blocksize);
1912 This sets the block size of a device.
1914 (Note this is different from both size in blocks and filesystem block
1916 size).
1917 This uses the blockdev(8) command.
1919 This function returns 0 on success or -1 on error.
1921 (Added in 0.9.3)
1923 guestfs_blockdev_setro
1925 int
1926 guestfs_blockdev_setro (guestfs_h *g,
1927 const char *device);
1928 Sets the block device named "device" to read-only.
1930 This uses the blockdev(8) command.
1932 This function returns 0 on success or -1 on error.
1934 (Added in 0.9.3)
1936 guestfs_blockdev_setrw
1938 int
1939 guestfs_blockdev_setrw (guestfs_h *g,
1940 const char *device);
1941 Sets the block device named "device" to read-write.
1943 This uses the blockdev(8) command.
1945 This function returns 0 on success or -1 on error.
1947 (Added in 0.9.3)
1949 guestfs_case_sensitive_path
1951 char *
1952 guestfs_case_sensitive_path (guestfs_h *g,
1953 const char *path);
1954 This can be used to resolve case insensitive paths on a filesystem
1956 which is case sensitive. The use case is to resolve paths which you
1957 have read from Windows configuration files or the Windows Registry, to
1958 the true path.
1959 The command handles a peculiarity of the Linux ntfs-3g filesystem
1961 driver (and probably others), which is that although the underlying
1962 filesystem is case-insensitive, the driver exports the filesystem to
1963 Linux as case-sensitive.
1964 One consequence of this is that special directories such as
1966 "c:\windows" may appear as "/WINDOWS" or "/windows" (or other things)
1967 depending on the precise details of how they were created. In Windows
1968 itself this would not be a problem.
1969 Bug or feature? You decide:
1971 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
1972 <http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
1973 This function resolves the true case of each element in the path and
1975 returns the case-sensitive path.
1976 Thus "guestfs_case_sensitive_path" ("/Windows/System32") might return
1978 "/WINDOWS/system32" (the exact return value would depend on details of
1979 how the directories were originally created under Windows).
1980 Note: This function does not handle drive names, backslashes etc.
1982 See also "guestfs_realpath".
1984 This function returns a string, or NULL on error. The caller must free
1986 the returned string after use.
1987 (Added in 1.0.75)
1989 guestfs_cat
1991 char *
1992 guestfs_cat (guestfs_h *g,
1993 const char *path);
1994 Return the contents of the file named "path".
1996 Note that this function cannot correctly handle binary files
1998 (specifically, files containing "\0" character which is treated as end
1999 of string). For those you need to use the "guestfs_read_file" or
2000 "guestfs_download" functions which have a more complex interface.
2001 This function returns a string, or NULL on error. The caller must free
2003 the returned string after use.
2004 Because of the message protocol, there is a transfer limit of somewhere
2006 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2007 (Added in 0.4)
2009 guestfs_checksum
2011 char *
2012 guestfs_checksum (guestfs_h *g,
2013 const char *csumtype,
2014 const char *path);
2015 This call computes the MD5, SHAx or CRC checksum of the file named
2017 "path".
2018 The type of checksum to compute is given by the "csumtype" parameter
2020 which must have one of the following values:
2021 "crc"
2023 Compute the cyclic redundancy check (CRC) specified by POSIX for
2024 the "cksum" command.
2025 "md5"
2027 Compute the MD5 hash (using the "md5sum" program).
2028 "sha1"
2030 Compute the SHA1 hash (using the "sha1sum" program).
2031 "sha224"
2033 Compute the SHA224 hash (using the "sha224sum" program).
2034 "sha256"
2036 Compute the SHA256 hash (using the "sha256sum" program).
2037 "sha384"
2039 Compute the SHA384 hash (using the "sha384sum" program).
2040 "sha512"
2042 Compute the SHA512 hash (using the "sha512sum" program).
2043 The checksum is returned as a printable string.
2045 To get the checksum for a device, use "guestfs_checksum_device".
2047 To get the checksums for many files, use "guestfs_checksums_out".
2049 This function returns a string, or NULL on error. The caller must free
2051 the returned string after use.
2052 (Added in 1.0.2)
2054 guestfs_checksum_device
2056 char *
2057 guestfs_checksum_device (guestfs_h *g,
2058 const char *csumtype,
2059 const char *device);
2060 This call computes the MD5, SHAx or CRC checksum of the contents of the
2062 device named "device". For the types of checksums supported see the
2063 "guestfs_checksum" command.
2064 This function returns a string, or NULL on error. The caller must free
2066 the returned string after use.
2067 (Added in 1.3.2)
2069 guestfs_checksums_out
2071 int
2072 guestfs_checksums_out (guestfs_h *g,
2073 const char *csumtype,
2074 const char *directory,
2075 const char *sumsfile);
2076 This command computes the checksums of all regular files in "directory"
2078 and then emits a list of those checksums to the local output file
2079 "sumsfile".
2080 This can be used for verifying the integrity of a virtual machine.
2082 However to be properly secure you should pay attention to the output of
2083 the checksum command (it uses the ones from GNU coreutils). In
2084 particular when the filename is not printable, coreutils uses a special
2085 backslash syntax. For more information, see the GNU coreutils info
2086 file.
2087 This function returns 0 on success or -1 on error.
2089 (Added in 1.3.7)
2091 guestfs_chmod
2093 int
2094 guestfs_chmod (guestfs_h *g,
2095 int mode,
2096 const char *path);
2097 Change the mode (permissions) of "path" to "mode". Only numeric modes
2099 are supported.
2100 Note: When using this command from guestfish, "mode" by default would
2102 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
2103 700.
2104 The mode actually set is affected by the umask.
2106 This function returns 0 on success or -1 on error.
2108 (Added in 0.8)
2110 guestfs_chown
2112 int
2113 guestfs_chown (guestfs_h *g,
2114 int owner,
2115 int group,
2116 const char *path);
2117 Change the file owner to "owner" and group to "group".
2119 Only numeric uid and gid are supported. If you want to use names, you
2121 will need to locate and parse the password file yourself (Augeas
2122 support makes this relatively easy).
2123 This function returns 0 on success or -1 on error.
2125 (Added in 0.8)
2127 guestfs_command
2129 char *
2130 guestfs_command (guestfs_h *g,
2131 char *const *arguments);
2132 This call runs a command from the guest filesystem. The filesystem
2134 must be mounted, and must contain a compatible operating system (ie.
2135 something Linux, with the same or compatible processor architecture).
2136 The single parameter is an argv-style list of arguments. The first
2138 element is the name of the program to run. Subsequent elements are
2139 parameters. The list must be non-empty (ie. must contain a program
2140 name). Note that the command runs directly, and is not invoked via the
2141 shell (see "guestfs_sh").
2142 The return value is anything printed to stdout by the command.
2144 If the command returns a non-zero exit status, then this function
2146 returns an error message. The error message string is the content of
2147 stderr from the command.
2148 The $PATH environment variable will contain at least "/usr/bin" and
2150 "/bin". If you require a program from another location, you should
2151 provide the full path in the first parameter.
2152 Shared libraries and data files required by the program must be
2154 available on filesystems which are mounted in the correct places. It
2155 is the caller's responsibility to ensure all filesystems that are
2156 needed are mounted at the right locations.
2157 This function returns a string, or NULL on error. The caller must free
2159 the returned string after use.
2160 Because of the message protocol, there is a transfer limit of somewhere
2162 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2163 (Added in 0.9.1)
2165 guestfs_command_lines
2167 char **
2168 guestfs_command_lines (guestfs_h *g,
2169 char *const *arguments);
2170 This is the same as "guestfs_command", but splits the result into a
2172 list of lines.
2173 See also: "guestfs_sh_lines"
2175 This function returns a NULL-terminated array of strings (like
2177 environ(3)), or NULL if there was an error. The caller must free the
2178 strings and the array after use.
2179 Because of the message protocol, there is a transfer limit of somewhere
2181 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2182 (Added in 0.9.1)
2184 guestfs_config
2186 int
2187 guestfs_config (guestfs_h *g,
2188 const char *qemuparam,
2189 const char *qemuvalue);
2190 This can be used to add arbitrary qemu command line parameters of the
2192 form "-param value". Actually it's not quite arbitrary - we prevent
2193 you from setting some parameters which would interfere with parameters
2194 that we use.
2195 The first character of "param" string must be a "-" (dash).
2197 "value" can be NULL.
2199 This function returns 0 on success or -1 on error.
2201 (Added in 0.3)
2203 guestfs_copy_size
2205 int
2206 guestfs_copy_size (guestfs_h *g,
2207 const char *src,
2208 const char *dest,
2209 int64_t size);
2210 This command copies exactly "size" bytes from one source device or file
2212 "src" to another destination device or file "dest".
2213 Note this will fail if the source is too short or if the destination is
2215 not large enough.
2216 This function returns 0 on success or -1 on error.
2218 This long-running command can generate progress notification messages
2220 so that the caller can display a progress bar or indicator. To receive
2221 these messages, the caller must register a progress callback. See
2222 "guestfs_set_progress_callback" in guestfs(3).
2223 (Added in 1.0.87)
2225 guestfs_cp
2227 int
2228 guestfs_cp (guestfs_h *g,
2229 const char *src,
2230 const char *dest);
2231 This copies a file from "src" to "dest" where "dest" is either a
2233 destination filename or destination directory.
2234 This function returns 0 on success or -1 on error.
2236 (Added in 1.0.18)
2238 guestfs_cp_a
2240 int
2241 guestfs_cp_a (guestfs_h *g,
2242 const char *src,
2243 const char *dest);
2244 This copies a file or directory from "src" to "dest" recursively using
2246 the "cp -a" command.
2247 This function returns 0 on success or -1 on error.
2249 (Added in 1.0.18)
2251 guestfs_dd
2253 int
2254 guestfs_dd (guestfs_h *g,
2255 const char *src,
2256 const char *dest);
2257 This command copies from one source device or file "src" to another
2259 destination device or file "dest". Normally you would use this to copy
2260 to or from a device or partition, for example to duplicate a
2261 filesystem.
2262 If the destination is a device, it must be as large or larger than the
2264 source file or device, otherwise the copy will fail. This command
2265 cannot do partial copies (see "guestfs_copy_size").
2266 This function returns 0 on success or -1 on error.
2268 (Added in 1.0.80)
2270 guestfs_df
2272 char *
2273 guestfs_df (guestfs_h *g);
2274 This command runs the "df" command to report disk space used.
2276 This command is mostly useful for interactive sessions. It is not
2278 intended that you try to parse the output string. Use
2279 "guestfs_statvfs" from programs.
2280 This function returns a string, or NULL on error. The caller must free
2282 the returned string after use.
2283 (Added in 1.0.54)
2285 guestfs_df_h
2287 char *
2288 guestfs_df_h (guestfs_h *g);
2289 This command runs the "df -h" command to report disk space used in
2291 human-readable format.
2292 This command is mostly useful for interactive sessions. It is not
2294 intended that you try to parse the output string. Use
2295 "guestfs_statvfs" from programs.
2296 This function returns a string, or NULL on error. The caller must free
2298 the returned string after use.
2299 (Added in 1.0.54)
2301 guestfs_dmesg
2303 char *
2304 guestfs_dmesg (guestfs_h *g);
2305 This returns the kernel messages ("dmesg" output) from the guest
2307 kernel. This is sometimes useful for extended debugging of problems.
2308 Another way to get the same information is to enable verbose messages
2310 with "guestfs_set_verbose" or by setting the environment variable
2311 "LIBGUESTFS_DEBUG=1" before running the program.
2312 This function returns a string, or NULL on error. The caller must free
2314 the returned string after use.
2315 (Added in 1.0.18)
2317 guestfs_download
2319 int
2320 guestfs_download (guestfs_h *g,
2321 const char *remotefilename,
2322 const char *filename);
2323 Download file "remotefilename" and save it as "filename" on the local
2325 machine.
2326 "filename" can also be a named pipe.
2328 See also "guestfs_upload", "guestfs_cat".
2330 This function returns 0 on success or -1 on error.
2332 This long-running command can generate progress notification messages
2334 so that the caller can display a progress bar or indicator. To receive
2335 these messages, the caller must register a progress callback. See
2336 "guestfs_set_progress_callback" in guestfs(3).
2337 (Added in 1.0.2)
2339 guestfs_download_offset
2341 int
2342 guestfs_download_offset (guestfs_h *g,
2343 const char *remotefilename,
2344 const char *filename,
2345 int64_t offset,
2346 int64_t size);
2347 Download file "remotefilename" and save it as "filename" on the local
2349 machine.
2350 "remotefilename" is read for "size" bytes starting at "offset" (this
2352 region must be within the file or device).
2353 Note that there is no limit on the amount of data that can be
2355 downloaded with this call, unlike with "guestfs_pread", and this call
2356 always reads the full amount unless an error occurs.
2357 See also "guestfs_download", "guestfs_pread".
2359 This function returns 0 on success or -1 on error.
2361 This long-running command can generate progress notification messages
2363 so that the caller can display a progress bar or indicator. To receive
2364 these messages, the caller must register a progress callback. See
2365 "guestfs_set_progress_callback" in guestfs(3).
2366 (Added in 1.5.17)
2368 guestfs_drop_caches
2370 int
2371 guestfs_drop_caches (guestfs_h *g,
2372 int whattodrop);
2373 This instructs the guest kernel to drop its page cache, and/or dentries
2375 and inode caches. The parameter "whattodrop" tells the kernel what
2376 precisely to drop, see http://linux-mm.org/Drop_Caches <http://linux-
2377 mm.org/Drop_Caches>
2378 Setting "whattodrop" to 3 should drop everything.
2380 This automatically calls sync(2) before the operation, so that the
2382 maximum guest memory is freed.
2383 This function returns 0 on success or -1 on error.
2385 (Added in 1.0.18)
2387 guestfs_du
2389 int64_t
2390 guestfs_du (guestfs_h *g,
2391 const char *path);
2392 This command runs the "du -s" command to estimate file space usage for
2394 "path".
2395 "path" can be a file or a directory. If "path" is a directory then the
2397 estimate includes the contents of the directory and all subdirectories
2398 (recursively).
2399 The result is the estimated size in kilobytes (ie. units of 1024
2401 bytes).
2402 On error this function returns -1.
2404 (Added in 1.0.54)
2406 guestfs_e2fsck_f
2408 int
2409 guestfs_e2fsck_f (guestfs_h *g,
2410 const char *device);
2411 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
2413 checker on "device", noninteractively ("-p"), even if the filesystem
2414 appears to be clean ("-f").
2415 This command is only needed because of "guestfs_resize2fs" (q.v.).
2417 Normally you should use "guestfs_fsck".
2418 This function returns 0 on success or -1 on error.
2420 (Added in 1.0.29)
2422 guestfs_echo_daemon
2424 char *
2425 guestfs_echo_daemon (guestfs_h *g,
2426 char *const *words);
2427 This command concatenates the list of "words" passed with single spaces
2429 between them and returns the resulting string.
2430 You can use this command to test the connection through to the daemon.
2432 See also "guestfs_ping_daemon".
2434 This function returns a string, or NULL on error. The caller must free
2436 the returned string after use.
2437 (Added in 1.0.69)
2439 guestfs_egrep
2441 char **
2442 guestfs_egrep (guestfs_h *g,
2443 const char *regex,
2444 const char *path);
2445 This calls the external "egrep" program and returns the matching lines.
2447 This function returns a NULL-terminated array of strings (like
2449 environ(3)), or NULL if there was an error. The caller must free the
2450 strings and the array after use.
2451 Because of the message protocol, there is a transfer limit of somewhere
2453 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2454 (Added in 1.0.66)
2456 guestfs_egrepi
2458 char **
2459 guestfs_egrepi (guestfs_h *g,
2460 const char *regex,
2461 const char *path);
2462 This calls the external "egrep -i" program and returns the matching
2464 lines.
2465 This function returns a NULL-terminated array of strings (like
2467 environ(3)), or NULL if there was an error. The caller must free the
2468 strings and the array after use.
2469 Because of the message protocol, there is a transfer limit of somewhere
2471 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2472 (Added in 1.0.66)
2474 guestfs_equal
2476 int
2477 guestfs_equal (guestfs_h *g,
2478 const char *file1,
2479 const char *file2);
2480 This compares the two files "file1" and "file2" and returns true if
2482 their content is exactly equal, or false otherwise.
2483 The external cmp(1) program is used for the comparison.
2485 This function returns a C truth value on success or -1 on error.
2487 (Added in 1.0.18)
2489 guestfs_exists
2491 int
2492 guestfs_exists (guestfs_h *g,
2493 const char *path);
2494 This returns "true" if and only if there is a file, directory (or
2496 anything) with the given "path" name.
2497 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
2499 This function returns a C truth value on success or -1 on error.
2501 (Added in 0.8)
2503 guestfs_fallocate
2505 int
2506 guestfs_fallocate (guestfs_h *g,
2507 const char *path,
2508 int len);
2509 This command preallocates a file (containing zero bytes) named "path"
2511 of size "len" bytes. If the file exists already, it is overwritten.
2512 Do not confuse this with the guestfish-specific "alloc" command which
2514 allocates a file in the host and attaches it as a device.
2515 This function returns 0 on success or -1 on error.
2517 This function is deprecated. In new code, use the
2519 "guestfs_fallocate64" call instead.
2520 Deprecated functions will not be removed from the API, but the fact
2522 that they are deprecated indicates that there are problems with correct
2523 use of these functions.
2524 (Added in 1.0.66)
2526 guestfs_fallocate64
2528 int
2529 guestfs_fallocate64 (guestfs_h *g,
2530 const char *path,
2531 int64_t len);
2532 This command preallocates a file (containing zero bytes) named "path"
2534 of size "len" bytes. If the file exists already, it is overwritten.
2535 Note that this call allocates disk blocks for the file. To create a
2537 sparse file use "guestfs_truncate_size" instead.
2538 The deprecated call "guestfs_fallocate" does the same, but owing to an
2540 oversight it only allowed 30 bit lengths to be specified, effectively
2541 limiting the maximum size of files created through that call to 1GB.
2542 Do not confuse this with the guestfish-specific "alloc" and "sparse"
2544 commands which create a file in the host and attach it as a device.
2545 This function returns 0 on success or -1 on error.
2547 (Added in 1.3.17)
2549 guestfs_fgrep
2551 char **
2552 guestfs_fgrep (guestfs_h *g,
2553 const char *pattern,
2554 const char *path);
2555 This calls the external "fgrep" program and returns the matching lines.
2557 This function returns a NULL-terminated array of strings (like
2559 environ(3)), or NULL if there was an error. The caller must free the
2560 strings and the array after use.
2561 Because of the message protocol, there is a transfer limit of somewhere
2563 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2564 (Added in 1.0.66)
2566 guestfs_fgrepi
2568 char **
2569 guestfs_fgrepi (guestfs_h *g,
2570 const char *pattern,
2571 const char *path);
2572 This calls the external "fgrep -i" program and returns the matching
2574 lines.
2575 This function returns a NULL-terminated array of strings (like
2577 environ(3)), or NULL if there was an error. The caller must free the
2578 strings and the array after use.
2579 Because of the message protocol, there is a transfer limit of somewhere
2581 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2582 (Added in 1.0.66)
2584 guestfs_file
2586 char *
2587 guestfs_file (guestfs_h *g,
2588 const char *path);
2589 This call uses the standard file(1) command to determine the type or
2591 contents of the file.
2592 This call will also transparently look inside various types of
2594 compressed file.
2595 The exact command which runs is "file -zb path". Note in particular
2597 that the filename is not prepended to the output (the "-b" option).
2598 The output depends on the output of the underlying file(1) command and
2600 it can change in future in ways beyond our control. In other words,
2601 the output is not guaranteed by the ABI.
2602 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
2604 "guestfs_is_file", "guestfs_is_blockdev" (etc).
2605 This function returns a string, or NULL on error. The caller must free
2607 the returned string after use.
2608 (Added in 0.9.1)
2610 guestfs_file_architecture
2612 char *
2613 guestfs_file_architecture (guestfs_h *g,
2614 const char *filename);
2615 This detects the architecture of the binary "filename", and returns it
2617 if known.
2618 Currently defined architectures are:
2620 "i386"
2622 This string is returned for all 32 bit i386, i486, i586, i686
2623 binaries irrespective of the precise processor requirements of the
2624 binary.
2625 "x86_64"
2627 64 bit x86-64.
2628 "sparc"
2630 32 bit SPARC.
2631 "sparc64"
2633 64 bit SPARC V9 and above.
2634 "ia64"
2636 Intel Itanium.
2637 "ppc"
2639 32 bit Power PC.
2640 "ppc64"
2642 64 bit Power PC.
2643 Libguestfs may return other architecture strings in future.
2645 The function works on at least the following types of files:
2647 · many types of Un*x and Linux binary
2649 · many types of Un*x and Linux shared library
2651 · Windows Win32 and Win64 binaries
2653 · Windows Win32 and Win64 DLLs
2655 Win32 binaries and DLLs return "i386".
2657 Win64 binaries and DLLs return "x86_64".
2659 · Linux kernel modules
2661 · Linux new-style initrd images
2663 · some non-x86 Linux vmlinuz kernels
2665 What it can't do currently:
2667 · static libraries (libfoo.a)
2669 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
2671 · x86 Linux vmlinuz kernels
2673 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
2675 and compressed code, and are horribly hard to unpack. If you want
2676 to find the architecture of a kernel, use the architecture of the
2677 associated initrd or kernel module(s) instead.
2678 This function returns a string, or NULL on error. The caller must free
2680 the returned string after use.
2681 (Added in 1.5.3)
2683 guestfs_filesize
2685 int64_t
2686 guestfs_filesize (guestfs_h *g,
2687 const char *file);
2688 This command returns the size of "file" in bytes.
2690 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
2692 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
2693 devices, use "guestfs_blockdev_getsize64".
2694 On error this function returns -1.
2696 (Added in 1.0.82)
2698 guestfs_fill
2700 int
2701 guestfs_fill (guestfs_h *g,
2702 int c,
2703 int len,
2704 const char *path);
2705 This command creates a new file called "path". The initial content of
2707 the file is "len" octets of "c", where "c" must be a number in the
2708 range "[0..255]".
2709 To fill a file with zero bytes (sparsely), it is much more efficient to
2711 use "guestfs_truncate_size". To create a file with a pattern of
2712 repeating bytes use "guestfs_fill_pattern".
2713 This function returns 0 on success or -1 on error.
2715 This long-running command can generate progress notification messages
2717 so that the caller can display a progress bar or indicator. To receive
2718 these messages, the caller must register a progress callback. See
2719 "guestfs_set_progress_callback" in guestfs(3).
2720 (Added in 1.0.79)
2722 guestfs_fill_pattern
2724 int
2725 guestfs_fill_pattern (guestfs_h *g,
2726 const char *pattern,
2727 int len,
2728 const char *path);
2729 This function is like "guestfs_fill" except that it creates a new file
2731 of length "len" containing the repeating pattern of bytes in "pattern".
2732 The pattern is truncated if necessary to ensure the length of the file
2733 is exactly "len" bytes.
2734 This function returns 0 on success or -1 on error.
2736 This long-running command can generate progress notification messages
2738 so that the caller can display a progress bar or indicator. To receive
2739 these messages, the caller must register a progress callback. See
2740 "guestfs_set_progress_callback" in guestfs(3).
2741 (Added in 1.3.12)
2743 guestfs_find
2745 char **
2746 guestfs_find (guestfs_h *g,
2747 const char *directory);
2748 This command lists out all files and directories, recursively, starting
2750 at "directory". It is essentially equivalent to running the shell
2751 command "find directory -print" but some post-processing happens on the
2752 output, described below.
2753 This returns a list of strings without any prefix. Thus if the
2755 directory structure was:
2756 /tmp/a
2758 /tmp/b
2759 /tmp/c/d
2760 then the returned list from "guestfs_find" "/tmp" would be 4 elements:
2762 a
2764 b
2765 c
2766 c/d
2767 If "directory" is not a directory, then this command returns an error.
2769 The returned list is sorted.
2771 See also "guestfs_find0".
2773 This function returns a NULL-terminated array of strings (like
2775 environ(3)), or NULL if there was an error. The caller must free the
2776 strings and the array after use.
2777 Because of the message protocol, there is a transfer limit of somewhere
2779 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2780 (Added in 1.0.27)
2782 guestfs_find0
2784 int
2785 guestfs_find0 (guestfs_h *g,
2786 const char *directory,
2787 const char *files);
2788 This command lists out all files and directories, recursively, starting
2790 at "directory", placing the resulting list in the external file called
2791 "files".
2792 This command works the same way as "guestfs_find" with the following
2794 exceptions:
2795 · The resulting list is written to an external file.
2797 · Items (filenames) in the result are separated by "\0" characters.
2799 See find(1) option -print0.
2800 · This command is not limited in the number of names that it can
2802 return.
2803 · The result list is not sorted.
2805 This function returns 0 on success or -1 on error.
2807 (Added in 1.0.74)
2809 guestfs_findfs_label
2811 char *
2812 guestfs_findfs_label (guestfs_h *g,
2813 const char *label);
2814 This command searches the filesystems and returns the one which has the
2816 given label. An error is returned if no such filesystem can be found.
2817 To find the label of a filesystem, use "guestfs_vfs_label".
2819 This function returns a string, or NULL on error. The caller must free
2821 the returned string after use.
2822 (Added in 1.5.3)
2824 guestfs_findfs_uuid
2826 char *
2827 guestfs_findfs_uuid (guestfs_h *g,
2828 const char *uuid);
2829 This command searches the filesystems and returns the one which has the
2831 given UUID. An error is returned if no such filesystem can be found.
2832 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
2834 This function returns a string, or NULL on error. The caller must free
2836 the returned string after use.
2837 (Added in 1.5.3)
2839 guestfs_fsck
2841 int
2842 guestfs_fsck (guestfs_h *g,
2843 const char *fstype,
2844 const char *device);
2845 This runs the filesystem checker (fsck) on "device" which should have
2847 filesystem type "fstype".
2848 The returned integer is the status. See fsck(8) for the list of status
2850 codes from "fsck".
2851 Notes:
2853 · Multiple status codes can be summed together.
2855 · A non-zero return code can mean "success", for example if errors
2857 have been corrected on the filesystem.
2858 · Checking or repairing NTFS volumes is not supported (by linux-
2860 ntfs).
2861 This command is entirely equivalent to running "fsck -a -t fstype
2863 device".
2864 On error this function returns -1.
2866 (Added in 1.0.16)
2868 guestfs_get_append
2870 const char *
2871 guestfs_get_append (guestfs_h *g);
2872 Return the additional kernel options which are added to the guest
2874 kernel command line.
2875 If "NULL" then no options are added.
2877 This function returns a string which may be NULL. There is no way to
2879 return an error from this function. The string is owned by the guest
2880 handle and must not be freed.
2881 (Added in 1.0.26)
2883 guestfs_get_autosync
2885 int
2886 guestfs_get_autosync (guestfs_h *g);
2887 Get the autosync flag.
2889 This function returns a C truth value on success or -1 on error.
2891 (Added in 0.3)
2893 guestfs_get_direct
2895 int
2896 guestfs_get_direct (guestfs_h *g);
2897 Return the direct appliance mode flag.
2899 This function returns a C truth value on success or -1 on error.
2901 (Added in 1.0.72)
2903 guestfs_get_e2label
2905 char *
2906 guestfs_get_e2label (guestfs_h *g,
2907 const char *device);
2908 This returns the ext2/3/4 filesystem label of the filesystem on
2910 "device".
2911 This function returns a string, or NULL on error. The caller must free
2913 the returned string after use.
2914 This function is deprecated. In new code, use the "guestfs_vfs_label"
2916 call instead.
2917 Deprecated functions will not be removed from the API, but the fact
2919 that they are deprecated indicates that there are problems with correct
2920 use of these functions.
2921 (Added in 1.0.15)
2923 guestfs_get_e2uuid
2925 char *
2926 guestfs_get_e2uuid (guestfs_h *g,
2927 const char *device);
2928 This returns the ext2/3/4 filesystem UUID of the filesystem on
2930 "device".
2931 This function returns a string, or NULL on error. The caller must free
2933 the returned string after use.
2934 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
2936 call instead.
2937 Deprecated functions will not be removed from the API, but the fact
2939 that they are deprecated indicates that there are problems with correct
2940 use of these functions.
2941 (Added in 1.0.15)
2943 guestfs_get_memsize
2945 int
2946 guestfs_get_memsize (guestfs_h *g);
2947 This gets the memory size in megabytes allocated to the qemu
2949 subprocess.
2950 If "guestfs_set_memsize" was not called on this handle, and if
2952 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
2953 default value for memsize.
2954 For more information on the architecture of libguestfs, see guestfs(3).
2956 On error this function returns -1.
2958 (Added in 1.0.55)
2960 guestfs_get_network
2962 int
2963 guestfs_get_network (guestfs_h *g);
2964 This returns the enable network flag.
2966 This function returns a C truth value on success or -1 on error.
2968 (Added in 1.5.4)
2970 guestfs_get_path
2972 const char *
2973 guestfs_get_path (guestfs_h *g);
2974 Return the current search path.
2976 This is always non-NULL. If it wasn't set already, then this will
2978 return the default path.
2979 This function returns a string, or NULL on error. The string is owned
2981 by the guest handle and must not be freed.
2982 (Added in 0.3)
2984 guestfs_get_pid
2986 int
2987 guestfs_get_pid (guestfs_h *g);
2988 Return the process ID of the qemu subprocess. If there is no qemu
2990 subprocess, then this will return an error.
2991 This is an internal call used for debugging and testing.
2993 On error this function returns -1.
2995 (Added in 1.0.56)
2997 guestfs_get_qemu
2999 const char *
3000 guestfs_get_qemu (guestfs_h *g);
3001 Return the current qemu binary.
3003 This is always non-NULL. If it wasn't set already, then this will
3005 return the default qemu binary name.
3006 This function returns a string, or NULL on error. The string is owned
3008 by the guest handle and must not be freed.
3009 (Added in 1.0.6)
3011 guestfs_get_recovery_proc
3013 int
3014 guestfs_get_recovery_proc (guestfs_h *g);
3015 Return the recovery process enabled flag.
3017 This function returns a C truth value on success or -1 on error.
3019 (Added in 1.0.77)
3021 guestfs_get_selinux
3023 int
3024 guestfs_get_selinux (guestfs_h *g);
3025 This returns the current setting of the selinux flag which is passed to
3027 the appliance at boot time. See "guestfs_set_selinux".
3028 For more information on the architecture of libguestfs, see guestfs(3).
3030 This function returns a C truth value on success or -1 on error.
3032 (Added in 1.0.67)
3034 guestfs_get_state
3036 int
3037 guestfs_get_state (guestfs_h *g);
3038 This returns the current state as an opaque integer. This is only
3040 useful for printing debug and internal error messages.
3041 For more information on states, see guestfs(3).
3043 On error this function returns -1.
3045 (Added in 1.0.2)
3047 guestfs_get_trace
3049 int
3050 guestfs_get_trace (guestfs_h *g);
3051 Return the command trace flag.
3053 This function returns a C truth value on success or -1 on error.
3055 (Added in 1.0.69)
3057 guestfs_get_umask
3059 int
3060 guestfs_get_umask (guestfs_h *g);
3061 Return the current umask. By default the umask is 022 unless it has
3063 been set by calling "guestfs_umask".
3064 On error this function returns -1.
3066 (Added in 1.3.4)
3068 guestfs_get_verbose
3070 int
3071 guestfs_get_verbose (guestfs_h *g);
3072 This returns the verbose messages flag.
3074 This function returns a C truth value on success or -1 on error.
3076 (Added in 0.3)
3078 guestfs_getcon
3080 char *
3081 guestfs_getcon (guestfs_h *g);
3082 This gets the SELinux security context of the daemon.
3084 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
3086 This function returns a string, or NULL on error. The caller must free
3088 the returned string after use.
3089 (Added in 1.0.67)
3091 guestfs_getxattr
3093 char *
3094 guestfs_getxattr (guestfs_h *g,
3095 const char *path,
3096 const char *name,
3097 size_t *size_r);
3098 Get a single extended attribute from file "path" named "name". This
3100 call follows symlinks. If you want to lookup an extended attribute for
3101 the symlink itself, use "guestfs_lgetxattr".
3102 Normally it is better to get all extended attributes from a file in one
3104 go by calling "guestfs_getxattrs". However some Linux filesystem
3105 implementations are buggy and do not provide a way to list out
3106 attributes. For these filesystems (notably ntfs-3g) you have to know
3107 the names of the extended attributes you want in advance and call this
3108 function.
3109 Extended attribute values are blobs of binary data. If there is no
3111 extended attribute named "name", this returns an error.
3112 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
3114 This function returns a buffer, or NULL on error. The size of the
3116 returned buffer is written to *size_r. The caller must free the
3117 returned buffer after use.
3118 (Added in 1.7.24)
3120 guestfs_getxattrs
3122 struct guestfs_xattr_list *
3123 guestfs_getxattrs (guestfs_h *g,
3124 const char *path);
3125 This call lists the extended attributes of the file or directory
3127 "path".
3128 At the system call level, this is a combination of the listxattr(2) and
3130 getxattr(2) calls.
3131 See also: "guestfs_lgetxattrs", attr(5).
3133 This function returns a "struct guestfs_xattr_list *", or NULL if there
3135 was an error. The caller must call "guestfs_free_xattr_list" after
3136 use.
3137 (Added in 1.0.59)
3139 guestfs_glob_expand
3141 char **
3142 guestfs_glob_expand (guestfs_h *g,
3143 const char *pattern);
3144 This command searches for all the pathnames matching "pattern"
3146 according to the wildcard expansion rules used by the shell.
3147 If no paths match, then this returns an empty list (note: not an
3149 error).
3150 It is just a wrapper around the C glob(3) function with flags
3152 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
3153 This function returns a NULL-terminated array of strings (like
3155 environ(3)), or NULL if there was an error. The caller must free the
3156 strings and the array after use.
3157 (Added in 1.0.50)
3159 guestfs_grep
3161 char **
3162 guestfs_grep (guestfs_h *g,
3163 const char *regex,
3164 const char *path);
3165 This calls the external "grep" program and returns the matching lines.
3167 This function returns a NULL-terminated array of strings (like
3169 environ(3)), or NULL if there was an error. The caller must free the
3170 strings and the array after use.
3171 Because of the message protocol, there is a transfer limit of somewhere
3173 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3174 (Added in 1.0.66)
3176 guestfs_grepi
3178 char **
3179 guestfs_grepi (guestfs_h *g,
3180 const char *regex,
3181 const char *path);
3182 This calls the external "grep -i" program and returns the matching
3184 lines.
3185 This function returns a NULL-terminated array of strings (like
3187 environ(3)), or NULL if there was an error. The caller must free the
3188 strings and the array after use.
3189 Because of the message protocol, there is a transfer limit of somewhere
3191 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3192 (Added in 1.0.66)
3194 guestfs_grub_install
3196 int
3197 guestfs_grub_install (guestfs_h *g,
3198 const char *root,
3199 const char *device);
3200 This command installs GRUB 1 (the Grand Unified Bootloader) on
3202 "device", with the root directory being "root".
3203 Notes:
3205 · There is currently no way in the API to install grub2, which is
3207 used by most modern Linux guests. It is possible to run the grub2
3208 command from the guest, although see the caveats in "RUNNING
3209 COMMANDS" in guestfs(3).
3210 · This uses "grub-install" from the host. Unfortunately grub is not
3212 always compatible with itself, so this only works in rather narrow
3213 circumstances. Careful testing with each guest version is
3214 advisable.
3215 · If grub-install reports the error "No suitable drive was found in
3217 the generated device map." it may be that you need to create a
3218 "/boot/grub/device.map" file first that contains the mapping
3219 between grub device names and Linux device names. It is usually
3220 sufficient to create a file containing:
3221 (hd0) /dev/vda
3223 replacing "/dev/vda" with the name of the installation device.
3225 This function returns 0 on success or -1 on error.
3227 (Added in 1.0.17)
3229 guestfs_head
3231 char **
3232 guestfs_head (guestfs_h *g,
3233 const char *path);
3234 This command returns up to the first 10 lines of a file as a list of
3236 strings.
3237 This function returns a NULL-terminated array of strings (like
3239 environ(3)), or NULL if there was an error. The caller must free the
3240 strings and the array after use.
3241 Because of the message protocol, there is a transfer limit of somewhere
3243 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3244 (Added in 1.0.54)
3246 guestfs_head_n
3248 char **
3249 guestfs_head_n (guestfs_h *g,
3250 int nrlines,
3251 const char *path);
3252 If the parameter "nrlines" is a positive number, this returns the first
3254 "nrlines" lines of the file "path".
3255 If the parameter "nrlines" is a negative number, this returns lines
3257 from the file "path", excluding the last "nrlines" lines.
3258 If the parameter "nrlines" is zero, this returns an empty list.
3260 This function returns a NULL-terminated array of strings (like
3262 environ(3)), or NULL if there was an error. The caller must free the
3263 strings and the array after use.
3264 Because of the message protocol, there is a transfer limit of somewhere
3266 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3267 (Added in 1.0.54)
3269 guestfs_hexdump
3271 char *
3272 guestfs_hexdump (guestfs_h *g,
3273 const char *path);
3274 This runs "hexdump -C" on the given "path". The result is the human-
3276 readable, canonical hex dump of the file.
3277 This function returns a string, or NULL on error. The caller must free
3279 the returned string after use.
3280 Because of the message protocol, there is a transfer limit of somewhere
3282 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3283 (Added in 1.0.22)
3285 guestfs_initrd_cat
3287 char *
3288 guestfs_initrd_cat (guestfs_h *g,
3289 const char *initrdpath,
3290 const char *filename,
3291 size_t *size_r);
3292 This command unpacks the file "filename" from the initrd file called
3294 "initrdpath". The filename must be given without the initial "/"
3295 character.
3296 For example, in guestfish you could use the following command to
3298 examine the boot script (usually called "/init") contained in a Linux
3299 initrd or initramfs image:
3300 initrd-cat /boot/initrd-<version>.img init
3302 See also "guestfs_initrd_list".
3304 This function returns a buffer, or NULL on error. The size of the
3306 returned buffer is written to *size_r. The caller must free the
3307 returned buffer after use.
3308 Because of the message protocol, there is a transfer limit of somewhere
3310 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3311 (Added in 1.0.84)
3313 guestfs_initrd_list
3315 char **
3316 guestfs_initrd_list (guestfs_h *g,
3317 const char *path);
3318 This command lists out files contained in an initrd.
3320 The files are listed without any initial "/" character. The files are
3322 listed in the order they appear (not necessarily alphabetical).
3323 Directory names are listed as separate items.
3324 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
3326 as initrd. We only support the newer initramfs format (compressed cpio
3327 files).
3328 This function returns a NULL-terminated array of strings (like
3330 environ(3)), or NULL if there was an error. The caller must free the
3331 strings and the array after use.
3332 (Added in 1.0.54)
3334 guestfs_inotify_add_watch
3336 int64_t
3337 guestfs_inotify_add_watch (guestfs_h *g,
3338 const char *path,
3339 int mask);
3340 Watch "path" for the events listed in "mask".
3342 Note that if "path" is a directory then events within that directory
3344 are watched, but this does not happen recursively (in subdirectories).
3345 Note for non-C or non-Linux callers: the inotify events are defined by
3347 the Linux kernel ABI and are listed in "/usr/include/sys/inotify.h".
3348 On error this function returns -1.
3350 (Added in 1.0.66)
3352 guestfs_inotify_close
3354 int
3355 guestfs_inotify_close (guestfs_h *g);
3356 This closes the inotify handle which was previously opened by
3358 inotify_init. It removes all watches, throws away any pending events,
3359 and deallocates all resources.
3360 This function returns 0 on success or -1 on error.
3362 (Added in 1.0.66)
3364 guestfs_inotify_files
3366 char **
3367 guestfs_inotify_files (guestfs_h *g);
3368 This function is a helpful wrapper around "guestfs_inotify_read" which
3370 just returns a list of pathnames of objects that were touched. The
3371 returned pathnames are sorted and deduplicated.
3372 This function returns a NULL-terminated array of strings (like
3374 environ(3)), or NULL if there was an error. The caller must free the
3375 strings and the array after use.
3376 (Added in 1.0.66)
3378 guestfs_inotify_init
3380 int
3381 guestfs_inotify_init (guestfs_h *g,
3382 int maxevents);
3383 This command creates a new inotify handle. The inotify subsystem can
3385 be used to notify events which happen to objects in the guest
3386 filesystem.
3387 "maxevents" is the maximum number of events which will be queued up
3389 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
3390 this is passed as 0, then the kernel (or previously set) default is
3391 used. For Linux 2.6.29 the default was 16384 events. Beyond this
3392 limit, the kernel throws away events, but records the fact that it
3393 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
3394 structure list (see "guestfs_inotify_read").
3395 Before any events are generated, you have to add some watches to the
3397 internal watch list. See: "guestfs_inotify_add_watch",
3398 "guestfs_inotify_rm_watch" and "guestfs_inotify_watch_all".
3399 Queued up events should be read periodically by calling
3401 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
3402 helpful wrapper around "guestfs_inotify_read"). If you don't read the
3403 events out often enough then you risk the internal queue overflowing.
3404 The handle should be closed after use by calling
3406 "guestfs_inotify_close". This also removes any watches automatically.
3407 See also inotify(7) for an overview of the inotify interface as exposed
3409 by the Linux kernel, which is roughly what we expose via libguestfs.
3410 Note that there is one global inotify handle per libguestfs instance.
3411 This function returns 0 on success or -1 on error.
3413 (Added in 1.0.66)
3415 guestfs_inotify_read
3417 struct guestfs_inotify_event_list *
3418 guestfs_inotify_read (guestfs_h *g);
3419 Return the complete queue of events that have happened since the
3421 previous read call.
3422 If no events have happened, this returns an empty list.
3424 Note: In order to make sure that all events have been read, you must
3426 call this function repeatedly until it returns an empty list. The
3427 reason is that the call will read events up to the maximum appliance-
3428 to-host message size and leave remaining events in the queue.
3429 This function returns a "struct guestfs_inotify_event_list *", or NULL
3431 if there was an error. The caller must call
3432 "guestfs_free_inotify_event_list" after use.
3433 (Added in 1.0.66)
3435 guestfs_inotify_rm_watch
3437 int
3438 guestfs_inotify_rm_watch (guestfs_h *g,
3439 int wd);
3440 Remove a previously defined inotify watch. See
3442 "guestfs_inotify_add_watch".
3443 This function returns 0 on success or -1 on error.
3445 (Added in 1.0.66)
3447 guestfs_inspect_get_arch
3449 char *
3450 guestfs_inspect_get_arch (guestfs_h *g,
3451 const char *root);
3452 This function should only be called with a root device string as
3454 returned by "guestfs_inspect_os".
3455 This returns the architecture of the inspected operating system. The
3457 possible return values are listed under "guestfs_file_architecture".
3458 If the architecture could not be determined, then the string "unknown"
3460 is returned.
3461 Please read "INSPECTION" in guestfs(3) for more details.
3463 This function returns a string, or NULL on error. The caller must free
3465 the returned string after use.
3466 (Added in 1.5.3)
3468 guestfs_inspect_get_distro
3470 char *
3471 guestfs_inspect_get_distro (guestfs_h *g,
3472 const char *root);
3473 This function should only be called with a root device string as
3475 returned by "guestfs_inspect_os".
3476 This returns the distro (distribution) of the inspected operating
3478 system.
3479 Currently defined distros are:
3481 "archlinux"
3483 Arch Linux.
3484 "debian"
3486 Debian.
3487 "fedora"
3489 Fedora.
3490 "gentoo"
3492 Gentoo.
3493 "linuxmint"
3495 Linux Mint.
3496 "mandriva"
3498 Mandriva.
3499 "meego"
3501 MeeGo.
3502 "pardus"
3504 Pardus.
3505 "redhat-based"
3507 Some Red Hat-derived distro.
3508 "rhel"
3510 Red Hat Enterprise Linux and some derivatives.
3511 "ubuntu"
3513 Ubuntu.
3514 "unknown"
3516 The distro could not be determined.
3517 "windows"
3519 Windows does not have distributions. This string is returned if
3520 the OS type is Windows.
3521 Future versions of libguestfs may return other strings here. The
3523 caller should be prepared to handle any string.
3524 Please read "INSPECTION" in guestfs(3) for more details.
3526 This function returns a string, or NULL on error. The caller must free
3528 the returned string after use.
3529 (Added in 1.5.3)
3531 guestfs_inspect_get_filesystems
3533 char **
3534 guestfs_inspect_get_filesystems (guestfs_h *g,
3535 const char *root);
3536 This function should only be called with a root device string as
3538 returned by "guestfs_inspect_os".
3539 This returns a list of all the filesystems that we think are associated
3541 with this operating system. This includes the root filesystem, other
3542 ordinary filesystems, and non-mounted devices like swap partitions.
3543 In the case of a multi-boot virtual machine, it is possible for a
3545 filesystem to be shared between operating systems.
3546 Please read "INSPECTION" in guestfs(3) for more details. See also
3548 "guestfs_inspect_get_mountpoints".
3549 This function returns a NULL-terminated array of strings (like
3551 environ(3)), or NULL if there was an error. The caller must free the
3552 strings and the array after use.
3553 (Added in 1.5.3)
3555 guestfs_inspect_get_hostname
3557 char *
3558 guestfs_inspect_get_hostname (guestfs_h *g,
3559 const char *root);
3560 This function should only be called with a root device string as
3562 returned by "guestfs_inspect_os".
3563 This function returns the hostname of the operating system as found by
3565 inspection of the guest's configuration files.
3566 If the hostname could not be determined, then the string "unknown" is
3568 returned.
3569 Please read "INSPECTION" in guestfs(3) for more details.
3571 This function returns a string, or NULL on error. The caller must free
3573 the returned string after use.
3574 (Added in 1.7.9)
3576 guestfs_inspect_get_major_version
3578 int
3579 guestfs_inspect_get_major_version (guestfs_h *g,
3580 const char *root);
3581 This function should only be called with a root device string as
3583 returned by "guestfs_inspect_os".
3584 This returns the major version number of the inspected operating
3586 system.
3587 Windows uses a consistent versioning scheme which is not reflected in
3589 the popular public names used by the operating system. Notably the
3590 operating system known as "Windows 7" is really version 6.1 (ie. major
3591 = 6, minor = 1). You can find out the real versions corresponding to
3592 releases of Windows by consulting Wikipedia or MSDN.
3593 If the version could not be determined, then 0 is returned.
3595 Please read "INSPECTION" in guestfs(3) for more details.
3597 On error this function returns -1.
3599 (Added in 1.5.3)
3601 guestfs_inspect_get_minor_version
3603 int
3604 guestfs_inspect_get_minor_version (guestfs_h *g,
3605 const char *root);
3606 This function should only be called with a root device string as
3608 returned by "guestfs_inspect_os".
3609 This returns the minor version number of the inspected operating
3611 system.
3612 If the version could not be determined, then 0 is returned.
3614 Please read "INSPECTION" in guestfs(3) for more details. See also
3616 "guestfs_inspect_get_major_version".
3617 On error this function returns -1.
3619 (Added in 1.5.3)
3621 guestfs_inspect_get_mountpoints
3623 char **
3624 guestfs_inspect_get_mountpoints (guestfs_h *g,
3625 const char *root);
3626 This function should only be called with a root device string as
3628 returned by "guestfs_inspect_os".
3629 This returns a hash of where we think the filesystems associated with
3631 this operating system should be mounted. Callers should note that this
3632 is at best an educated guess made by reading configuration files such
3633 as "/etc/fstab". In particular note that this may return filesystems
3634 which are non-existent or not mountable and callers should be prepared
3635 to handle or ignore failures if they try to mount them.
3636 Each element in the returned hashtable has a key which is the path of
3638 the mountpoint (eg. "/boot") and a value which is the filesystem that
3639 would be mounted there (eg. "/dev/sda1").
3640 Non-mounted devices such as swap devices are not returned in this list.
3642 Please read "INSPECTION" in guestfs(3) for more details. See also
3644 "guestfs_inspect_get_filesystems".
3645 This function returns a NULL-terminated array of strings, or NULL if
3647 there was an error. The array of strings will always have length
3648 "2n+1", where "n" keys and values alternate, followed by the trailing
3649 NULL entry. The caller must free the strings and the array after use.
3650 (Added in 1.5.3)
3652 guestfs_inspect_get_package_format
3654 char *
3655 guestfs_inspect_get_package_format (guestfs_h *g,
3656 const char *root);
3657 This function should only be called with a root device string as
3659 returned by "guestfs_inspect_os".
3660 This function and "guestfs_inspect_get_package_management" return the
3662 package format and package management tool used by the inspected
3663 operating system. For example for Fedora these functions would return
3664 "rpm" (package format) and "yum" (package management).
3665 This returns the string "unknown" if we could not determine the package
3667 format or if the operating system does not have a real packaging system
3668 (eg. Windows).
3669 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman".
3671 Future versions of libguestfs may return other strings.
3672 Please read "INSPECTION" in guestfs(3) for more details.
3674 This function returns a string, or NULL on error. The caller must free
3676 the returned string after use.
3677 (Added in 1.7.5)
3679 guestfs_inspect_get_package_management
3681 char *
3682 guestfs_inspect_get_package_management (guestfs_h *g,
3683 const char *root);
3684 This function should only be called with a root device string as
3686 returned by "guestfs_inspect_os".
3687 "guestfs_inspect_get_package_format" and this function return the
3689 package format and package management tool used by the inspected
3690 operating system. For example for Fedora these functions would return
3691 "rpm" (package format) and "yum" (package management).
3692 This returns the string "unknown" if we could not determine the package
3694 management tool or if the operating system does not have a real
3695 packaging system (eg. Windows).
3696 Possible strings include: "yum", "up2date", "apt" (for all Debian
3698 derivatives), "portage", "pisi", "pacman", "urpmi". Future versions of
3699 libguestfs may return other strings.
3700 Please read "INSPECTION" in guestfs(3) for more details.
3702 This function returns a string, or NULL on error. The caller must free
3704 the returned string after use.
3705 (Added in 1.7.5)
3707 guestfs_inspect_get_product_name
3709 char *
3710 guestfs_inspect_get_product_name (guestfs_h *g,
3711 const char *root);
3712 This function should only be called with a root device string as
3714 returned by "guestfs_inspect_os".
3715 This returns the product name of the inspected operating system. The
3717 product name is generally some freeform string which can be displayed
3718 to the user, but should not be parsed by programs.
3719 If the product name could not be determined, then the string "unknown"
3721 is returned.
3722 Please read "INSPECTION" in guestfs(3) for more details.
3724 This function returns a string, or NULL on error. The caller must free
3726 the returned string after use.
3727 (Added in 1.5.3)
3729 guestfs_inspect_get_roots
3731 char **
3732 guestfs_inspect_get_roots (guestfs_h *g);
3733 This function is a convenient way to get the list of root devices, as
3735 returned from a previous call to "guestfs_inspect_os", but without
3736 redoing the whole inspection process.
3737 This returns an empty list if either no root devices were found or the
3739 caller has not called "guestfs_inspect_os".
3740 Please read "INSPECTION" in guestfs(3) for more details.
3742 This function returns a NULL-terminated array of strings (like
3744 environ(3)), or NULL if there was an error. The caller must free the
3745 strings and the array after use.
3746 (Added in 1.7.3)
3748 guestfs_inspect_get_type
3750 char *
3751 guestfs_inspect_get_type (guestfs_h *g,
3752 const char *root);
3753 This function should only be called with a root device string as
3755 returned by "guestfs_inspect_os".
3756 This returns the type of the inspected operating system. Currently
3758 defined types are:
3759 "linux"
3761 Any Linux-based operating system.
3762 "windows"
3764 Any Microsoft Windows operating system.
3765 "freebsd"
3767 FreeBSD.
3768 "unknown"
3770 The operating system type could not be determined.
3771 Future versions of libguestfs may return other strings here. The
3773 caller should be prepared to handle any string.
3774 Please read "INSPECTION" in guestfs(3) for more details.
3776 This function returns a string, or NULL on error. The caller must free
3778 the returned string after use.
3779 (Added in 1.5.3)
3781 guestfs_inspect_get_windows_systemroot
3783 char *
3784 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
3785 const char *root);
3786 This function should only be called with a root device string as
3788 returned by "guestfs_inspect_os".
3789 This returns the Windows systemroot of the inspected guest. The
3791 systemroot is a directory path such as "/WINDOWS".
3792 This call assumes that the guest is Windows and that the systemroot
3794 could be determined by inspection. If this is not the case then an
3795 error is returned.
3796 Please read "INSPECTION" in guestfs(3) for more details.
3798 This function returns a string, or NULL on error. The caller must free
3800 the returned string after use.
3801 (Added in 1.5.25)
3803 guestfs_inspect_list_applications
3805 struct guestfs_application_list *
3806 guestfs_inspect_list_applications (guestfs_h *g,
3807 const char *root);
3808 This function should only be called with a root device string as
3810 returned by "guestfs_inspect_os".
3811 Return the list of applications installed in the operating system.
3813 Note: This call works differently from other parts of the inspection
3815 API. You have to call "guestfs_inspect_os", then
3816 "guestfs_inspect_get_mountpoints", then mount up the disks, before
3817 calling this. Listing applications is a significantly more difficult
3818 operation which requires access to the full filesystem. Also note that
3819 unlike the other "guestfs_inspect_get_*" calls which are just returning
3820 data cached in the libguestfs handle, this call actually reads parts of
3821 the mounted filesystems during the call.
3822 This returns an empty list if the inspection code was not able to
3824 determine the list of applications.
3825 The application structure contains the following fields:
3827 "app_name"
3829 The name of the application. For Red Hat-derived and Debian-
3830 derived Linux guests, this is the package name.
3831 "app_display_name"
3833 The display name of the application, sometimes localized to the
3834 install language of the guest operating system.
3835 If unavailable this is returned as an empty string "". Callers
3837 needing to display something can use "app_name" instead.
3838 "app_epoch"
3840 For package managers which use epochs, this contains the epoch of
3841 the package (an integer). If unavailable, this is returned as 0.
3842 "app_version"
3844 The version string of the application or package. If unavailable
3845 this is returned as an empty string "".
3846 "app_release"
3848 The release string of the application or package, for package
3849 managers that use this. If unavailable this is returned as an
3850 empty string "".
3851 "app_install_path"
3853 The installation path of the application (on operating systems such
3854 as Windows which use installation paths). This path is in the
3855 format used by the guest operating system, it is not a libguestfs
3856 path.
3857 If unavailable this is returned as an empty string "".
3859 "app_trans_path"
3861 The install path translated into a libguestfs path. If unavailable
3862 this is returned as an empty string "".
3863 "app_publisher"
3865 The name of the publisher of the application, for package managers
3866 that use this. If unavailable this is returned as an empty string
3867 "".
3868 "app_url"
3870 The URL (eg. upstream URL) of the application. If unavailable this
3871 is returned as an empty string "".
3872 "app_source_package"
3874 For packaging systems which support this, the name of the source
3875 package. If unavailable this is returned as an empty string "".
3876 "app_summary"
3878 A short (usually one line) description of the application or
3879 package. If unavailable this is returned as an empty string "".
3880 "app_description"
3882 A longer description of the application or package. If unavailable
3883 this is returned as an empty string "".
3884 Please read "INSPECTION" in guestfs(3) for more details.
3886 This function returns a "struct guestfs_application_list *", or NULL if
3888 there was an error. The caller must call
3889 "guestfs_free_application_list" after use.
3890 (Added in 1.7.8)
3892 guestfs_inspect_os
3894 char **
3895 guestfs_inspect_os (guestfs_h *g);
3896 This function uses other libguestfs functions and certain heuristics to
3898 inspect the disk(s) (usually disks belonging to a virtual machine),
3899 looking for operating systems.
3900 The list returned is empty if no operating systems were found.
3902 If one operating system was found, then this returns a list with a
3904 single element, which is the name of the root filesystem of this
3905 operating system. It is also possible for this function to return a
3906 list containing more than one element, indicating a dual-boot or multi-
3907 boot virtual machine, with each element being the root filesystem of
3908 one of the operating systems.
3909 You can pass the root string(s) returned to other
3911 "guestfs_inspect_get_*" functions in order to query further information
3912 about each operating system, such as the name and version.
3913 This function uses other libguestfs features such as "guestfs_mount_ro"
3915 and "guestfs_umount_all" in order to mount and unmount filesystems and
3916 look at the contents. This should be called with no disks currently
3917 mounted. The function may also use Augeas, so any existing Augeas
3918 handle will be closed.
3919 This function cannot decrypt encrypted disks. The caller must do that
3921 first (supplying the necessary keys) if the disk is encrypted.
3922 Please read "INSPECTION" in guestfs(3) for more details.
3924 See also "guestfs_list_filesystems".
3926 This function returns a NULL-terminated array of strings (like
3928 environ(3)), or NULL if there was an error. The caller must free the
3929 strings and the array after use.
3930 (Added in 1.5.3)
3932 guestfs_is_blockdev
3934 int
3935 guestfs_is_blockdev (guestfs_h *g,
3936 const char *path);
3937 This returns "true" if and only if there is a block device with the
3939 given "path" name.
3940 See also "guestfs_stat".
3942 This function returns a C truth value on success or -1 on error.
3944 (Added in 1.5.10)
3946 guestfs_is_busy
3948 int
3949 guestfs_is_busy (guestfs_h *g);
3950 This returns true iff this handle is busy processing a command (in the
3952 "BUSY" state).
3953 For more information on states, see guestfs(3).
3955 This function returns a C truth value on success or -1 on error.
3957 (Added in 1.0.2)
3959 guestfs_is_chardev
3961 int
3962 guestfs_is_chardev (guestfs_h *g,
3963 const char *path);
3964 This returns "true" if and only if there is a character device with the
3966 given "path" name.
3967 See also "guestfs_stat".
3969 This function returns a C truth value on success or -1 on error.
3971 (Added in 1.5.10)
3973 guestfs_is_config
3975 int
3976 guestfs_is_config (guestfs_h *g);
3977 This returns true iff this handle is being configured (in the "CONFIG"
3979 state).
3980 For more information on states, see guestfs(3).
3982 This function returns a C truth value on success or -1 on error.
3984 (Added in 1.0.2)
3986 guestfs_is_dir
3988 int
3989 guestfs_is_dir (guestfs_h *g,
3990 const char *path);
3991 This returns "true" if and only if there is a directory with the given
3993 "path" name. Note that it returns false for other objects like files.
3994 See also "guestfs_stat".
3996 This function returns a C truth value on success or -1 on error.
3998 (Added in 0.8)
4000 guestfs_is_fifo
4002 int
4003 guestfs_is_fifo (guestfs_h *g,
4004 const char *path);
4005 This returns "true" if and only if there is a FIFO (named pipe) with
4007 the given "path" name.
4008 See also "guestfs_stat".
4010 This function returns a C truth value on success or -1 on error.
4012 (Added in 1.5.10)
4014 guestfs_is_file
4016 int
4017 guestfs_is_file (guestfs_h *g,
4018 const char *path);
4019 This returns "true" if and only if there is a regular file with the
4021 given "path" name. Note that it returns false for other objects like
4022 directories.
4023 See also "guestfs_stat".
4025 This function returns a C truth value on success or -1 on error.
4027 (Added in 0.8)
4029 guestfs_is_launching
4031 int
4032 guestfs_is_launching (guestfs_h *g);
4033 This returns true iff this handle is launching the subprocess (in the
4035 "LAUNCHING" state).
4036 For more information on states, see guestfs(3).
4038 This function returns a C truth value on success or -1 on error.
4040 (Added in 1.0.2)
4042 guestfs_is_lv
4044 int
4045 guestfs_is_lv (guestfs_h *g,
4046 const char *device);
4047 This command tests whether "device" is a logical volume, and returns
4049 true iff this is the case.
4050 This function returns a C truth value on success or -1 on error.
4052 (Added in 1.5.3)
4054 guestfs_is_ready
4056 int
4057 guestfs_is_ready (guestfs_h *g);
4058 This returns true iff this handle is ready to accept commands (in the
4060 "READY" state).
4061 For more information on states, see guestfs(3).
4063 This function returns a C truth value on success or -1 on error.
4065 (Added in 1.0.2)
4067 guestfs_is_socket
4069 int
4070 guestfs_is_socket (guestfs_h *g,
4071 const char *path);
4072 This returns "true" if and only if there is a Unix domain socket with
4074 the given "path" name.
4075 See also "guestfs_stat".
4077 This function returns a C truth value on success or -1 on error.
4079 (Added in 1.5.10)
4081 guestfs_is_symlink
4083 int
4084 guestfs_is_symlink (guestfs_h *g,
4085 const char *path);
4086 This returns "true" if and only if there is a symbolic link with the
4088 given "path" name.
4089 See also "guestfs_stat".
4091 This function returns a C truth value on success or -1 on error.
4093 (Added in 1.5.10)
4095 guestfs_kill_subprocess
4097 int
4098 guestfs_kill_subprocess (guestfs_h *g);
4099 This kills the qemu subprocess. You should never need to call this.
4101 This function returns 0 on success or -1 on error.
4103 (Added in 0.3)
4105 guestfs_launch
4107 int
4108 guestfs_launch (guestfs_h *g);
4109 Internally libguestfs is implemented by running a virtual machine using
4111 qemu(1).
4112 You should call this after configuring the handle (eg. adding drives)
4114 but before performing any actions.
4115 This function returns 0 on success or -1 on error.
4117 (Added in 0.3)
4119 guestfs_lchown
4121 int
4122 guestfs_lchown (guestfs_h *g,
4123 int owner,
4124 int group,
4125 const char *path);
4126 Change the file owner to "owner" and group to "group". This is like
4128 "guestfs_chown" but if "path" is a symlink then the link itself is
4129 changed, not the target.
4130 Only numeric uid and gid are supported. If you want to use names, you
4132 will need to locate and parse the password file yourself (Augeas
4133 support makes this relatively easy).
4134 This function returns 0 on success or -1 on error.
4136 (Added in 1.0.77)
4138 guestfs_lgetxattr
4140 char *
4141 guestfs_lgetxattr (guestfs_h *g,
4142 const char *path,
4143 const char *name,
4144 size_t *size_r);
4145 Get a single extended attribute from file "path" named "name". If
4147 "path" is a symlink, then this call returns an extended attribute from
4148 the symlink.
4149 Normally it is better to get all extended attributes from a file in one
4151 go by calling "guestfs_getxattrs". However some Linux filesystem
4152 implementations are buggy and do not provide a way to list out
4153 attributes. For these filesystems (notably ntfs-3g) you have to know
4154 the names of the extended attributes you want in advance and call this
4155 function.
4156 Extended attribute values are blobs of binary data. If there is no
4158 extended attribute named "name", this returns an error.
4159 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
4161 This function returns a buffer, or NULL on error. The size of the
4163 returned buffer is written to *size_r. The caller must free the
4164 returned buffer after use.
4165 (Added in 1.7.24)
4167 guestfs_lgetxattrs
4169 struct guestfs_xattr_list *
4170 guestfs_lgetxattrs (guestfs_h *g,
4171 const char *path);
4172 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
4174 link, then it returns the extended attributes of the link itself.
4175 This function returns a "struct guestfs_xattr_list *", or NULL if there
4177 was an error. The caller must call "guestfs_free_xattr_list" after
4178 use.
4179 (Added in 1.0.59)
4181 guestfs_list_devices
4183 char **
4184 guestfs_list_devices (guestfs_h *g);
4185 List all the block devices.
4187 The full block device names are returned, eg. "/dev/sda".
4189 See also "guestfs_list_filesystems".
4191 This function returns a NULL-terminated array of strings (like
4193 environ(3)), or NULL if there was an error. The caller must free the
4194 strings and the array after use.
4195 (Added in 0.4)
4197 guestfs_list_filesystems
4199 char **
4200 guestfs_list_filesystems (guestfs_h *g);
4201 This inspection command looks for filesystems on partitions, block
4203 devices and logical volumes, returning a list of devices containing
4204 filesystems and their type.
4205 The return value is a hash, where the keys are the devices containing
4207 filesystems, and the values are the filesystem types. For example:
4208 "/dev/sda1" => "ntfs"
4210 "/dev/sda2" => "ext2"
4211 "/dev/vg_guest/lv_root" => "ext4"
4212 "/dev/vg_guest/lv_swap" => "swap"
4213 The value can have the special value "unknown", meaning the content of
4215 the device is undetermined or empty. "swap" means a Linux swap
4216 partition.
4217 This command runs other libguestfs commands, which might include
4219 "guestfs_mount" and "guestfs_umount", and therefore you should use this
4220 soon after launch and only when nothing is mounted.
4221 Not all of the filesystems returned will be mountable. In particular,
4223 swap partitions are returned in the list. Also this command does not
4224 check that each filesystem found is valid and mountable, and some
4225 filesystems might be mountable but require special options.
4226 Filesystems may not all belong to a single logical operating system
4227 (use "guestfs_inspect_os" to look for OSes).
4228 This function returns a NULL-terminated array of strings, or NULL if
4230 there was an error. The array of strings will always have length
4231 "2n+1", where "n" keys and values alternate, followed by the trailing
4232 NULL entry. The caller must free the strings and the array after use.
4233 (Added in 1.5.15)
4235 guestfs_list_partitions
4237 char **
4238 guestfs_list_partitions (guestfs_h *g);
4239 List all the partitions detected on all block devices.
4241 The full partition device names are returned, eg. "/dev/sda1"
4243 This does not return logical volumes. For that you will need to call
4245 "guestfs_lvs".
4246 See also "guestfs_list_filesystems".
4248 This function returns a NULL-terminated array of strings (like
4250 environ(3)), or NULL if there was an error. The caller must free the
4251 strings and the array after use.
4252 (Added in 0.4)
4254 guestfs_ll
4256 char *
4257 guestfs_ll (guestfs_h *g,
4258 const char *directory);
4259 List the files in "directory" (relative to the root directory, there is
4261 no cwd) in the format of 'ls -la'.
4262 This command is mostly useful for interactive sessions. It is not
4264 intended that you try to parse the output string.
4265 This function returns a string, or NULL on error. The caller must free
4267 the returned string after use.
4268 (Added in 0.4)
4270 guestfs_ln
4272 int
4273 guestfs_ln (guestfs_h *g,
4274 const char *target,
4275 const char *linkname);
4276 This command creates a hard link using the "ln" command.
4278 This function returns 0 on success or -1 on error.
4280 (Added in 1.0.66)
4282 guestfs_ln_f
4284 int
4285 guestfs_ln_f (guestfs_h *g,
4286 const char *target,
4287 const char *linkname);
4288 This command creates a hard link using the "ln -f" command. The "-f"
4290 option removes the link ("linkname") if it exists already.
4291 This function returns 0 on success or -1 on error.
4293 (Added in 1.0.66)
4295 guestfs_ln_s
4297 int
4298 guestfs_ln_s (guestfs_h *g,
4299 const char *target,
4300 const char *linkname);
4301 This command creates a symbolic link using the "ln -s" command.
4303 This function returns 0 on success or -1 on error.
4305 (Added in 1.0.66)
4307 guestfs_ln_sf
4309 int
4310 guestfs_ln_sf (guestfs_h *g,
4311 const char *target,
4312 const char *linkname);
4313 This command creates a symbolic link using the "ln -sf" command, The
4315 "-f" option removes the link ("linkname") if it exists already.
4316 This function returns 0 on success or -1 on error.
4318 (Added in 1.0.66)
4320 guestfs_lremovexattr
4322 int
4323 guestfs_lremovexattr (guestfs_h *g,
4324 const char *xattr,
4325 const char *path);
4326 This is the same as "guestfs_removexattr", but if "path" is a symbolic
4328 link, then it removes an extended attribute of the link itself.
4329 This function returns 0 on success or -1 on error.
4331 (Added in 1.0.59)
4333 guestfs_ls
4335 char **
4336 guestfs_ls (guestfs_h *g,
4337 const char *directory);
4338 List the files in "directory" (relative to the root directory, there is
4340 no cwd). The '.' and '..' entries are not returned, but hidden files
4341 are shown.
4342 This command is mostly useful for interactive sessions. Programs
4344 should probably use "guestfs_readdir" instead.
4345 This function returns a NULL-terminated array of strings (like
4347 environ(3)), or NULL if there was an error. The caller must free the
4348 strings and the array after use.
4349 (Added in 0.4)
4351 guestfs_lsetxattr
4353 int
4354 guestfs_lsetxattr (guestfs_h *g,
4355 const char *xattr,
4356 const char *val,
4357 int vallen,
4358 const char *path);
4359 This is the same as "guestfs_setxattr", but if "path" is a symbolic
4361 link, then it sets an extended attribute of the link itself.
4362 This function returns 0 on success or -1 on error.
4364 (Added in 1.0.59)
4366 guestfs_lstat
4368 struct guestfs_stat *
4369 guestfs_lstat (guestfs_h *g,
4370 const char *path);
4371 Returns file information for the given "path".
4373 This is the same as "guestfs_stat" except that if "path" is a symbolic
4375 link, then the link is stat-ed, not the file it refers to.
4376 This is the same as the lstat(2) system call.
4378 This function returns a "struct guestfs_stat *", or NULL if there was
4380 an error. The caller must call "guestfs_free_stat" after use.
4381 (Added in 0.9.2)
4383 guestfs_lstatlist
4385 struct guestfs_stat_list *
4386 guestfs_lstatlist (guestfs_h *g,
4387 const char *path,
4388 char *const *names);
4389 This call allows you to perform the "guestfs_lstat" operation on
4391 multiple files, where all files are in the directory "path". "names"
4392 is the list of files from this directory.
4393 On return you get a list of stat structs, with a one-to-one
4395 correspondence to the "names" list. If any name did not exist or could
4396 not be lstat'd, then the "ino" field of that structure is set to "-1".
4397 This call is intended for programs that want to efficiently list a
4399 directory contents without making many round-trips. See also
4400 "guestfs_lxattrlist" for a similarly efficient call for getting
4401 extended attributes. Very long directory listings might cause the
4402 protocol message size to be exceeded, causing this call to fail. The
4403 caller must split up such requests into smaller groups of names.
4404 This function returns a "struct guestfs_stat_list *", or NULL if there
4406 was an error. The caller must call "guestfs_free_stat_list" after use.
4407 (Added in 1.0.77)
4409 guestfs_luks_add_key
4411 int
4412 guestfs_luks_add_key (guestfs_h *g,
4413 const char *device,
4414 const char *key,
4415 const char *newkey,
4416 int keyslot);
4417 This command adds a new key on LUKS device "device". "key" is any
4419 existing key, and is used to access the device. "newkey" is the new
4420 key to add. "keyslot" is the key slot that will be replaced.
4421 Note that if "keyslot" already contains a key, then this command will
4423 fail. You have to use "guestfs_luks_kill_slot" first to remove that
4424 key.
4425 This function returns 0 on success or -1 on error.
4427 This function takes a key or passphrase parameter which could contain
4429 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
4430 information.
4431 (Added in 1.5.2)
4433 guestfs_luks_close
4435 int
4436 guestfs_luks_close (guestfs_h *g,
4437 const char *device);
4438 This closes a LUKS device that was created earlier by
4440 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
4441 must be the name of the LUKS mapping device (ie. "/dev/mapper/mapname")
4442 and not the name of the underlying block device.
4443 This function returns 0 on success or -1 on error.
4445 (Added in 1.5.1)
4447 guestfs_luks_format
4449 int
4450 guestfs_luks_format (guestfs_h *g,
4451 const char *device,
4452 const char *key,
4453 int keyslot);
4454 This command erases existing data on "device" and formats the device as
4456 a LUKS encrypted device. "key" is the initial key, which is added to
4457 key slot "slot". (LUKS supports 8 key slots, numbered 0-7).
4458 This function returns 0 on success or -1 on error.
4460 This command is dangerous. Without careful use you can easily destroy
4462 all your data.
4463 This function takes a key or passphrase parameter which could contain
4465 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
4466 information.
4467 (Added in 1.5.2)
4469 guestfs_luks_format_cipher
4471 int
4472 guestfs_luks_format_cipher (guestfs_h *g,
4473 const char *device,
4474 const char *key,
4475 int keyslot,
4476 const char *cipher);
4477 This command is the same as "guestfs_luks_format" but it also allows
4479 you to set the "cipher" used.
4480 This function returns 0 on success or -1 on error.
4482 This command is dangerous. Without careful use you can easily destroy
4484 all your data.
4485 This function takes a key or passphrase parameter which could contain
4487 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
4488 information.
4489 (Added in 1.5.2)
4491 guestfs_luks_kill_slot
4493 int
4494 guestfs_luks_kill_slot (guestfs_h *g,
4495 const char *device,
4496 const char *key,
4497 int keyslot);
4498 This command deletes the key in key slot "keyslot" from the encrypted
4500 LUKS device "device". "key" must be one of the other keys.
4501 This function returns 0 on success or -1 on error.
4503 This function takes a key or passphrase parameter which could contain
4505 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
4506 information.
4507 (Added in 1.5.2)
4509 guestfs_luks_open
4511 int
4512 guestfs_luks_open (guestfs_h *g,
4513 const char *device,
4514 const char *key,
4515 const char *mapname);
4516 This command opens a block device which has been encrypted according to
4518 the Linux Unified Key Setup (LUKS) standard.
4519 "device" is the encrypted block device or partition.
4521 The caller must supply one of the keys associated with the LUKS block
4523 device, in the "key" parameter.
4524 This creates a new block device called "/dev/mapper/mapname". Reads
4526 and writes to this block device are decrypted from and encrypted to the
4527 underlying "device" respectively.
4528 If this block device contains LVM volume groups, then calling
4530 "guestfs_vgscan" followed by "guestfs_vg_activate_all" will make them
4531 visible.
4532 This function returns 0 on success or -1 on error.
4534 This function takes a key or passphrase parameter which could contain
4536 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
4537 information.
4538 (Added in 1.5.1)
4540 guestfs_luks_open_ro
4542 int
4543 guestfs_luks_open_ro (guestfs_h *g,
4544 const char *device,
4545 const char *key,
4546 const char *mapname);
4547 This is the same as "guestfs_luks_open" except that a read-only mapping
4549 is created.
4550 This function returns 0 on success or -1 on error.
4552 This function takes a key or passphrase parameter which could contain
4554 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
4555 information.
4556 (Added in 1.5.1)
4558 guestfs_lvcreate
4560 int
4561 guestfs_lvcreate (guestfs_h *g,
4562 const char *logvol,
4563 const char *volgroup,
4564 int mbytes);
4565 This creates an LVM logical volume called "logvol" on the volume group
4567 "volgroup", with "size" megabytes.
4568 This function returns 0 on success or -1 on error.
4570 (Added in 0.8)
4572 guestfs_lvm_canonical_lv_name
4574 char *
4575 guestfs_lvm_canonical_lv_name (guestfs_h *g,
4576 const char *lvname);
4577 This converts alternative naming schemes for LVs that you might find to
4579 the canonical name. For example, "/dev/mapper/VG-LV" is converted to
4580 "/dev/VG/LV".
4581 This command returns an error if the "lvname" parameter does not refer
4583 to a logical volume.
4584 See also "guestfs_is_lv".
4586 This function returns a string, or NULL on error. The caller must free
4588 the returned string after use.
4589 (Added in 1.5.24)
4591 guestfs_lvm_clear_filter
4593 int
4594 guestfs_lvm_clear_filter (guestfs_h *g);
4595 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
4597 to see every block device.
4598 This command also clears the LVM cache and performs a volume group
4600 scan.
4601 This function returns 0 on success or -1 on error.
4603 (Added in 1.5.1)
4605 guestfs_lvm_remove_all
4607 int
4608 guestfs_lvm_remove_all (guestfs_h *g);
4609 This command removes all LVM logical volumes, volume groups and
4611 physical volumes.
4612 This function returns 0 on success or -1 on error.
4614 This command is dangerous. Without careful use you can easily destroy
4616 all your data.
4617 (Added in 0.8)
4619 guestfs_lvm_set_filter
4621 int
4622 guestfs_lvm_set_filter (guestfs_h *g,
4623 char *const *devices);
4624 This sets the LVM device filter so that LVM will only be able to "see"
4626 the block devices in the list "devices", and will ignore all other
4627 attached block devices.
4628 Where disk image(s) contain duplicate PVs or VGs, this command is
4630 useful to get LVM to ignore the duplicates, otherwise LVM can get
4631 confused. Note also there are two types of duplication possible:
4632 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
4633 cloned but just happen to have the same name. In normal operation you
4634 cannot create this situation, but you can do it outside LVM, eg. by
4635 cloning disk images or by bit twiddling inside the LVM metadata.
4636 This command also clears the LVM cache and performs a volume group
4638 scan.
4639 You can filter whole block devices or individual partitions.
4641 You cannot use this if any VG is currently in use (eg. contains a
4643 mounted filesystem), even if you are not filtering out that VG.
4644 This function returns 0 on success or -1 on error.
4646 (Added in 1.5.1)
4648 guestfs_lvremove
4650 int
4651 guestfs_lvremove (guestfs_h *g,
4652 const char *device);
4653 Remove an LVM logical volume "device", where "device" is the path to
4655 the LV, such as "/dev/VG/LV".
4656 You can also remove all LVs in a volume group by specifying the VG
4658 name, "/dev/VG".
4659 This function returns 0 on success or -1 on error.
4661 (Added in 1.0.13)
4663 guestfs_lvrename
4665 int
4666 guestfs_lvrename (guestfs_h *g,
4667 const char *logvol,
4668 const char *newlogvol);
4669 Rename a logical volume "logvol" with the new name "newlogvol".
4671 This function returns 0 on success or -1 on error.
4673 (Added in 1.0.83)
4675 guestfs_lvresize
4677 int
4678 guestfs_lvresize (guestfs_h *g,
4679 const char *device,
4680 int mbytes);
4681 This resizes (expands or shrinks) an existing LVM logical volume to
4683 "mbytes". When reducing, data in the reduced part is lost.
4684 This function returns 0 on success or -1 on error.
4686 (Added in 1.0.27)
4688 guestfs_lvresize_free
4690 int
4691 guestfs_lvresize_free (guestfs_h *g,
4692 const char *lv,
4693 int percent);
4694 This expands an existing logical volume "lv" so that it fills "pc"% of
4696 the remaining free space in the volume group. Commonly you would call
4697 this with pc = 100 which expands the logical volume as much as
4698 possible, using all remaining free space in the volume group.
4699 This function returns 0 on success or -1 on error.
4701 (Added in 1.3.3)
4703 guestfs_lvs
4705 char **
4706 guestfs_lvs (guestfs_h *g);
4707 List all the logical volumes detected. This is the equivalent of the
4709 lvs(8) command.
4710 This returns a list of the logical volume device names (eg.
4712 "/dev/VolGroup00/LogVol00").
4713 See also "guestfs_lvs_full", "guestfs_list_filesystems".
4715 This function returns a NULL-terminated array of strings (like
4717 environ(3)), or NULL if there was an error. The caller must free the
4718 strings and the array after use.
4719 (Added in 0.4)
4721 guestfs_lvs_full
4723 struct guestfs_lvm_lv_list *
4724 guestfs_lvs_full (guestfs_h *g);
4725 List all the logical volumes detected. This is the equivalent of the
4727 lvs(8) command. The "full" version includes all fields.
4728 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
4730 there was an error. The caller must call "guestfs_free_lvm_lv_list"
4731 after use.
4732 (Added in 0.4)
4734 guestfs_lvuuid
4736 char *
4737 guestfs_lvuuid (guestfs_h *g,
4738 const char *device);
4739 This command returns the UUID of the LVM LV "device".
4741 This function returns a string, or NULL on error. The caller must free
4743 the returned string after use.
4744 (Added in 1.0.87)
4746 guestfs_lxattrlist
4748 struct guestfs_xattr_list *
4749 guestfs_lxattrlist (guestfs_h *g,
4750 const char *path,
4751 char *const *names);
4752 This call allows you to get the extended attributes of multiple files,
4754 where all files are in the directory "path". "names" is the list of
4755 files from this directory.
4756 On return you get a flat list of xattr structs which must be
4758 interpreted sequentially. The first xattr struct always has a zero-
4759 length "attrname". "attrval" in this struct is zero-length to indicate
4760 there was an error doing "lgetxattr" for this file, or is a C string
4761 which is a decimal number (the number of following attributes for this
4762 file, which could be "0"). Then after the first xattr struct are the
4763 zero or more attributes for the first named file. This repeats for the
4764 second and subsequent files.
4765 This call is intended for programs that want to efficiently list a
4767 directory contents without making many round-trips. See also
4768 "guestfs_lstatlist" for a similarly efficient call for getting standard
4769 stats. Very long directory listings might cause the protocol message
4770 size to be exceeded, causing this call to fail. The caller must split
4771 up such requests into smaller groups of names.
4772 This function returns a "struct guestfs_xattr_list *", or NULL if there
4774 was an error. The caller must call "guestfs_free_xattr_list" after
4775 use.
4776 (Added in 1.0.77)
4778 guestfs_mkdir
4780 int
4781 guestfs_mkdir (guestfs_h *g,
4782 const char *path);
4783 Create a directory named "path".
4785 This function returns 0 on success or -1 on error.
4787 (Added in 0.8)
4789 guestfs_mkdir_mode
4791 int
4792 guestfs_mkdir_mode (guestfs_h *g,
4793 const char *path,
4794 int mode);
4795 This command creates a directory, setting the initial permissions of
4797 the directory to "mode".
4798 For common Linux filesystems, the actual mode which is set will be
4800 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
4801 the mode in other ways.
4802 See also "guestfs_mkdir", "guestfs_umask"
4804 This function returns 0 on success or -1 on error.
4806 (Added in 1.0.77)
4808 guestfs_mkdir_p
4810 int
4811 guestfs_mkdir_p (guestfs_h *g,
4812 const char *path);
4813 Create a directory named "path", creating any parent directories as
4815 necessary. This is like the "mkdir -p" shell command.
4816 This function returns 0 on success or -1 on error.
4818 (Added in 0.8)
4820 guestfs_mkdtemp
4822 char *
4823 guestfs_mkdtemp (guestfs_h *g,
4824 const char *template);
4825 This command creates a temporary directory. The "template" parameter
4827 should be a full pathname for the temporary directory name with the
4828 final six characters being "XXXXXX".
4829 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
4831 one being suitable for Windows filesystems.
4832 The name of the temporary directory that was created is returned.
4834 The temporary directory is created with mode 0700 and is owned by root.
4836 The caller is responsible for deleting the temporary directory and its
4838 contents after use.
4839 See also: mkdtemp(3)
4841 This function returns a string, or NULL on error. The caller must free
4843 the returned string after use.
4844 (Added in 1.0.54)
4846 guestfs_mke2fs_J
4848 int
4849 guestfs_mke2fs_J (guestfs_h *g,
4850 const char *fstype,
4851 int blocksize,
4852 const char *device,
4853 const char *journal);
4854 This creates an ext2/3/4 filesystem on "device" with an external
4856 journal on "journal". It is equivalent to the command:
4857 mke2fs -t fstype -b blocksize -J device=<journal> <device>
4859 See also "guestfs_mke2journal".
4861 This function returns 0 on success or -1 on error.
4863 (Added in 1.0.68)
4865 guestfs_mke2fs_JL
4867 int
4868 guestfs_mke2fs_JL (guestfs_h *g,
4869 const char *fstype,
4870 int blocksize,
4871 const char *device,
4872 const char *label);
4873 This creates an ext2/3/4 filesystem on "device" with an external
4875 journal on the journal labeled "label".
4876 See also "guestfs_mke2journal_L".
4878 This function returns 0 on success or -1 on error.
4880 (Added in 1.0.68)
4882 guestfs_mke2fs_JU
4884 int
4885 guestfs_mke2fs_JU (guestfs_h *g,
4886 const char *fstype,
4887 int blocksize,
4888 const char *device,
4889 const char *uuid);
4890 This creates an ext2/3/4 filesystem on "device" with an external
4892 journal on the journal with UUID "uuid".
4893 See also "guestfs_mke2journal_U".
4895 This function returns 0 on success or -1 on error.
4897 (Added in 1.0.68)
4899 guestfs_mke2journal
4901 int
4902 guestfs_mke2journal (guestfs_h *g,
4903 int blocksize,
4904 const char *device);
4905 This creates an ext2 external journal on "device". It is equivalent to
4907 the command:
4908 mke2fs -O journal_dev -b blocksize device
4910 This function returns 0 on success or -1 on error.
4912 (Added in 1.0.68)
4914 guestfs_mke2journal_L
4916 int
4917 guestfs_mke2journal_L (guestfs_h *g,
4918 int blocksize,
4919 const char *label,
4920 const char *device);
4921 This creates an ext2 external journal on "device" with label "label".
4923 This function returns 0 on success or -1 on error.
4925 (Added in 1.0.68)
4927 guestfs_mke2journal_U
4929 int
4930 guestfs_mke2journal_U (guestfs_h *g,
4931 int blocksize,
4932 const char *uuid,
4933 const char *device);
4934 This creates an ext2 external journal on "device" with UUID "uuid".
4936 This function returns 0 on success or -1 on error.
4938 (Added in 1.0.68)
4940 guestfs_mkfifo
4942 int
4943 guestfs_mkfifo (guestfs_h *g,
4944 int mode,
4945 const char *path);
4946 This call creates a FIFO (named pipe) called "path" with mode "mode".
4948 It is just a convenient wrapper around "guestfs_mknod".
4949 The mode actually set is affected by the umask.
4951 This function returns 0 on success or -1 on error.
4953 (Added in 1.0.55)
4955 guestfs_mkfs
4957 int
4958 guestfs_mkfs (guestfs_h *g,
4959 const char *fstype,
4960 const char *device);
4961 This creates a filesystem on "device" (usually a partition or LVM
4963 logical volume). The filesystem type is "fstype", for example "ext3".
4964 This function returns 0 on success or -1 on error.
4966 (Added in 0.8)
4968 guestfs_mkfs_b
4970 int
4971 guestfs_mkfs_b (guestfs_h *g,
4972 const char *fstype,
4973 int blocksize,
4974 const char *device);
4975 This call is similar to "guestfs_mkfs", but it allows you to control
4977 the block size of the resulting filesystem. Supported block sizes
4978 depend on the filesystem type, but typically they are 1024, 2048 or
4979 4096 only.
4980 For VFAT and NTFS the "blocksize" parameter is treated as the requested
4982 cluster size.
4983 This function returns 0 on success or -1 on error.
4985 This function is deprecated. In new code, use the "guestfs_mkfs_opts"
4987 call instead.
4988 Deprecated functions will not be removed from the API, but the fact
4990 that they are deprecated indicates that there are problems with correct
4991 use of these functions.
4992 (Added in 1.0.68)
4994 guestfs_mkfs_opts
4996 int
4997 guestfs_mkfs_opts (guestfs_h *g,
4998 const char *fstype,
4999 const char *device,
5000 ...);
5001 You may supply a list of optional arguments to this call. Use zero or
5003 more of the following pairs of parameters, and terminate the list with
5004 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5005 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
5007 This function creates a filesystem on "device". The filesystem type is
5009 "fstype", for example "ext3".
5010 The optional arguments are:
5012 "blocksize"
5014 The filesystem block size. Supported block sizes depend on the
5015 filesystem type, but typically they are 1024, 2048 or 4096 for
5016 Linux ext2/3 filesystems.
5017 For VFAT and NTFS the "blocksize" parameter is treated as the
5019 requested cluster size.
5020 For UFS block sizes, please see mkfs.ufs(8).
5022 This function returns 0 on success or -1 on error.
5024 (Added in 1.7.19)
5026 guestfs_mkfs_opts_va
5028 int
5029 guestfs_mkfs_opts_va (guestfs_h *g,
5030 const char *fstype,
5031 const char *device,
5032 va_list args);
5033 This is the "va_list variant" of "guestfs_mkfs_opts".
5035 See "CALLS WITH OPTIONAL ARGUMENTS".
5037 guestfs_mkfs_opts_argv
5039 int
5040 guestfs_mkfs_opts_argv (guestfs_h *g,
5041 const char *fstype,
5042 const char *device,
5043 const struct guestfs_mkfs_opts_argv *optargs);
5044 This is the "argv variant" of "guestfs_mkfs_opts".
5046 See "CALLS WITH OPTIONAL ARGUMENTS".
5048 guestfs_mkmountpoint
5050 int
5051 guestfs_mkmountpoint (guestfs_h *g,
5052 const char *exemptpath);
5053 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
5055 that can be used to create extra mountpoints before mounting the first
5056 filesystem.
5057 These calls are only necessary in some very limited circumstances,
5059 mainly the case where you want to mount a mix of unrelated and/or read-
5060 only filesystems together.
5061 For example, live CDs often contain a "Russian doll" nest of
5063 filesystems, an ISO outer layer, with a squashfs image inside, with an
5064 ext2/3 image inside that. You can unpack this as follows in guestfish:
5065 add-ro Fedora-11-i686-Live.iso
5067 run
5068 mkmountpoint /cd
5069 mkmountpoint /sqsh
5070 mkmountpoint /ext3fs
5071 mount /dev/sda /cd
5072 mount-loop /cd/LiveOS/squashfs.img /sqsh
5073 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5074 The inner filesystem is now unpacked under the /ext3fs mountpoint.
5076 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
5078 You may get unexpected errors if you try to mix these calls. It is
5079 safest to manually unmount filesystems and remove mountpoints after
5080 use.
5081 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
5083 first, so for this to work for manual mountpoints, you must ensure that
5084 the innermost mountpoints have the longest pathnames, as in the example
5085 code above.
5086 For more details see
5088 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
5089 Autosync [see "guestfs_set_autosync", this is set by default on
5091 handles] means that "guestfs_umount_all" is called when the handle is
5092 closed which can also trigger these issues.
5093 This function returns 0 on success or -1 on error.
5095 (Added in 1.0.62)
5097 guestfs_mknod
5099 int
5100 guestfs_mknod (guestfs_h *g,
5101 int mode,
5102 int devmajor,
5103 int devminor,
5104 const char *path);
5105 This call creates block or character special devices, or named pipes
5107 (FIFOs).
5108 The "mode" parameter should be the mode, using the standard constants.
5110 "devmajor" and "devminor" are the device major and minor numbers, only
5111 used when creating block and character special devices.
5112 Note that, just like mknod(2), the mode must be bitwise OR'd with
5114 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
5115 a regular file). These constants are available in the standard Linux
5116 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
5117 "guestfs_mkfifo" which are wrappers around this command which bitwise
5118 OR in the appropriate constant for you.
5119 The mode actually set is affected by the umask.
5121 This function returns 0 on success or -1 on error.
5123 (Added in 1.0.55)
5125 guestfs_mknod_b
5127 int
5128 guestfs_mknod_b (guestfs_h *g,
5129 int mode,
5130 int devmajor,
5131 int devminor,
5132 const char *path);
5133 This call creates a block device node called "path" with mode "mode"
5135 and device major/minor "devmajor" and "devminor". It is just a
5136 convenient wrapper around "guestfs_mknod".
5137 The mode actually set is affected by the umask.
5139 This function returns 0 on success or -1 on error.
5141 (Added in 1.0.55)
5143 guestfs_mknod_c
5145 int
5146 guestfs_mknod_c (guestfs_h *g,
5147 int mode,
5148 int devmajor,
5149 int devminor,
5150 const char *path);
5151 This call creates a char device node called "path" with mode "mode" and
5153 device major/minor "devmajor" and "devminor". It is just a convenient
5154 wrapper around "guestfs_mknod".
5155 The mode actually set is affected by the umask.
5157 This function returns 0 on success or -1 on error.
5159 (Added in 1.0.55)
5161 guestfs_mkswap
5163 int
5164 guestfs_mkswap (guestfs_h *g,
5165 const char *device);
5166 Create a swap partition on "device".
5168 This function returns 0 on success or -1 on error.
5170 (Added in 1.0.55)
5172 guestfs_mkswap_L
5174 int
5175 guestfs_mkswap_L (guestfs_h *g,
5176 const char *label,
5177 const char *device);
5178 Create a swap partition on "device" with label "label".
5180 Note that you cannot attach a swap label to a block device (eg.
5182 "/dev/sda"), just to a partition. This appears to be a limitation of
5183 the kernel or swap tools.
5184 This function returns 0 on success or -1 on error.
5186 (Added in 1.0.55)
5188 guestfs_mkswap_U
5190 int
5191 guestfs_mkswap_U (guestfs_h *g,
5192 const char *uuid,
5193 const char *device);
5194 Create a swap partition on "device" with UUID "uuid".
5196 This function returns 0 on success or -1 on error.
5198 (Added in 1.0.55)
5200 guestfs_mkswap_file
5202 int
5203 guestfs_mkswap_file (guestfs_h *g,
5204 const char *path);
5205 Create a swap file.
5207 This command just writes a swap file signature to an existing file. To
5209 create the file itself, use something like "guestfs_fallocate".
5210 This function returns 0 on success or -1 on error.
5212 (Added in 1.0.66)
5214 guestfs_modprobe
5216 int
5217 guestfs_modprobe (guestfs_h *g,
5218 const char *modulename);
5219 This loads a kernel module in the appliance.
5221 The kernel module must have been whitelisted when libguestfs was built
5223 (see "appliance/kmod.whitelist.in" in the source).
5224 This function returns 0 on success or -1 on error.
5226 (Added in 1.0.68)
5228 guestfs_mount
5230 int
5231 guestfs_mount (guestfs_h *g,
5232 const char *device,
5233 const char *mountpoint);
5234 Mount a guest disk at a position in the filesystem. Block devices are
5236 named "/dev/sda", "/dev/sdb" and so on, as they were added to the
5237 guest. If those block devices contain partitions, they will have the
5238 usual names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style names can
5239 be used.
5240 The rules are the same as for mount(2): A filesystem must first be
5242 mounted on "/" before others can be mounted. Other filesystems can
5243 only be mounted on directories which already exist.
5244 The mounted filesystem is writable, if we have sufficient permissions
5246 on the underlying device.
5247 Important note: When you use this call, the filesystem options "sync"
5249 and "noatime" are set implicitly. This was originally done because we
5250 thought it would improve reliability, but it turns out that -o sync has
5251 a very large negative performance impact and negligible effect on
5252 reliability. Therefore we recommend that you avoid using
5253 "guestfs_mount" in any code that needs performance, and instead use
5254 "guestfs_mount_options" (use an empty string for the first parameter if
5255 you don't want any options).
5256 This function returns 0 on success or -1 on error.
5258 (Added in 0.3)
5260 guestfs_mount_loop
5262 int
5263 guestfs_mount_loop (guestfs_h *g,
5264 const char *file,
5265 const char *mountpoint);
5266 This command lets you mount "file" (a filesystem image in a file) on a
5268 mount point. It is entirely equivalent to the command "mount -o loop
5269 file mountpoint".
5270 This function returns 0 on success or -1 on error.
5272 (Added in 1.0.54)
5274 guestfs_mount_options
5276 int
5277 guestfs_mount_options (guestfs_h *g,
5278 const char *options,
5279 const char *device,
5280 const char *mountpoint);
5281 This is the same as the "guestfs_mount" command, but it allows you to
5283 set the mount options as for the mount(8) -o flag.
5284 If the "options" parameter is an empty string, then no options are
5286 passed (all options default to whatever the filesystem uses).
5287 This function returns 0 on success or -1 on error.
5289 (Added in 1.0.10)
5291 guestfs_mount_ro
5293 int
5294 guestfs_mount_ro (guestfs_h *g,
5295 const char *device,
5296 const char *mountpoint);
5297 This is the same as the "guestfs_mount" command, but it mounts the
5299 filesystem with the read-only (-o ro) flag.
5300 This function returns 0 on success or -1 on error.
5302 (Added in 1.0.10)
5304 guestfs_mount_vfs
5306 int
5307 guestfs_mount_vfs (guestfs_h *g,
5308 const char *options,
5309 const char *vfstype,
5310 const char *device,
5311 const char *mountpoint);
5312 This is the same as the "guestfs_mount" command, but it allows you to
5314 set both the mount options and the vfstype as for the mount(8) -o and
5315 -t flags.
5316 This function returns 0 on success or -1 on error.
5318 (Added in 1.0.10)
5320 guestfs_mountpoints
5322 char **
5323 guestfs_mountpoints (guestfs_h *g);
5324 This call is similar to "guestfs_mounts". That call returns a list of
5326 devices. This one returns a hash table (map) of device name to
5327 directory where the device is mounted.
5328 This function returns a NULL-terminated array of strings, or NULL if
5330 there was an error. The array of strings will always have length
5331 "2n+1", where "n" keys and values alternate, followed by the trailing
5332 NULL entry. The caller must free the strings and the array after use.
5333 (Added in 1.0.62)
5335 guestfs_mounts
5337 char **
5338 guestfs_mounts (guestfs_h *g);
5339 This returns the list of currently mounted filesystems. It returns the
5341 list of devices (eg. "/dev/sda1", "/dev/VG/LV").
5342 Some internal mounts are not shown.
5344 See also: "guestfs_mountpoints"
5346 This function returns a NULL-terminated array of strings (like
5348 environ(3)), or NULL if there was an error. The caller must free the
5349 strings and the array after use.
5350 (Added in 0.8)
5352 guestfs_mv
5354 int
5355 guestfs_mv (guestfs_h *g,
5356 const char *src,
5357 const char *dest);
5358 This moves a file from "src" to "dest" where "dest" is either a
5360 destination filename or destination directory.
5361 This function returns 0 on success or -1 on error.
5363 (Added in 1.0.18)
5365 guestfs_ntfs_3g_probe
5367 int
5368 guestfs_ntfs_3g_probe (guestfs_h *g,
5369 int rw,
5370 const char *device);
5371 This command runs the ntfs-3g.probe(8) command which probes an NTFS
5373 "device" for mountability. (Not all NTFS volumes can be mounted read-
5374 write, and some cannot be mounted at all).
5375 "rw" is a boolean flag. Set it to true if you want to test if the
5377 volume can be mounted read-write. Set it to false if you want to test
5378 if the volume can be mounted read-only.
5379 The return value is an integer which 0 if the operation would succeed,
5381 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
5382 On error this function returns -1.
5384 (Added in 1.0.43)
5386 guestfs_ntfsresize
5388 int
5389 guestfs_ntfsresize (guestfs_h *g,
5390 const char *device);
5391 This command resizes an NTFS filesystem, expanding or shrinking it to
5393 the size of the underlying device.
5394 Note: After the resize operation, the filesystem is marked as requiring
5396 a consistency check (for safety). You have to boot into Windows to
5397 perform this check and clear this condition. Furthermore, ntfsresize
5398 refuses to resize filesystems which have been marked in this way. So
5399 in effect it is not possible to call ntfsresize multiple times on a
5400 single filesystem without booting into Windows between each resize.
5401 See also ntfsresize(8).
5403 This function returns 0 on success or -1 on error.
5405 (Added in 1.3.2)
5407 guestfs_ntfsresize_size
5409 int
5410 guestfs_ntfsresize_size (guestfs_h *g,
5411 const char *device,
5412 int64_t size);
5413 This command is the same as "guestfs_ntfsresize" except that it allows
5415 you to specify the new size (in bytes) explicitly.
5416 This function returns 0 on success or -1 on error.
5418 (Added in 1.3.14)
5420 guestfs_part_add
5422 int
5423 guestfs_part_add (guestfs_h *g,
5424 const char *device,
5425 const char *prlogex,
5426 int64_t startsect,
5427 int64_t endsect);
5428 This command adds a partition to "device". If there is no partition
5430 table on the device, call "guestfs_part_init" first.
5431 The "prlogex" parameter is the type of partition. Normally you should
5433 pass "p" or "primary" here, but MBR partition tables also support "l"
5434 (or "logical") and "e" (or "extended") partition types.
5435 "startsect" and "endsect" are the start and end of the partition in
5437 sectors. "endsect" may be negative, which means it counts backwards
5438 from the end of the disk ("-1" is the last sector).
5439 Creating a partition which covers the whole disk is not so easy. Use
5441 "guestfs_part_disk" to do that.
5442 This function returns 0 on success or -1 on error.
5444 (Added in 1.0.78)
5446 guestfs_part_del
5448 int
5449 guestfs_part_del (guestfs_h *g,
5450 const char *device,
5451 int partnum);
5452 This command deletes the partition numbered "partnum" on "device".
5454 Note that in the case of MBR partitioning, deleting an extended
5456 partition also deletes any logical partitions it contains.
5457 This function returns 0 on success or -1 on error.
5459 (Added in 1.3.2)
5461 guestfs_part_disk
5463 int
5464 guestfs_part_disk (guestfs_h *g,
5465 const char *device,
5466 const char *parttype);
5467 This command is simply a combination of "guestfs_part_init" followed by
5469 "guestfs_part_add" to create a single primary partition covering the
5470 whole disk.
5471 "parttype" is the partition table type, usually "mbr" or "gpt", but
5473 other possible values are described in "guestfs_part_init".
5474 This function returns 0 on success or -1 on error.
5476 This command is dangerous. Without careful use you can easily destroy
5478 all your data.
5479 (Added in 1.0.78)
5481 guestfs_part_get_bootable
5483 int
5484 guestfs_part_get_bootable (guestfs_h *g,
5485 const char *device,
5486 int partnum);
5487 This command returns true if the partition "partnum" on "device" has
5489 the bootable flag set.
5490 See also "guestfs_part_set_bootable".
5492 This function returns a C truth value on success or -1 on error.
5494 (Added in 1.3.2)
5496 guestfs_part_get_mbr_id
5498 int
5499 guestfs_part_get_mbr_id (guestfs_h *g,
5500 const char *device,
5501 int partnum);
5502 Returns the MBR type byte (also known as the ID byte) from the numbered
5504 partition "partnum".
5505 Note that only MBR (old DOS-style) partitions have type bytes. You
5507 will get undefined results for other partition table types (see
5508 "guestfs_part_get_parttype").
5509 On error this function returns -1.
5511 (Added in 1.3.2)
5513 guestfs_part_get_parttype
5515 char *
5516 guestfs_part_get_parttype (guestfs_h *g,
5517 const char *device);
5518 This command examines the partition table on "device" and returns the
5520 partition table type (format) being used.
5521 Common return values include: "msdos" (a DOS/Windows style MBR
5523 partition table), "gpt" (a GPT/EFI-style partition table). Other
5524 values are possible, although unusual. See "guestfs_part_init" for a
5525 full list.
5526 This function returns a string, or NULL on error. The caller must free
5528 the returned string after use.
5529 (Added in 1.0.78)
5531 guestfs_part_init
5533 int
5534 guestfs_part_init (guestfs_h *g,
5535 const char *device,
5536 const char *parttype);
5537 This creates an empty partition table on "device" of one of the
5539 partition types listed below. Usually "parttype" should be either
5540 "msdos" or "gpt" (for large disks).
5541 Initially there are no partitions. Following this, you should call
5543 "guestfs_part_add" for each partition required.
5544 Possible values for "parttype" are:
5546 efi | gpt
5548 Intel EFI / GPT partition table.
5549 This is recommended for >= 2 TB partitions that will be accessed
5551 from Linux and Intel-based Mac OS X. It also has limited backwards
5552 compatibility with the "mbr" format.
5553 mbr | msdos
5555 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
5556 and Windows. This partition type will only work for device sizes
5557 up to 2 TB. For large disks we recommend using "gpt".
5558 Other partition table types that may work but are not supported
5560 include:
5561 aix AIX disk labels.
5563 amiga | rdb
5565 Amiga "Rigid Disk Block" format.
5566 bsd BSD disk labels.
5568 dasd
5570 DASD, used on IBM mainframes.
5571 dvh MIPS/SGI volumes.
5573 mac Old Mac partition format. Modern Macs use "gpt".
5575 pc98
5577 NEC PC-98 format, common in Japan apparently.
5578 sun Sun disk labels.
5580 This function returns 0 on success or -1 on error.
5582 (Added in 1.0.78)
5584 guestfs_part_list
5586 struct guestfs_partition_list *
5587 guestfs_part_list (guestfs_h *g,
5588 const char *device);
5589 This command parses the partition table on "device" and returns the
5591 list of partitions found.
5592 The fields in the returned structure are:
5594 part_num
5596 Partition number, counting from 1.
5597 part_start
5599 Start of the partition in bytes. To get sectors you have to divide
5600 by the device's sector size, see "guestfs_blockdev_getss".
5601 part_end
5603 End of the partition in bytes.
5604 part_size
5606 Size of the partition in bytes.
5607 This function returns a "struct guestfs_partition_list *", or NULL if
5609 there was an error. The caller must call "guestfs_free_partition_list"
5610 after use.
5611 (Added in 1.0.78)
5613 guestfs_part_set_bootable
5615 int
5616 guestfs_part_set_bootable (guestfs_h *g,
5617 const char *device,
5618 int partnum,
5619 int bootable);
5620 This sets the bootable flag on partition numbered "partnum" on device
5622 "device". Note that partitions are numbered from 1.
5623 The bootable flag is used by some operating systems (notably Windows)
5625 to determine which partition to boot from. It is by no means
5626 universally recognized.
5627 This function returns 0 on success or -1 on error.
5629 (Added in 1.0.78)
5631 guestfs_part_set_mbr_id
5633 int
5634 guestfs_part_set_mbr_id (guestfs_h *g,
5635 const char *device,
5636 int partnum,
5637 int idbyte);
5638 Sets the MBR type byte (also known as the ID byte) of the numbered
5640 partition "partnum" to "idbyte". Note that the type bytes quoted in
5641 most documentation are in fact hexadecimal numbers, but usually
5642 documented without any leading "0x" which might be confusing.
5643 Note that only MBR (old DOS-style) partitions have type bytes. You
5645 will get undefined results for other partition table types (see
5646 "guestfs_part_get_parttype").
5647 This function returns 0 on success or -1 on error.
5649 (Added in 1.3.2)
5651 guestfs_part_set_name
5653 int
5654 guestfs_part_set_name (guestfs_h *g,
5655 const char *device,
5656 int partnum,
5657 const char *name);
5658 This sets the partition name on partition numbered "partnum" on device
5660 "device". Note that partitions are numbered from 1.
5661 The partition name can only be set on certain types of partition table.
5663 This works on "gpt" but not on "mbr" partitions.
5664 This function returns 0 on success or -1 on error.
5666 (Added in 1.0.78)
5668 guestfs_part_to_dev
5670 char *
5671 guestfs_part_to_dev (guestfs_h *g,
5672 const char *partition);
5673 This function takes a partition name (eg. "/dev/sdb1") and removes the
5675 partition number, returning the device name (eg. "/dev/sdb").
5676 The named partition must exist, for example as a string returned from
5678 "guestfs_list_partitions".
5679 This function returns a string, or NULL on error. The caller must free
5681 the returned string after use.
5682 (Added in 1.5.15)
5684 guestfs_ping_daemon
5686 int
5687 guestfs_ping_daemon (guestfs_h *g);
5688 This is a test probe into the guestfs daemon running inside the qemu
5690 subprocess. Calling this function checks that the daemon responds to
5691 the ping message, without affecting the daemon or attached block
5692 device(s) in any other way.
5693 This function returns 0 on success or -1 on error.
5695 (Added in 1.0.18)
5697 guestfs_pread
5699 char *
5700 guestfs_pread (guestfs_h *g,
5701 const char *path,
5702 int count,
5703 int64_t offset,
5704 size_t *size_r);
5705 This command lets you read part of a file. It reads "count" bytes of
5707 the file, starting at "offset", from file "path".
5708 This may read fewer bytes than requested. For further details see the
5710 pread(2) system call.
5711 See also "guestfs_pwrite", "guestfs_pread_device".
5713 This function returns a buffer, or NULL on error. The size of the
5715 returned buffer is written to *size_r. The caller must free the
5716 returned buffer after use.
5717 Because of the message protocol, there is a transfer limit of somewhere
5719 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5720 (Added in 1.0.77)
5722 guestfs_pread_device
5724 char *
5725 guestfs_pread_device (guestfs_h *g,
5726 const char *device,
5727 int count,
5728 int64_t offset,
5729 size_t *size_r);
5730 This command lets you read part of a file. It reads "count" bytes of
5732 "device", starting at "offset".
5733 This may read fewer bytes than requested. For further details see the
5735 pread(2) system call.
5736 See also "guestfs_pread".
5738 This function returns a buffer, or NULL on error. The size of the
5740 returned buffer is written to *size_r. The caller must free the
5741 returned buffer after use.
5742 Because of the message protocol, there is a transfer limit of somewhere
5744 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5745 (Added in 1.5.21)
5747 guestfs_pvcreate
5749 int
5750 guestfs_pvcreate (guestfs_h *g,
5751 const char *device);
5752 This creates an LVM physical volume on the named "device", where
5754 "device" should usually be a partition name such as "/dev/sda1".
5755 This function returns 0 on success or -1 on error.
5757 (Added in 0.8)
5759 guestfs_pvremove
5761 int
5762 guestfs_pvremove (guestfs_h *g,
5763 const char *device);
5764 This wipes a physical volume "device" so that LVM will no longer
5766 recognise it.
5767 The implementation uses the "pvremove" command which refuses to wipe
5769 physical volumes that contain any volume groups, so you have to remove
5770 those first.
5771 This function returns 0 on success or -1 on error.
5773 (Added in 1.0.13)
5775 guestfs_pvresize
5777 int
5778 guestfs_pvresize (guestfs_h *g,
5779 const char *device);
5780 This resizes (expands or shrinks) an existing LVM physical volume to
5782 match the new size of the underlying device.
5783 This function returns 0 on success or -1 on error.
5785 (Added in 1.0.26)
5787 guestfs_pvresize_size
5789 int
5790 guestfs_pvresize_size (guestfs_h *g,
5791 const char *device,
5792 int64_t size);
5793 This command is the same as "guestfs_pvresize" except that it allows
5795 you to specify the new size (in bytes) explicitly.
5796 This function returns 0 on success or -1 on error.
5798 (Added in 1.3.14)
5800 guestfs_pvs
5802 char **
5803 guestfs_pvs (guestfs_h *g);
5804 List all the physical volumes detected. This is the equivalent of the
5806 pvs(8) command.
5807 This returns a list of just the device names that contain PVs (eg.
5809 "/dev/sda2").
5810 See also "guestfs_pvs_full".
5812 This function returns a NULL-terminated array of strings (like
5814 environ(3)), or NULL if there was an error. The caller must free the
5815 strings and the array after use.
5816 (Added in 0.4)
5818 guestfs_pvs_full
5820 struct guestfs_lvm_pv_list *
5821 guestfs_pvs_full (guestfs_h *g);
5822 List all the physical volumes detected. This is the equivalent of the
5824 pvs(8) command. The "full" version includes all fields.
5825 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
5827 there was an error. The caller must call "guestfs_free_lvm_pv_list"
5828 after use.
5829 (Added in 0.4)
5831 guestfs_pvuuid
5833 char *
5834 guestfs_pvuuid (guestfs_h *g,
5835 const char *device);
5836 This command returns the UUID of the LVM PV "device".
5838 This function returns a string, or NULL on error. The caller must free
5840 the returned string after use.
5841 (Added in 1.0.87)
5843 guestfs_pwrite
5845 int
5846 guestfs_pwrite (guestfs_h *g,
5847 const char *path,
5848 const char *content,
5849 size_t content_size,
5850 int64_t offset);
5851 This command writes to part of a file. It writes the data buffer
5853 "content" to the file "path" starting at offset "offset".
5854 This command implements the pwrite(2) system call, and like that system
5856 call it may not write the full data requested. The return value is the
5857 number of bytes that were actually written to the file. This could
5858 even be 0, although short writes are unlikely for regular files in
5859 ordinary circumstances.
5860 See also "guestfs_pread", "guestfs_pwrite_device".
5862 On error this function returns -1.
5864 Because of the message protocol, there is a transfer limit of somewhere
5866 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5867 (Added in 1.3.14)
5869 guestfs_pwrite_device
5871 int
5872 guestfs_pwrite_device (guestfs_h *g,
5873 const char *device,
5874 const char *content,
5875 size_t content_size,
5876 int64_t offset);
5877 This command writes to part of a device. It writes the data buffer
5879 "content" to "device" starting at offset "offset".
5880 This command implements the pwrite(2) system call, and like that system
5882 call it may not write the full data requested (although short writes to
5883 disk devices and partitions are probably impossible with standard Linux
5884 kernels).
5885 See also "guestfs_pwrite".
5887 On error this function returns -1.
5889 Because of the message protocol, there is a transfer limit of somewhere
5891 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5892 (Added in 1.5.20)
5894 guestfs_read_file
5896 char *
5897 guestfs_read_file (guestfs_h *g,
5898 const char *path,
5899 size_t *size_r);
5900 This calls returns the contents of the file "path" as a buffer.
5902 Unlike "guestfs_cat", this function can correctly handle files that
5904 contain embedded ASCII NUL characters. However unlike
5905 "guestfs_download", this function is limited in the total size of file
5906 that can be handled.
5907 This function returns a buffer, or NULL on error. The size of the
5909 returned buffer is written to *size_r. The caller must free the
5910 returned buffer after use.
5911 Because of the message protocol, there is a transfer limit of somewhere
5913 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5914 (Added in 1.0.63)
5916 guestfs_read_lines
5918 char **
5919 guestfs_read_lines (guestfs_h *g,
5920 const char *path);
5921 Return the contents of the file named "path".
5923 The file contents are returned as a list of lines. Trailing "LF" and
5925 "CRLF" character sequences are not returned.
5926 Note that this function cannot correctly handle binary files
5928 (specifically, files containing "\0" character which is treated as end
5929 of line). For those you need to use the "guestfs_read_file" function
5930 which has a more complex interface.
5931 This function returns a NULL-terminated array of strings (like
5933 environ(3)), or NULL if there was an error. The caller must free the
5934 strings and the array after use.
5935 (Added in 0.7)
5937 guestfs_readdir
5939 struct guestfs_dirent_list *
5940 guestfs_readdir (guestfs_h *g,
5941 const char *dir);
5942 This returns the list of directory entries in directory "dir".
5944 All entries in the directory are returned, including "." and "..". The
5946 entries are not sorted, but returned in the same order as the
5947 underlying filesystem.
5948 Also this call returns basic file type information about each file.
5950 The "ftyp" field will contain one of the following characters:
5951 'b' Block special
5953 'c' Char special
5955 'd' Directory
5957 'f' FIFO (named pipe)
5959 'l' Symbolic link
5961 'r' Regular file
5963 's' Socket
5965 'u' Unknown file type
5967 '?' The readdir(3) call returned a "d_type" field with an unexpected
5969 value
5970 This function is primarily intended for use by programs. To get a
5972 simple list of names, use "guestfs_ls". To get a printable directory
5973 for human consumption, use "guestfs_ll".
5974 This function returns a "struct guestfs_dirent_list *", or NULL if
5976 there was an error. The caller must call "guestfs_free_dirent_list"
5977 after use.
5978 (Added in 1.0.55)
5980 guestfs_readlink
5982 char *
5983 guestfs_readlink (guestfs_h *g,
5984 const char *path);
5985 This command reads the target of a symbolic link.
5987 This function returns a string, or NULL on error. The caller must free
5989 the returned string after use.
5990 (Added in 1.0.66)
5992 guestfs_readlinklist
5994 char **
5995 guestfs_readlinklist (guestfs_h *g,
5996 const char *path,
5997 char *const *names);
5998 This call allows you to do a "readlink" operation on multiple files,
6000 where all files are in the directory "path". "names" is the list of
6001 files from this directory.
6002 On return you get a list of strings, with a one-to-one correspondence
6004 to the "names" list. Each string is the value of the symbolic link.
6005 If the readlink(2) operation fails on any name, then the corresponding
6007 result string is the empty string "". However the whole operation is
6008 completed even if there were readlink(2) errors, and so you can call
6009 this function with names where you don't know if they are symbolic
6010 links already (albeit slightly less efficient).
6011 This call is intended for programs that want to efficiently list a
6013 directory contents without making many round-trips. Very long
6014 directory listings might cause the protocol message size to be
6015 exceeded, causing this call to fail. The caller must split up such
6016 requests into smaller groups of names.
6017 This function returns a NULL-terminated array of strings (like
6019 environ(3)), or NULL if there was an error. The caller must free the
6020 strings and the array after use.
6021 (Added in 1.0.77)
6023 guestfs_realpath
6025 char *
6026 guestfs_realpath (guestfs_h *g,
6027 const char *path);
6028 Return the canonicalized absolute pathname of "path". The returned
6030 path has no ".", ".." or symbolic link path elements.
6031 This function returns a string, or NULL on error. The caller must free
6033 the returned string after use.
6034 (Added in 1.0.66)
6036 guestfs_removexattr
6038 int
6039 guestfs_removexattr (guestfs_h *g,
6040 const char *xattr,
6041 const char *path);
6042 This call removes the extended attribute named "xattr" of the file
6044 "path".
6045 See also: "guestfs_lremovexattr", attr(5).
6047 This function returns 0 on success or -1 on error.
6049 (Added in 1.0.59)
6051 guestfs_resize2fs
6053 int
6054 guestfs_resize2fs (guestfs_h *g,
6055 const char *device);
6056 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
6058 underlying device.
6059 Note: It is sometimes required that you run "guestfs_e2fsck_f" on the
6061 "device" before calling this command. For unknown reasons "resize2fs"
6062 sometimes gives an error about this and sometimes not. In any case, it
6063 is always safe to call "guestfs_e2fsck_f" before calling this function.
6064 This function returns 0 on success or -1 on error.
6066 (Added in 1.0.27)
6068 guestfs_resize2fs_size
6070 int
6071 guestfs_resize2fs_size (guestfs_h *g,
6072 const char *device,
6073 int64_t size);
6074 This command is the same as "guestfs_resize2fs" except that it allows
6076 you to specify the new size (in bytes) explicitly.
6077 This function returns 0 on success or -1 on error.
6079 (Added in 1.3.14)
6081 guestfs_rm
6083 int
6084 guestfs_rm (guestfs_h *g,
6085 const char *path);
6086 Remove the single file "path".
6088 This function returns 0 on success or -1 on error.
6090 (Added in 0.8)
6092 guestfs_rm_rf
6094 int
6095 guestfs_rm_rf (guestfs_h *g,
6096 const char *path);
6097 Remove the file or directory "path", recursively removing the contents
6099 if its a directory. This is like the "rm -rf" shell command.
6100 This function returns 0 on success or -1 on error.
6102 (Added in 0.8)
6104 guestfs_rmdir
6106 int
6107 guestfs_rmdir (guestfs_h *g,
6108 const char *path);
6109 Remove the single directory "path".
6111 This function returns 0 on success or -1 on error.
6113 (Added in 0.8)
6115 guestfs_rmmountpoint
6117 int
6118 guestfs_rmmountpoint (guestfs_h *g,
6119 const char *exemptpath);
6120 This calls removes a mountpoint that was previously created with
6122 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
6123 This function returns 0 on success or -1 on error.
6125 (Added in 1.0.62)
6127 guestfs_scrub_device
6129 int
6130 guestfs_scrub_device (guestfs_h *g,
6131 const char *device);
6132 This command writes patterns over "device" to make data retrieval more
6134 difficult.
6135 It is an interface to the scrub(1) program. See that manual page for
6137 more details.
6138 This function returns 0 on success or -1 on error.
6140 This command is dangerous. Without careful use you can easily destroy
6142 all your data.
6143 (Added in 1.0.52)
6145 guestfs_scrub_file
6147 int
6148 guestfs_scrub_file (guestfs_h *g,
6149 const char *file);
6150 This command writes patterns over a file to make data retrieval more
6152 difficult.
6153 The file is removed after scrubbing.
6155 It is an interface to the scrub(1) program. See that manual page for
6157 more details.
6158 This function returns 0 on success or -1 on error.
6160 (Added in 1.0.52)
6162 guestfs_scrub_freespace
6164 int
6165 guestfs_scrub_freespace (guestfs_h *g,
6166 const char *dir);
6167 This command creates the directory "dir" and then fills it with files
6169 until the filesystem is full, and scrubs the files as for
6170 "guestfs_scrub_file", and deletes them. The intention is to scrub any
6171 free space on the partition containing "dir".
6172 It is an interface to the scrub(1) program. See that manual page for
6174 more details.
6175 This function returns 0 on success or -1 on error.
6177 (Added in 1.0.52)
6179 guestfs_set_append
6181 int
6182 guestfs_set_append (guestfs_h *g,
6183 const char *append);
6184 This function is used to add additional options to the guest kernel
6186 command line.
6187 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
6189 environment variable.
6190 Setting "append" to "NULL" means no additional options are passed
6192 (libguestfs always adds a few of its own).
6193 This function returns 0 on success or -1 on error.
6195 (Added in 1.0.26)
6197 guestfs_set_autosync
6199 int
6200 guestfs_set_autosync (guestfs_h *g,
6201 int autosync);
6202 If "autosync" is true, this enables autosync. Libguestfs will make a
6204 best effort attempt to run "guestfs_umount_all" followed by
6205 "guestfs_sync" when the handle is closed (also if the program exits
6206 without closing handles).
6207 This is enabled by default (since libguestfs 1.5.24, previously it was
6209 disabled by default).
6210 This function returns 0 on success or -1 on error.
6212 (Added in 0.3)
6214 guestfs_set_direct
6216 int
6217 guestfs_set_direct (guestfs_h *g,
6218 int direct);
6219 If the direct appliance mode flag is enabled, then stdin and stdout are
6221 passed directly through to the appliance once it is launched.
6222 One consequence of this is that log messages aren't caught by the
6224 library and handled by "guestfs_set_log_message_callback", but go
6225 straight to stdout.
6226 You probably don't want to use this unless you know what you are doing.
6228 The default is disabled.
6230 This function returns 0 on success or -1 on error.
6232 (Added in 1.0.72)
6234 guestfs_set_e2label
6236 int
6237 guestfs_set_e2label (guestfs_h *g,
6238 const char *device,
6239 const char *label);
6240 This sets the ext2/3/4 filesystem label of the filesystem on "device"
6242 to "label". Filesystem labels are limited to 16 characters.
6243 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
6245 return the existing label on a filesystem.
6246 This function returns 0 on success or -1 on error.
6248 (Added in 1.0.15)
6250 guestfs_set_e2uuid
6252 int
6253 guestfs_set_e2uuid (guestfs_h *g,
6254 const char *device,
6255 const char *uuid);
6256 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
6258 "uuid". The format of the UUID and alternatives such as "clear",
6259 "random" and "time" are described in the tune2fs(8) manpage.
6260 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2uuid" to
6262 return the existing UUID of a filesystem.
6263 This function returns 0 on success or -1 on error.
6265 (Added in 1.0.15)
6267 guestfs_set_memsize
6269 int
6270 guestfs_set_memsize (guestfs_h *g,
6271 int memsize);
6272 This sets the memory size in megabytes allocated to the qemu
6274 subprocess. This only has any effect if called before
6275 "guestfs_launch".
6276 You can also change this by setting the environment variable
6278 "LIBGUESTFS_MEMSIZE" before the handle is created.
6279 For more information on the architecture of libguestfs, see guestfs(3).
6281 This function returns 0 on success or -1 on error.
6283 (Added in 1.0.55)
6285 guestfs_set_network
6287 int
6288 guestfs_set_network (guestfs_h *g,
6289 int network);
6290 If "network" is true, then the network is enabled in the libguestfs
6292 appliance. The default is false.
6293 This affects whether commands are able to access the network (see
6295 "RUNNING COMMANDS" in guestfs(3)).
6296 You must call this before calling "guestfs_launch", otherwise it has no
6298 effect.
6299 This function returns 0 on success or -1 on error.
6301 (Added in 1.5.4)
6303 guestfs_set_path
6305 int
6306 guestfs_set_path (guestfs_h *g,
6307 const char *searchpath);
6308 Set the path that libguestfs searches for kernel and initrd.img.
6310 The default is "$libdir/guestfs" unless overridden by setting
6312 "LIBGUESTFS_PATH" environment variable.
6313 Setting "path" to "NULL" restores the default path.
6315 This function returns 0 on success or -1 on error.
6317 (Added in 0.3)
6319 guestfs_set_qemu
6321 int
6322 guestfs_set_qemu (guestfs_h *g,
6323 const char *qemu);
6324 Set the qemu binary that we will use.
6326 The default is chosen when the library was compiled by the configure
6328 script.
6329 You can also override this by setting the "LIBGUESTFS_QEMU" environment
6331 variable.
6332 Setting "qemu" to "NULL" restores the default qemu binary.
6334 Note that you should call this function as early as possible after
6336 creating the handle. This is because some pre-launch operations depend
6337 on testing qemu features (by running "qemu -help"). If the qemu binary
6338 changes, we don't retest features, and so you might see inconsistent
6339 results. Using the environment variable "LIBGUESTFS_QEMU" is safest of
6340 all since that picks the qemu binary at the same time as the handle is
6341 created.
6342 This function returns 0 on success or -1 on error.
6344 (Added in 1.0.6)
6346 guestfs_set_recovery_proc
6348 int
6349 guestfs_set_recovery_proc (guestfs_h *g,
6350 int recoveryproc);
6351 If this is called with the parameter "false" then "guestfs_launch" does
6353 not create a recovery process. The purpose of the recovery process is
6354 to stop runaway qemu processes in the case where the main program
6355 aborts abruptly.
6356 This only has any effect if called before "guestfs_launch", and the
6358 default is true.
6359 About the only time when you would want to disable this is if the main
6361 process will fork itself into the background ("daemonize" itself). In
6362 this case the recovery process thinks that the main program has
6363 disappeared and so kills qemu, which is not very helpful.
6364 This function returns 0 on success or -1 on error.
6366 (Added in 1.0.77)
6368 guestfs_set_selinux
6370 int
6371 guestfs_set_selinux (guestfs_h *g,
6372 int selinux);
6373 This sets the selinux flag that is passed to the appliance at boot
6375 time. The default is "selinux=0" (disabled).
6376 Note that if SELinux is enabled, it is always in Permissive mode
6378 ("enforcing=0").
6379 For more information on the architecture of libguestfs, see guestfs(3).
6381 This function returns 0 on success or -1 on error.
6383 (Added in 1.0.67)
6385 guestfs_set_trace
6387 int
6388 guestfs_set_trace (guestfs_h *g,
6389 int trace);
6390 If the command trace flag is set to 1, then commands are printed on
6392 stderr before they are executed in a format which is very similar to
6393 the one used by guestfish. In other words, you can run a program with
6394 this enabled, and you will get out a script which you can feed to
6395 guestfish to perform the same set of actions.
6396 If you want to trace C API calls into libguestfs (and other libraries)
6398 then possibly a better way is to use the external ltrace(1) command.
6399 Command traces are disabled unless the environment variable
6401 "LIBGUESTFS_TRACE" is defined and set to 1.
6402 This function returns 0 on success or -1 on error.
6404 (Added in 1.0.69)
6406 guestfs_set_verbose
6408 int
6409 guestfs_set_verbose (guestfs_h *g,
6410 int verbose);
6411 If "verbose" is true, this turns on verbose messages (to "stderr").
6413 Verbose messages are disabled unless the environment variable
6415 "LIBGUESTFS_DEBUG" is defined and set to 1.
6416 This function returns 0 on success or -1 on error.
6418 (Added in 0.3)
6420 guestfs_setcon
6422 int
6423 guestfs_setcon (guestfs_h *g,
6424 const char *context);
6425 This sets the SELinux security context of the daemon to the string
6427 "context".
6428 See the documentation about SELINUX in guestfs(3).
6430 This function returns 0 on success or -1 on error.
6432 (Added in 1.0.67)
6434 guestfs_setxattr
6436 int
6437 guestfs_setxattr (guestfs_h *g,
6438 const char *xattr,
6439 const char *val,
6440 int vallen,
6441 const char *path);
6442 This call sets the extended attribute named "xattr" of the file "path"
6444 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
6445 data.
6446 See also: "guestfs_lsetxattr", attr(5).
6448 This function returns 0 on success or -1 on error.
6450 (Added in 1.0.59)
6452 guestfs_sfdisk
6454 int
6455 guestfs_sfdisk (guestfs_h *g,
6456 const char *device,
6457 int cyls,
6458 int heads,
6459 int sectors,
6460 char *const *lines);
6461 This is a direct interface to the sfdisk(8) program for creating
6463 partitions on block devices.
6464 "device" should be a block device, for example "/dev/sda".
6466 "cyls", "heads" and "sectors" are the number of cylinders, heads and
6468 sectors on the device, which are passed directly to sfdisk as the -C,
6469 -H and -S parameters. If you pass 0 for any of these, then the
6470 corresponding parameter is omitted. Usually for 'large' disks, you can
6471 just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or
6472 rather, the kernel) cannot work out the right geometry and you will
6473 need to tell it.
6474 "lines" is a list of lines that we feed to "sfdisk". For more
6476 information refer to the sfdisk(8) manpage.
6477 To create a single partition occupying the whole disk, you would pass
6479 "lines" as a single element list, when the single element being the
6480 string "," (comma).
6481 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
6483 This function returns 0 on success or -1 on error.
6485 This command is dangerous. Without careful use you can easily destroy
6487 all your data.
6488 (Added in 0.8)
6490 guestfs_sfdiskM
6492 int
6493 guestfs_sfdiskM (guestfs_h *g,
6494 const char *device,
6495 char *const *lines);
6496 This is a simplified interface to the "guestfs_sfdisk" command, where
6498 partition sizes are specified in megabytes only (rounded to the nearest
6499 cylinder) and you don't need to specify the cyls, heads and sectors
6500 parameters which were rarely if ever used anyway.
6501 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
6503 "guestfs_part_disk"
6504 This function returns 0 on success or -1 on error.
6506 This command is dangerous. Without careful use you can easily destroy
6508 all your data.
6509 (Added in 1.0.55)
6511 guestfs_sfdisk_N
6513 int
6514 guestfs_sfdisk_N (guestfs_h *g,
6515 const char *device,
6516 int partnum,
6517 int cyls,
6518 int heads,
6519 int sectors,
6520 const char *line);
6521 This runs sfdisk(8) option to modify just the single partition "n"
6523 (note: "n" counts from 1).
6524 For other parameters, see "guestfs_sfdisk". You should usually pass 0
6526 for the cyls/heads/sectors parameters.
6527 See also: "guestfs_part_add"
6529 This function returns 0 on success or -1 on error.
6531 This command is dangerous. Without careful use you can easily destroy
6533 all your data.
6534 (Added in 1.0.26)
6536 guestfs_sfdisk_disk_geometry
6538 char *
6539 guestfs_sfdisk_disk_geometry (guestfs_h *g,
6540 const char *device);
6541 This displays the disk geometry of "device" read from the partition
6543 table. Especially in the case where the underlying block device has
6544 been resized, this can be different from the kernel's idea of the
6545 geometry (see "guestfs_sfdisk_kernel_geometry").
6546 The result is in human-readable format, and not designed to be parsed.
6548 This function returns a string, or NULL on error. The caller must free
6550 the returned string after use.
6551 (Added in 1.0.26)
6553 guestfs_sfdisk_kernel_geometry
6555 char *
6556 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
6557 const char *device);
6558 This displays the kernel's idea of the geometry of "device".
6560 The result is in human-readable format, and not designed to be parsed.
6562 This function returns a string, or NULL on error. The caller must free
6564 the returned string after use.
6565 (Added in 1.0.26)
6567 guestfs_sfdisk_l
6569 char *
6570 guestfs_sfdisk_l (guestfs_h *g,
6571 const char *device);
6572 This displays the partition table on "device", in the human-readable
6574 output of the sfdisk(8) command. It is not intended to be parsed.
6575 See also: "guestfs_part_list"
6577 This function returns a string, or NULL on error. The caller must free
6579 the returned string after use.
6580 (Added in 1.0.26)
6582 guestfs_sh
6584 char *
6585 guestfs_sh (guestfs_h *g,
6586 const char *command);
6587 This call runs a command from the guest filesystem via the guest's
6589 "/bin/sh".
6590 This is like "guestfs_command", but passes the command to:
6592 /bin/sh -c "command"
6594 Depending on the guest's shell, this usually results in wildcards being
6596 expanded, shell expressions being interpolated and so on.
6597 All the provisos about "guestfs_command" apply to this call.
6599 This function returns a string, or NULL on error. The caller must free
6601 the returned string after use.
6602 (Added in 1.0.50)
6604 guestfs_sh_lines
6606 char **
6607 guestfs_sh_lines (guestfs_h *g,
6608 const char *command);
6609 This is the same as "guestfs_sh", but splits the result into a list of
6611 lines.
6612 See also: "guestfs_command_lines"
6614 This function returns a NULL-terminated array of strings (like
6616 environ(3)), or NULL if there was an error. The caller must free the
6617 strings and the array after use.
6618 (Added in 1.0.50)
6620 guestfs_sleep
6622 int
6623 guestfs_sleep (guestfs_h *g,
6624 int secs);
6625 Sleep for "secs" seconds.
6627 This function returns 0 on success or -1 on error.
6629 (Added in 1.0.41)
6631 guestfs_stat
6633 struct guestfs_stat *
6634 guestfs_stat (guestfs_h *g,
6635 const char *path);
6636 Returns file information for the given "path".
6638 This is the same as the stat(2) system call.
6640 This function returns a "struct guestfs_stat *", or NULL if there was
6642 an error. The caller must call "guestfs_free_stat" after use.
6643 (Added in 0.9.2)
6645 guestfs_statvfs
6647 struct guestfs_statvfs *
6648 guestfs_statvfs (guestfs_h *g,
6649 const char *path);
6650 Returns file system statistics for any mounted file system. "path"
6652 should be a file or directory in the mounted file system (typically it
6653 is the mount point itself, but it doesn't need to be).
6654 This is the same as the statvfs(2) system call.
6656 This function returns a "struct guestfs_statvfs *", or NULL if there
6658 was an error. The caller must call "guestfs_free_statvfs" after use.
6659 (Added in 0.9.2)
6661 guestfs_strings
6663 char **
6664 guestfs_strings (guestfs_h *g,
6665 const char *path);
6666 This runs the strings(1) command on a file and returns the list of
6668 printable strings found.
6669 This function returns a NULL-terminated array of strings (like
6671 environ(3)), or NULL if there was an error. The caller must free the
6672 strings and the array after use.
6673 Because of the message protocol, there is a transfer limit of somewhere
6675 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
6676 (Added in 1.0.22)
6678 guestfs_strings_e
6680 char **
6681 guestfs_strings_e (guestfs_h *g,
6682 const char *encoding,
6683 const char *path);
6684 This is like the "guestfs_strings" command, but allows you to specify
6686 the encoding of strings that are looked for in the source file "path".
6687 Allowed encodings are:
6689 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
6691 parts of ISO-8859-X (this is what "guestfs_strings" uses).
6692 S Single 8-bit-byte characters.
6694 b 16-bit big endian strings such as those encoded in UTF-16BE or
6696 UCS-2BE.
6697 l (lower case letter L)
6699 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
6700 for examining binaries in Windows guests.
6701 B 32-bit big endian such as UCS-4BE.
6703 L 32-bit little endian such as UCS-4LE.
6705 The returned strings are transcoded to UTF-8.
6707 This function returns a NULL-terminated array of strings (like
6709 environ(3)), or NULL if there was an error. The caller must free the
6710 strings and the array after use.
6711 Because of the message protocol, there is a transfer limit of somewhere
6713 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
6714 (Added in 1.0.22)
6716 guestfs_swapoff_device
6718 int
6719 guestfs_swapoff_device (guestfs_h *g,
6720 const char *device);
6721 This command disables the libguestfs appliance swap device or partition
6723 named "device". See "guestfs_swapon_device".
6724 This function returns 0 on success or -1 on error.
6726 (Added in 1.0.66)
6728 guestfs_swapoff_file
6730 int
6731 guestfs_swapoff_file (guestfs_h *g,
6732 const char *file);
6733 This command disables the libguestfs appliance swap on file.
6735 This function returns 0 on success or -1 on error.
6737 (Added in 1.0.66)
6739 guestfs_swapoff_label
6741 int
6742 guestfs_swapoff_label (guestfs_h *g,
6743 const char *label);
6744 This command disables the libguestfs appliance swap on labeled swap
6746 partition.
6747 This function returns 0 on success or -1 on error.
6749 (Added in 1.0.66)
6751 guestfs_swapoff_uuid
6753 int
6754 guestfs_swapoff_uuid (guestfs_h *g,
6755 const char *uuid);
6756 This command disables the libguestfs appliance swap partition with the
6758 given UUID.
6759 This function returns 0 on success or -1 on error.
6761 (Added in 1.0.66)
6763 guestfs_swapon_device
6765 int
6766 guestfs_swapon_device (guestfs_h *g,
6767 const char *device);
6768 This command enables the libguestfs appliance to use the swap device or
6770 partition named "device". The increased memory is made available for
6771 all commands, for example those run using "guestfs_command" or
6772 "guestfs_sh".
6773 Note that you should not swap to existing guest swap partitions unless
6775 you know what you are doing. They may contain hibernation information,
6776 or other information that the guest doesn't want you to trash. You
6777 also risk leaking information about the host to the guest this way.
6778 Instead, attach a new host device to the guest and swap on that.
6779 This function returns 0 on success or -1 on error.
6781 (Added in 1.0.66)
6783 guestfs_swapon_file
6785 int
6786 guestfs_swapon_file (guestfs_h *g,
6787 const char *file);
6788 This command enables swap to a file. See "guestfs_swapon_device" for
6790 other notes.
6791 This function returns 0 on success or -1 on error.
6793 (Added in 1.0.66)
6795 guestfs_swapon_label
6797 int
6798 guestfs_swapon_label (guestfs_h *g,
6799 const char *label);
6800 This command enables swap to a labeled swap partition. See
6802 "guestfs_swapon_device" for other notes.
6803 This function returns 0 on success or -1 on error.
6805 (Added in 1.0.66)
6807 guestfs_swapon_uuid
6809 int
6810 guestfs_swapon_uuid (guestfs_h *g,
6811 const char *uuid);
6812 This command enables swap to a swap partition with the given UUID. See
6814 "guestfs_swapon_device" for other notes.
6815 This function returns 0 on success or -1 on error.
6817 (Added in 1.0.66)
6819 guestfs_sync
6821 int
6822 guestfs_sync (guestfs_h *g);
6823 This syncs the disk, so that any writes are flushed through to the
6825 underlying disk image.
6826 You should always call this if you have modified a disk image, before
6828 closing the handle.
6829 This function returns 0 on success or -1 on error.
6831 (Added in 0.3)
6833 guestfs_tail
6835 char **
6836 guestfs_tail (guestfs_h *g,
6837 const char *path);
6838 This command returns up to the last 10 lines of a file as a list of
6840 strings.
6841 This function returns a NULL-terminated array of strings (like
6843 environ(3)), or NULL if there was an error. The caller must free the
6844 strings and the array after use.
6845 Because of the message protocol, there is a transfer limit of somewhere
6847 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
6848 (Added in 1.0.54)
6850 guestfs_tail_n
6852 char **
6853 guestfs_tail_n (guestfs_h *g,
6854 int nrlines,
6855 const char *path);
6856 If the parameter "nrlines" is a positive number, this returns the last
6858 "nrlines" lines of the file "path".
6859 If the parameter "nrlines" is a negative number, this returns lines
6861 from the file "path", starting with the "-nrlines"th line.
6862 If the parameter "nrlines" is zero, this returns an empty list.
6864 This function returns a NULL-terminated array of strings (like
6866 environ(3)), or NULL if there was an error. The caller must free the
6867 strings and the array after use.
6868 Because of the message protocol, there is a transfer limit of somewhere
6870 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
6871 (Added in 1.0.54)
6873 guestfs_tar_in
6875 int
6876 guestfs_tar_in (guestfs_h *g,
6877 const char *tarfile,
6878 const char *directory);
6879 This command uploads and unpacks local file "tarfile" (an uncompressed
6881 tar file) into "directory".
6882 To upload a compressed tarball, use "guestfs_tgz_in" or
6884 "guestfs_txz_in".
6885 This function returns 0 on success or -1 on error.
6887 (Added in 1.0.3)
6889 guestfs_tar_out
6891 int
6892 guestfs_tar_out (guestfs_h *g,
6893 const char *directory,
6894 const char *tarfile);
6895 This command packs the contents of "directory" and downloads it to
6897 local file "tarfile".
6898 To download a compressed tarball, use "guestfs_tgz_out" or
6900 "guestfs_txz_out".
6901 This function returns 0 on success or -1 on error.
6903 (Added in 1.0.3)
6905 guestfs_tgz_in
6907 int
6908 guestfs_tgz_in (guestfs_h *g,
6909 const char *tarball,
6910 const char *directory);
6911 This command uploads and unpacks local file "tarball" (a gzip
6913 compressed tar file) into "directory".
6914 To upload an uncompressed tarball, use "guestfs_tar_in".
6916 This function returns 0 on success or -1 on error.
6918 (Added in 1.0.3)
6920 guestfs_tgz_out
6922 int
6923 guestfs_tgz_out (guestfs_h *g,
6924 const char *directory,
6925 const char *tarball);
6926 This command packs the contents of "directory" and downloads it to
6928 local file "tarball".
6929 To download an uncompressed tarball, use "guestfs_tar_out".
6931 This function returns 0 on success or -1 on error.
6933 (Added in 1.0.3)
6935 guestfs_touch
6937 int
6938 guestfs_touch (guestfs_h *g,
6939 const char *path);
6940 Touch acts like the touch(1) command. It can be used to update the
6942 timestamps on a file, or, if the file does not exist, to create a new
6943 zero-length file.
6944 This command only works on regular files, and will fail on other file
6946 types such as directories, symbolic links, block special etc.
6947 This function returns 0 on success or -1 on error.
6949 (Added in 0.3)
6951 guestfs_truncate
6953 int
6954 guestfs_truncate (guestfs_h *g,
6955 const char *path);
6956 This command truncates "path" to a zero-length file. The file must
6958 exist already.
6959 This function returns 0 on success or -1 on error.
6961 (Added in 1.0.77)
6963 guestfs_truncate_size
6965 int
6966 guestfs_truncate_size (guestfs_h *g,
6967 const char *path,
6968 int64_t size);
6969 This command truncates "path" to size "size" bytes. The file must
6971 exist already.
6972 If the current file size is less than "size" then the file is extended
6974 to the required size with zero bytes. This creates a sparse file (ie.
6975 disk blocks are not allocated for the file until you write to it). To
6976 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
6977 This function returns 0 on success or -1 on error.
6979 (Added in 1.0.77)
6981 guestfs_tune2fs_l
6983 char **
6984 guestfs_tune2fs_l (guestfs_h *g,
6985 const char *device);
6986 This returns the contents of the ext2, ext3 or ext4 filesystem
6988 superblock on "device".
6989 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
6991 for more details. The list of fields returned isn't clearly defined,
6992 and depends on both the version of "tune2fs" that libguestfs was built
6993 against, and the filesystem itself.
6994 This function returns a NULL-terminated array of strings, or NULL if
6996 there was an error. The array of strings will always have length
6997 "2n+1", where "n" keys and values alternate, followed by the trailing
6998 NULL entry. The caller must free the strings and the array after use.
6999 (Added in 0.9.2)
7001 guestfs_txz_in
7003 int
7004 guestfs_txz_in (guestfs_h *g,
7005 const char *tarball,
7006 const char *directory);
7007 This command uploads and unpacks local file "tarball" (an xz compressed
7009 tar file) into "directory".
7010 This function returns 0 on success or -1 on error.
7012 (Added in 1.3.2)
7014 guestfs_txz_out
7016 int
7017 guestfs_txz_out (guestfs_h *g,
7018 const char *directory,
7019 const char *tarball);
7020 This command packs the contents of "directory" and downloads it to
7022 local file "tarball" (as an xz compressed tar archive).
7023 This function returns 0 on success or -1 on error.
7025 (Added in 1.3.2)
7027 guestfs_umask
7029 int
7030 guestfs_umask (guestfs_h *g,
7031 int mask);
7032 This function sets the mask used for creating new files and device
7034 nodes to "mask & 0777".
7035 Typical umask values would be 022 which creates new files with
7037 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
7038 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
7039 The default umask is 022. This is important because it means that
7041 directories and device nodes will be created with 0644 or 0755 mode
7042 even if you specify 0777.
7043 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
7045 "guestfs_mkdir".
7046 This call returns the previous umask.
7048 On error this function returns -1.
7050 (Added in 1.0.55)
7052 guestfs_umount
7054 int
7055 guestfs_umount (guestfs_h *g,
7056 const char *pathordevice);
7057 This unmounts the given filesystem. The filesystem may be specified
7059 either by its mountpoint (path) or the device which contains the
7060 filesystem.
7061 This function returns 0 on success or -1 on error.
7063 (Added in 0.8)
7065 guestfs_umount_all
7067 int
7068 guestfs_umount_all (guestfs_h *g);
7069 This unmounts all mounted filesystems.
7071 Some internal mounts are not unmounted by this call.
7073 This function returns 0 on success or -1 on error.
7075 (Added in 0.8)
7077 guestfs_upload
7079 int
7080 guestfs_upload (guestfs_h *g,
7081 const char *filename,
7082 const char *remotefilename);
7083 Upload local file "filename" to "remotefilename" on the filesystem.
7085 "filename" can also be a named pipe.
7087 See also "guestfs_download".
7089 This function returns 0 on success or -1 on error.
7091 This long-running command can generate progress notification messages
7093 so that the caller can display a progress bar or indicator. To receive
7094 these messages, the caller must register a progress callback. See
7095 "guestfs_set_progress_callback" in guestfs(3).
7096 (Added in 1.0.2)
7098 guestfs_upload_offset
7100 int
7101 guestfs_upload_offset (guestfs_h *g,
7102 const char *filename,
7103 const char *remotefilename,
7104 int64_t offset);
7105 Upload local file "filename" to "remotefilename" on the filesystem.
7107 "remotefilename" is overwritten starting at the byte "offset"
7109 specified. The intention is to overwrite parts of existing files or
7110 devices, although if a non-existant file is specified then it is
7111 created with a "hole" before "offset". The size of the data written is
7112 implicit in the size of the source "filename".
7113 Note that there is no limit on the amount of data that can be uploaded
7115 with this call, unlike with "guestfs_pwrite", and this call always
7116 writes the full amount unless an error occurs.
7117 See also "guestfs_upload", "guestfs_pwrite".
7119 This function returns 0 on success or -1 on error.
7121 This long-running command can generate progress notification messages
7123 so that the caller can display a progress bar or indicator. To receive
7124 these messages, the caller must register a progress callback. See
7125 "guestfs_set_progress_callback" in guestfs(3).
7126 (Added in 1.5.17)
7128 guestfs_utimens
7130 int
7131 guestfs_utimens (guestfs_h *g,
7132 const char *path,
7133 int64_t atsecs,
7134 int64_t atnsecs,
7135 int64_t mtsecs,
7136 int64_t mtnsecs);
7137 This command sets the timestamps of a file with nanosecond precision.
7139 "atsecs, atnsecs" are the last access time (atime) in secs and
7141 nanoseconds from the epoch.
7142 "mtsecs, mtnsecs" are the last modification time (mtime) in secs and
7144 nanoseconds from the epoch.
7145 If the *nsecs field contains the special value "-1" then the
7147 corresponding timestamp is set to the current time. (The *secs field
7148 is ignored in this case).
7149 If the *nsecs field contains the special value "-2" then the
7151 corresponding timestamp is left unchanged. (The *secs field is ignored
7152 in this case).
7153 This function returns 0 on success or -1 on error.
7155 (Added in 1.0.77)
7157 guestfs_version
7159 struct guestfs_version *
7160 guestfs_version (guestfs_h *g);
7161 Return the libguestfs version number that the program is linked
7163 against.
7164 Note that because of dynamic linking this is not necessarily the
7166 version of libguestfs that you compiled against. You can compile the
7167 program, and then at runtime dynamically link against a completely
7168 different "libguestfs.so" library.
7169 This call was added in version 1.0.58. In previous versions of
7171 libguestfs there was no way to get the version number. From C code you
7172 can use dynamic linker functions to find out if this symbol exists (if
7173 it doesn't, then it's an earlier version).
7174 The call returns a structure with four elements. The first three
7176 ("major", "minor" and "release") are numbers and correspond to the
7177 usual version triplet. The fourth element ("extra") is a string and is
7178 normally empty, but may be used for distro-specific information.
7179 To construct the original version string:
7181 "$major.$minor.$release$extra"
7182 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7184 Note: Don't use this call to test for availability of features. In
7186 enterprise distributions we backport features from later versions into
7187 earlier versions, making this an unreliable way to test for features.
7188 Use "guestfs_available" instead.
7189 This function returns a "struct guestfs_version *", or NULL if there
7191 was an error. The caller must call "guestfs_free_version" after use.
7192 (Added in 1.0.58)
7194 guestfs_vfs_label
7196 char *
7197 guestfs_vfs_label (guestfs_h *g,
7198 const char *device);
7199 This returns the filesystem label of the filesystem on "device".
7201 If the filesystem is unlabeled, this returns the empty string.
7203 To find a filesystem from the label, use "guestfs_findfs_label".
7205 This function returns a string, or NULL on error. The caller must free
7207 the returned string after use.
7208 (Added in 1.3.18)
7210 guestfs_vfs_type
7212 char *
7213 guestfs_vfs_type (guestfs_h *g,
7214 const char *device);
7215 This command gets the filesystem type corresponding to the filesystem
7217 on "device".
7218 For most filesystems, the result is the name of the Linux VFS module
7220 which would be used to mount this filesystem if you mounted it without
7221 specifying the filesystem type. For example a string such as "ext3" or
7222 "ntfs".
7223 This function returns a string, or NULL on error. The caller must free
7225 the returned string after use.
7226 (Added in 1.0.75)
7228 guestfs_vfs_uuid
7230 char *
7231 guestfs_vfs_uuid (guestfs_h *g,
7232 const char *device);
7233 This returns the filesystem UUID of the filesystem on "device".
7235 If the filesystem does not have a UUID, this returns the empty string.
7237 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
7239 This function returns a string, or NULL on error. The caller must free
7241 the returned string after use.
7242 (Added in 1.3.18)
7244 guestfs_vg_activate
7246 int
7247 guestfs_vg_activate (guestfs_h *g,
7248 int activate,
7249 char *const *volgroups);
7250 This command activates or (if "activate" is false) deactivates all
7252 logical volumes in the listed volume groups "volgroups". If activated,
7253 then they are made known to the kernel, ie. they appear as
7254 "/dev/mapper" devices. If deactivated, then those devices disappear.
7255 This command is the same as running "vgchange -a y|n volgroups..."
7257 Note that if "volgroups" is an empty list then all volume groups are
7259 activated or deactivated.
7260 This function returns 0 on success or -1 on error.
7262 (Added in 1.0.26)
7264 guestfs_vg_activate_all
7266 int
7267 guestfs_vg_activate_all (guestfs_h *g,
7268 int activate);
7269 This command activates or (if "activate" is false) deactivates all
7271 logical volumes in all volume groups. If activated, then they are made
7272 known to the kernel, ie. they appear as "/dev/mapper" devices. If
7273 deactivated, then those devices disappear.
7274 This command is the same as running "vgchange -a y|n"
7276 This function returns 0 on success or -1 on error.
7278 (Added in 1.0.26)
7280 guestfs_vgcreate
7282 int
7283 guestfs_vgcreate (guestfs_h *g,
7284 const char *volgroup,
7285 char *const *physvols);
7286 This creates an LVM volume group called "volgroup" from the non-empty
7288 list of physical volumes "physvols".
7289 This function returns 0 on success or -1 on error.
7291 (Added in 0.8)
7293 guestfs_vglvuuids
7295 char **
7296 guestfs_vglvuuids (guestfs_h *g,
7297 const char *vgname);
7298 Given a VG called "vgname", this returns the UUIDs of all the logical
7300 volumes created in this volume group.
7301 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
7303 associate logical volumes and volume groups.
7304 See also "guestfs_vgpvuuids".
7306 This function returns a NULL-terminated array of strings (like
7308 environ(3)), or NULL if there was an error. The caller must free the
7309 strings and the array after use.
7310 (Added in 1.0.87)
7312 guestfs_vgpvuuids
7314 char **
7315 guestfs_vgpvuuids (guestfs_h *g,
7316 const char *vgname);
7317 Given a VG called "vgname", this returns the UUIDs of all the physical
7319 volumes that this volume group resides on.
7320 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
7322 associate physical volumes and volume groups.
7323 See also "guestfs_vglvuuids".
7325 This function returns a NULL-terminated array of strings (like
7327 environ(3)), or NULL if there was an error. The caller must free the
7328 strings and the array after use.
7329 (Added in 1.0.87)
7331 guestfs_vgremove
7333 int
7334 guestfs_vgremove (guestfs_h *g,
7335 const char *vgname);
7336 Remove an LVM volume group "vgname", (for example "VG").
7338 This also forcibly removes all logical volumes in the volume group (if
7340 any).
7341 This function returns 0 on success or -1 on error.
7343 (Added in 1.0.13)
7345 guestfs_vgrename
7347 int
7348 guestfs_vgrename (guestfs_h *g,
7349 const char *volgroup,
7350 const char *newvolgroup);
7351 Rename a volume group "volgroup" with the new name "newvolgroup".
7353 This function returns 0 on success or -1 on error.
7355 (Added in 1.0.83)
7357 guestfs_vgs
7359 char **
7360 guestfs_vgs (guestfs_h *g);
7361 List all the volumes groups detected. This is the equivalent of the
7363 vgs(8) command.
7364 This returns a list of just the volume group names that were detected
7366 (eg. "VolGroup00").
7367 See also "guestfs_vgs_full".
7369 This function returns a NULL-terminated array of strings (like
7371 environ(3)), or NULL if there was an error. The caller must free the
7372 strings and the array after use.
7373 (Added in 0.4)
7375 guestfs_vgs_full
7377 struct guestfs_lvm_vg_list *
7378 guestfs_vgs_full (guestfs_h *g);
7379 List all the volumes groups detected. This is the equivalent of the
7381 vgs(8) command. The "full" version includes all fields.
7382 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
7384 there was an error. The caller must call "guestfs_free_lvm_vg_list"
7385 after use.
7386 (Added in 0.4)
7388 guestfs_vgscan
7390 int
7391 guestfs_vgscan (guestfs_h *g);
7392 This rescans all block devices and rebuilds the list of LVM physical
7394 volumes, volume groups and logical volumes.
7395 This function returns 0 on success or -1 on error.
7397 (Added in 1.3.2)
7399 guestfs_vguuid
7401 char *
7402 guestfs_vguuid (guestfs_h *g,
7403 const char *vgname);
7404 This command returns the UUID of the LVM VG named "vgname".
7406 This function returns a string, or NULL on error. The caller must free
7408 the returned string after use.
7409 (Added in 1.0.87)
7411 guestfs_wait_ready
7413 int
7414 guestfs_wait_ready (guestfs_h *g);
7415 This function is a no op.
7417 In versions of the API < 1.0.71 you had to call this function just
7419 after calling "guestfs_launch" to wait for the launch to complete.
7420 However this is no longer necessary because "guestfs_launch" now does
7421 the waiting.
7422 If you see any calls to this function in code then you can just remove
7424 them, unless you want to retain compatibility with older versions of
7425 the API.
7426 This function returns 0 on success or -1 on error.
7428 (Added in 0.3)
7430 guestfs_wc_c
7432 int
7433 guestfs_wc_c (guestfs_h *g,
7434 const char *path);
7435 This command counts the characters in a file, using the "wc -c"
7437 external command.
7438 On error this function returns -1.
7440 (Added in 1.0.54)
7442 guestfs_wc_l
7444 int
7445 guestfs_wc_l (guestfs_h *g,
7446 const char *path);
7447 This command counts the lines in a file, using the "wc -l" external
7449 command.
7450 On error this function returns -1.
7452 (Added in 1.0.54)
7454 guestfs_wc_w
7456 int
7457 guestfs_wc_w (guestfs_h *g,
7458 const char *path);
7459 This command counts the words in a file, using the "wc -w" external
7461 command.
7462 On error this function returns -1.
7464 (Added in 1.0.54)
7466 guestfs_write
7468 int
7469 guestfs_write (guestfs_h *g,
7470 const char *path,
7471 const char *content,
7472 size_t content_size);
7473 This call creates a file called "path". The content of the file is the
7475 string "content" (which can contain any 8 bit data).
7476 This function returns 0 on success or -1 on error.
7478 Because of the message protocol, there is a transfer limit of somewhere
7480 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7481 (Added in 1.3.14)
7483 guestfs_write_file
7485 int
7486 guestfs_write_file (guestfs_h *g,
7487 const char *path,
7488 const char *content,
7489 int size);
7490 This call creates a file called "path". The contents of the file is
7492 the string "content" (which can contain any 8 bit data), with length
7493 "size".
7494 As a special case, if "size" is 0 then the length is calculated using
7496 "strlen" (so in this case the content cannot contain embedded ASCII
7497 NULs).
7498 NB. Owing to a bug, writing content containing ASCII NUL characters
7500 does not work, even if the length is specified.
7501 This function returns 0 on success or -1 on error.
7503 Because of the message protocol, there is a transfer limit of somewhere
7505 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7506 This function is deprecated. In new code, use the "guestfs_write" call
7508 instead.
7509 Deprecated functions will not be removed from the API, but the fact
7511 that they are deprecated indicates that there are problems with correct
7512 use of these functions.
7513 (Added in 0.8)
7515 guestfs_zegrep
7517 char **
7518 guestfs_zegrep (guestfs_h *g,
7519 const char *regex,
7520 const char *path);
7521 This calls the external "zegrep" program and returns the matching
7523 lines.
7524 This function returns a NULL-terminated array of strings (like
7526 environ(3)), or NULL if there was an error. The caller must free the
7527 strings and the array after use.
7528 Because of the message protocol, there is a transfer limit of somewhere
7530 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7531 (Added in 1.0.66)
7533 guestfs_zegrepi
7535 char **
7536 guestfs_zegrepi (guestfs_h *g,
7537 const char *regex,
7538 const char *path);
7539 This calls the external "zegrep -i" program and returns the matching
7541 lines.
7542 This function returns a NULL-terminated array of strings (like
7544 environ(3)), or NULL if there was an error. The caller must free the
7545 strings and the array after use.
7546 Because of the message protocol, there is a transfer limit of somewhere
7548 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7549 (Added in 1.0.66)
7551 guestfs_zero
7553 int
7554 guestfs_zero (guestfs_h *g,
7555 const char *device);
7556 This command writes zeroes over the first few blocks of "device".
7558 How many blocks are zeroed isn't specified (but it's not enough to
7560 securely wipe the device). It should be sufficient to remove any
7561 partition tables, filesystem superblocks and so on.
7562 See also: "guestfs_zero_device", "guestfs_scrub_device".
7564 This function returns 0 on success or -1 on error.
7566 This long-running command can generate progress notification messages
7568 so that the caller can display a progress bar or indicator. To receive
7569 these messages, the caller must register a progress callback. See
7570 "guestfs_set_progress_callback" in guestfs(3).
7571 (Added in 1.0.16)
7573 guestfs_zero_device
7575 int
7576 guestfs_zero_device (guestfs_h *g,
7577 const char *device);
7578 This command writes zeroes over the entire "device". Compare with
7580 "guestfs_zero" which just zeroes the first few blocks of a device.
7581 This function returns 0 on success or -1 on error.
7583 This long-running command can generate progress notification messages
7585 so that the caller can display a progress bar or indicator. To receive
7586 these messages, the caller must register a progress callback. See
7587 "guestfs_set_progress_callback" in guestfs(3).
7588 This command is dangerous. Without careful use you can easily destroy
7590 all your data.
7591 (Added in 1.3.1)
7593 guestfs_zerofree
7595 int
7596 guestfs_zerofree (guestfs_h *g,
7597 const char *device);
7598 This runs the zerofree program on "device". This program claims to
7600 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
7601 it possible to compress the filesystem more effectively.
7602 You should not run this program if the filesystem is mounted.
7604 It is possible that using this program can damage the filesystem or
7606 data on the filesystem.
7607 This function returns 0 on success or -1 on error.
7609 (Added in 1.0.26)
7611 guestfs_zfgrep
7613 char **
7614 guestfs_zfgrep (guestfs_h *g,
7615 const char *pattern,
7616 const char *path);
7617 This calls the external "zfgrep" program and returns the matching
7619 lines.
7620 This function returns a NULL-terminated array of strings (like
7622 environ(3)), or NULL if there was an error. The caller must free the
7623 strings and the array after use.
7624 Because of the message protocol, there is a transfer limit of somewhere
7626 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7627 (Added in 1.0.66)
7629 guestfs_zfgrepi
7631 char **
7632 guestfs_zfgrepi (guestfs_h *g,
7633 const char *pattern,
7634 const char *path);
7635 This calls the external "zfgrep -i" program and returns the matching
7637 lines.
7638 This function returns a NULL-terminated array of strings (like
7640 environ(3)), or NULL if there was an error. The caller must free the
7641 strings and the array after use.
7642 Because of the message protocol, there is a transfer limit of somewhere
7644 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7645 (Added in 1.0.66)
7647 guestfs_zfile
7649 char *
7650 guestfs_zfile (guestfs_h *g,
7651 const char *meth,
7652 const char *path);
7653 This command runs "file" after first decompressing "path" using
7655 "method".
7656 "method" must be one of "gzip", "compress" or "bzip2".
7658 Since 1.0.63, use "guestfs_file" instead which can now process
7660 compressed files.
7661 This function returns a string, or NULL on error. The caller must free
7663 the returned string after use.
7664 This function is deprecated. In new code, use the "guestfs_file" call
7666 instead.
7667 Deprecated functions will not be removed from the API, but the fact
7669 that they are deprecated indicates that there are problems with correct
7670 use of these functions.
7671 (Added in 1.0.59)
7673 guestfs_zgrep
7675 char **
7676 guestfs_zgrep (guestfs_h *g,
7677 const char *regex,
7678 const char *path);
7679 This calls the external "zgrep" program and returns the matching lines.
7681 This function returns a NULL-terminated array of strings (like
7683 environ(3)), or NULL if there was an error. The caller must free the
7684 strings and the array after use.
7685 Because of the message protocol, there is a transfer limit of somewhere
7687 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7688 (Added in 1.0.66)
7690 guestfs_zgrepi
7692 char **
7693 guestfs_zgrepi (guestfs_h *g,
7694 const char *regex,
7695 const char *path);
7696 This calls the external "zgrep -i" program and returns the matching
7698 lines.
7699 This function returns a NULL-terminated array of strings (like
7701 environ(3)), or NULL if there was an error. The caller must free the
7702 strings and the array after use.
7703 Because of the message protocol, there is a transfer limit of somewhere
7705 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7706 (Added in 1.0.66)
7708
7710 guestfs_int_bool
7711 struct guestfs_int_bool {
7712 int32_t i;
7713 int32_t b;
7714 };
7715 struct guestfs_int_bool_list {
7717 uint32_t len; /* Number of elements in list. */
7718 struct guestfs_int_bool *val; /* Elements. */
7719 };
7720 void guestfs_free_int_bool (struct guestfs_free_int_bool *);
7722 void guestfs_free_int_bool_list (struct guestfs_free_int_bool_list *);
7723 guestfs_lvm_pv
7725 struct guestfs_lvm_pv {
7726 char *pv_name;
7727 /* The next field is NOT nul-terminated, be careful when printing it: */
7728 char pv_uuid[32];
7729 char *pv_fmt;
7730 uint64_t pv_size;
7731 uint64_t dev_size;
7732 uint64_t pv_free;
7733 uint64_t pv_used;
7734 char *pv_attr;
7735 int64_t pv_pe_count;
7736 int64_t pv_pe_alloc_count;
7737 char *pv_tags;
7738 uint64_t pe_start;
7739 int64_t pv_mda_count;
7740 uint64_t pv_mda_free;
7741 };
7742 struct guestfs_lvm_pv_list {
7744 uint32_t len; /* Number of elements in list. */
7745 struct guestfs_lvm_pv *val; /* Elements. */
7746 };
7747 void guestfs_free_lvm_pv (struct guestfs_free_lvm_pv *);
7749 void guestfs_free_lvm_pv_list (struct guestfs_free_lvm_pv_list *);
7750 guestfs_lvm_vg
7752 struct guestfs_lvm_vg {
7753 char *vg_name;
7754 /* The next field is NOT nul-terminated, be careful when printing it: */
7755 char vg_uuid[32];
7756 char *vg_fmt;
7757 char *vg_attr;
7758 uint64_t vg_size;
7759 uint64_t vg_free;
7760 char *vg_sysid;
7761 uint64_t vg_extent_size;
7762 int64_t vg_extent_count;
7763 int64_t vg_free_count;
7764 int64_t max_lv;
7765 int64_t max_pv;
7766 int64_t pv_count;
7767 int64_t lv_count;
7768 int64_t snap_count;
7769 int64_t vg_seqno;
7770 char *vg_tags;
7771 int64_t vg_mda_count;
7772 uint64_t vg_mda_free;
7773 };
7774 struct guestfs_lvm_vg_list {
7776 uint32_t len; /* Number of elements in list. */
7777 struct guestfs_lvm_vg *val; /* Elements. */
7778 };
7779 void guestfs_free_lvm_vg (struct guestfs_free_lvm_vg *);
7781 void guestfs_free_lvm_vg_list (struct guestfs_free_lvm_vg_list *);
7782 guestfs_lvm_lv
7784 struct guestfs_lvm_lv {
7785 char *lv_name;
7786 /* The next field is NOT nul-terminated, be careful when printing it: */
7787 char lv_uuid[32];
7788 char *lv_attr;
7789 int64_t lv_major;
7790 int64_t lv_minor;
7791 int64_t lv_kernel_major;
7792 int64_t lv_kernel_minor;
7793 uint64_t lv_size;
7794 int64_t seg_count;
7795 char *origin;
7796 /* The next field is [0..100] or -1 meaning 'not present': */
7797 float snap_percent;
7798 /* The next field is [0..100] or -1 meaning 'not present': */
7799 float copy_percent;
7800 char *move_pv;
7801 char *lv_tags;
7802 char *mirror_log;
7803 char *modules;
7804 };
7805 struct guestfs_lvm_lv_list {
7807 uint32_t len; /* Number of elements in list. */
7808 struct guestfs_lvm_lv *val; /* Elements. */
7809 };
7810 void guestfs_free_lvm_lv (struct guestfs_free_lvm_lv *);
7812 void guestfs_free_lvm_lv_list (struct guestfs_free_lvm_lv_list *);
7813 guestfs_stat
7815 struct guestfs_stat {
7816 int64_t dev;
7817 int64_t ino;
7818 int64_t mode;
7819 int64_t nlink;
7820 int64_t uid;
7821 int64_t gid;
7822 int64_t rdev;
7823 int64_t size;
7824 int64_t blksize;
7825 int64_t blocks;
7826 int64_t atime;
7827 int64_t mtime;
7828 int64_t ctime;
7829 };
7830 struct guestfs_stat_list {
7832 uint32_t len; /* Number of elements in list. */
7833 struct guestfs_stat *val; /* Elements. */
7834 };
7835 void guestfs_free_stat (struct guestfs_free_stat *);
7837 void guestfs_free_stat_list (struct guestfs_free_stat_list *);
7838 guestfs_statvfs
7840 struct guestfs_statvfs {
7841 int64_t bsize;
7842 int64_t frsize;
7843 int64_t blocks;
7844 int64_t bfree;
7845 int64_t bavail;
7846 int64_t files;
7847 int64_t ffree;
7848 int64_t favail;
7849 int64_t fsid;
7850 int64_t flag;
7851 int64_t namemax;
7852 };
7853 struct guestfs_statvfs_list {
7855 uint32_t len; /* Number of elements in list. */
7856 struct guestfs_statvfs *val; /* Elements. */
7857 };
7858 void guestfs_free_statvfs (struct guestfs_free_statvfs *);
7860 void guestfs_free_statvfs_list (struct guestfs_free_statvfs_list *);
7861 guestfs_dirent
7863 struct guestfs_dirent {
7864 int64_t ino;
7865 char ftyp;
7866 char *name;
7867 };
7868 struct guestfs_dirent_list {
7870 uint32_t len; /* Number of elements in list. */
7871 struct guestfs_dirent *val; /* Elements. */
7872 };
7873 void guestfs_free_dirent (struct guestfs_free_dirent *);
7875 void guestfs_free_dirent_list (struct guestfs_free_dirent_list *);
7876 guestfs_version
7878 struct guestfs_version {
7879 int64_t major;
7880 int64_t minor;
7881 int64_t release;
7882 char *extra;
7883 };
7884 struct guestfs_version_list {
7886 uint32_t len; /* Number of elements in list. */
7887 struct guestfs_version *val; /* Elements. */
7888 };
7889 void guestfs_free_version (struct guestfs_free_version *);
7891 void guestfs_free_version_list (struct guestfs_free_version_list *);
7892 guestfs_xattr
7894 struct guestfs_xattr {
7895 char *attrname;
7896 /* The next two fields describe a byte array. */
7897 uint32_t attrval_len;
7898 char *attrval;
7899 };
7900 struct guestfs_xattr_list {
7902 uint32_t len; /* Number of elements in list. */
7903 struct guestfs_xattr *val; /* Elements. */
7904 };
7905 void guestfs_free_xattr (struct guestfs_free_xattr *);
7907 void guestfs_free_xattr_list (struct guestfs_free_xattr_list *);
7908 guestfs_inotify_event
7910 struct guestfs_inotify_event {
7911 int64_t in_wd;
7912 uint32_t in_mask;
7913 uint32_t in_cookie;
7914 char *in_name;
7915 };
7916 struct guestfs_inotify_event_list {
7918 uint32_t len; /* Number of elements in list. */
7919 struct guestfs_inotify_event *val; /* Elements. */
7920 };
7921 void guestfs_free_inotify_event (struct guestfs_free_inotify_event *);
7923 void guestfs_free_inotify_event_list (struct guestfs_free_inotify_event_list *);
7924 guestfs_partition
7926 struct guestfs_partition {
7927 int32_t part_num;
7928 uint64_t part_start;
7929 uint64_t part_end;
7930 uint64_t part_size;
7931 };
7932 struct guestfs_partition_list {
7934 uint32_t len; /* Number of elements in list. */
7935 struct guestfs_partition *val; /* Elements. */
7936 };
7937 void guestfs_free_partition (struct guestfs_free_partition *);
7939 void guestfs_free_partition_list (struct guestfs_free_partition_list *);
7940 guestfs_application
7942 struct guestfs_application {
7943 char *app_name;
7944 char *app_display_name;
7945 int32_t app_epoch;
7946 char *app_version;
7947 char *app_release;
7948 char *app_install_path;
7949 char *app_trans_path;
7950 char *app_publisher;
7951 char *app_url;
7952 char *app_source_package;
7953 char *app_summary;
7954 char *app_description;
7955 };
7956 struct guestfs_application_list {
7958 uint32_t len; /* Number of elements in list. */
7959 struct guestfs_application *val; /* Elements. */
7960 };
7961 void guestfs_free_application (struct guestfs_free_application *);
7963 void guestfs_free_application_list (struct guestfs_free_application_list *);
7964
7966 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
7967 Using "guestfs_available" you can test availability of the following
7968 groups of functions. This test queries the appliance to see if the
7969 appliance you are currently using supports the functionality.
7970 augeas
7972 The following functions: "guestfs_aug_clear" "guestfs_aug_close"
7973 "guestfs_aug_defnode" "guestfs_aug_defvar" "guestfs_aug_get"
7974 "guestfs_aug_init" "guestfs_aug_insert" "guestfs_aug_load"
7975 "guestfs_aug_ls" "guestfs_aug_match" "guestfs_aug_mv"
7976 "guestfs_aug_rm" "guestfs_aug_save" "guestfs_aug_set"
7977 grub
7979 The following functions: "guestfs_grub_install"
7980 inotify
7982 The following functions: "guestfs_inotify_add_watch"
7983 "guestfs_inotify_close" "guestfs_inotify_files"
7984 "guestfs_inotify_init" "guestfs_inotify_read"
7985 "guestfs_inotify_rm_watch"
7986 linuxfsuuid
7988 The following functions: "guestfs_mke2fs_JU"
7989 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
7990 "guestfs_swapon_uuid"
7991 linuxmodules
7993 The following functions: "guestfs_modprobe"
7994 linuxxattrs
7996 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
7997 "guestfs_lgetxattr" "guestfs_lgetxattrs" "guestfs_lremovexattr"
7998 "guestfs_lsetxattr" "guestfs_lxattrlist" "guestfs_removexattr"
7999 "guestfs_setxattr"
8000 luks
8002 The following functions: "guestfs_luks_add_key"
8003 "guestfs_luks_close" "guestfs_luks_format"
8004 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
8005 "guestfs_luks_open" "guestfs_luks_open_ro"
8006 lvm2
8008 The following functions: "guestfs_is_lv" "guestfs_lvcreate"
8009 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
8010 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
8011 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvcreate"
8012 "guestfs_pvremove" "guestfs_pvresize" "guestfs_pvresize_size"
8013 "guestfs_pvs" "guestfs_pvs_full" "guestfs_vg_activate"
8014 "guestfs_vg_activate_all" "guestfs_vgcreate" "guestfs_vgremove"
8015 "guestfs_vgs" "guestfs_vgs_full"
8016 mknod
8018 The following functions: "guestfs_mkfifo" "guestfs_mknod"
8019 "guestfs_mknod_b" "guestfs_mknod_c"
8020 ntfs3g
8022 The following functions: "guestfs_ntfs_3g_probe"
8023 ntfsprogs
8025 The following functions: "guestfs_ntfsresize"
8026 "guestfs_ntfsresize_size"
8027 realpath
8029 The following functions: "guestfs_realpath"
8030 scrub
8032 The following functions: "guestfs_scrub_device"
8033 "guestfs_scrub_file" "guestfs_scrub_freespace"
8034 selinux
8036 The following functions: "guestfs_getcon" "guestfs_setcon"
8037 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
8039 zerofree
8041 The following functions: "guestfs_zerofree"
8042 GUESTFISH supported COMMAND
8044 In guestfish(3) there is a handy interactive command "supported" which
8045 prints out the available groups and whether they are supported by this
8046 build of libguestfs. Note however that you have to do "run" first.
8047 SINGLE CALLS AT COMPILE TIME
8049 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
8050 function, such as:
8051 #define LIBGUESTFS_HAVE_DD 1
8053 if "guestfs_dd" is available.
8055 Before version 1.5.8, if you needed to test whether a single libguestfs
8057 function is available at compile time, we recommended using build tools
8058 such as autoconf or cmake. For example in autotools you could use:
8059 AC_CHECK_LIB([guestfs],[guestfs_create])
8061 AC_CHECK_FUNCS([guestfs_dd])
8062 which would result in "HAVE_GUESTFS_DD" being either defined or not
8064 defined in your program.
8065 SINGLE CALLS AT RUN TIME
8067 Testing at compile time doesn't guarantee that a function really exists
8068 in the library. The reason is that you might be dynamically linked
8069 against a previous libguestfs.so (dynamic library) which doesn't have
8070 the call. This situation unfortunately results in a segmentation
8071 fault, which is a shortcoming of the C dynamic linking system itself.
8072 You can use dlopen(3) to test if a function is available at run time,
8074 as in this example program (note that you still need the compile time
8075 check as well):
8076 #include <stdio.h>
8078 #include <stdlib.h>
8079 #include <unistd.h>
8080 #include <dlfcn.h>
8081 #include <guestfs.h>
8082 main ()
8084 {
8085 #ifdef LIBGUESTFS_HAVE_DD
8086 void *dl;
8087 int has_function;
8088 /* Test if the function guestfs_dd is really available. */
8090 dl = dlopen (NULL, RTLD_LAZY);
8091 if (!dl) {
8092 fprintf (stderr, "dlopen: %s\n", dlerror ());
8093 exit (EXIT_FAILURE);
8094 }
8095 has_function = dlsym (dl, "guestfs_dd") != NULL;
8096 dlclose (dl);
8097 if (!has_function)
8099 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
8100 else {
8101 printf ("this libguestfs.so has guestfs_dd function\n");
8102 /* Now it's safe to call
8103 guestfs_dd (g, "foo", "bar");
8104 */
8105 }
8106 #else
8107 printf ("guestfs_dd function was not found at compile time\n");
8108 #endif
8109 }
8110 You may think the above is an awful lot of hassle, and it is. There
8112 are other ways outside of the C linking system to ensure that this kind
8113 of incompatibility never arises, such as using package versioning:
8114 Requires: libguestfs >= 1.0.80
8116
8118 A recent feature of the API is the introduction of calls which take
8119 optional arguments. In C these are declared 3 ways. The main way is
8120 as a call which takes variable arguments (ie. "..."), as in this
8121 example:
8122 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
8124 Call this with a list of optional arguments, terminated by "-1". So to
8126 call with no optional arguments specified:
8127 guestfs_add_drive_opts (g, filename, -1);
8129 With a single optional argument:
8131 guestfs_add_drive_opts (g, filename,
8133 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
8134 -1);
8135 With two:
8137 guestfs_add_drive_opts (g, filename,
8139 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
8140 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
8141 -1);
8142 and so forth. Don't forget the terminating "-1" otherwise Bad Things
8144 will happen!
8145 USING va_list FOR OPTIONAL ARGUMENTS
8147 The second variant has the same name with the suffix "_va", which works
8148 the same way but takes a "va_list". See the C manual for details. For
8149 the example function, this is declared:
8150 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
8152 va_list args);
8153 CONSTRUCTING OPTIONAL ARGUMENTS
8155 The third variant is useful where you need to construct these calls.
8156 You pass in a structure where you fill in the optional fields. The
8157 structure has a bitmask as the first element which you must set to
8158 indicate which fields you have filled in. For our example function the
8159 structure and call are declared:
8160 struct guestfs_add_drive_opts_argv {
8162 uint64_t bitmask;
8163 int readonly;
8164 const char *format;
8165 /* ... */
8166 };
8167 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
8168 const struct guestfs_add_drive_opts_argv *optargs);
8169 You could call it like this:
8171 struct guestfs_add_drive_opts_argv optargs = {
8173 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
8174 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
8175 .readonly = 1,
8176 .format = "qcow2"
8177 };
8178 guestfs_add_drive_opts_argv (g, filename, &optargs);
8180 Notes:
8182 · The "_BITMASK" suffix on each option name when specifying the
8184 bitmask.
8185 · You do not need to fill in all fields of the structure.
8187 · There must be a one-to-one correspondence between fields of the
8189 structure that are filled in, and bits set in the bitmask.
8190 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
8192 In other languages, optional arguments are expressed in the way that is
8193 natural for that language. We refer you to the language-specific
8194 documentation for more details on that.
8195 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
8197 SETTING CALLBACKS TO HANDLE EVENTS
8199 The child process generates events in some situations. Current events
8200 include: receiving a log message, the child process exits.
8201 Use the "guestfs_set_*_callback" functions to set a callback for
8203 different types of events.
8204 Only one callback of each type can be registered for each handle.
8206 Calling "guestfs_set_*_callback" again overwrites the previous callback
8207 of that type. Cancel all callbacks of this type by calling this
8208 function with "cb" set to "NULL".
8209 guestfs_set_log_message_callback
8211 typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
8212 char *buf, int len);
8213 void guestfs_set_log_message_callback (guestfs_h *g,
8214 guestfs_log_message_cb cb,
8215 void *opaque);
8216 The callback function "cb" will be called whenever qemu or the guest
8218 writes anything to the console.
8219 Use this function to capture kernel messages and similar.
8221 Normally there is no log message handler, and log messages are just
8223 discarded.
8224 guestfs_set_subprocess_quit_callback
8226 typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);
8227 void guestfs_set_subprocess_quit_callback (guestfs_h *g,
8228 guestfs_subprocess_quit_cb cb,
8229 void *opaque);
8230 The callback function "cb" will be called when the child process quits,
8232 either asynchronously or if killed by "guestfs_kill_subprocess". (This
8233 corresponds to a transition from any state to the CONFIG state).
8234 guestfs_set_launch_done_callback
8236 typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
8237 void guestfs_set_launch_done_callback (guestfs_h *g,
8238 guestfs_launch_done_cb cb,
8239 void *opaque);
8240 The callback function "cb" will be called when the child process
8242 becomes ready first time after it has been launched. (This corresponds
8243 to a transition from LAUNCHING to the READY state).
8244 guestfs_set_close_callback
8246 typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);
8247 void guestfs_set_close_callback (guestfs_h *g,
8248 guestfs_close_cb cb,
8249 void *opaque);
8250 The callback function "cb" will be called while the handle is being
8252 closed (synchronously from "guestfs_close").
8253 Note that libguestfs installs an atexit(3) handler to try to clean up
8255 handles that are open when the program exits. This means that this
8256 callback might be called indirectly from exit(3), which can cause
8257 unexpected problems in higher-level languages (eg. if your HLL
8258 interpreter has already been cleaned up by the time this is called, and
8259 if your callback then jumps into some HLL function).
8260 guestfs_set_progress_callback
8262 typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque,
8263 int proc_nr, int serial,
8264 uint64_t position, uint64_t total);
8265 void guestfs_set_progress_callback (guestfs_h *g,
8266 guestfs_progress_cb cb,
8267 void *opaque);
8268 Some long-running operations can generate progress messages. If this
8270 callback is registered, then it will be called each time a progress
8271 message is generated (usually two seconds after the operation started,
8272 and three times per second thereafter until it completes, although the
8273 frequency may change in future versions).
8274 The callback receives two numbers: "position" and "total". The units
8276 of "total" are not defined, although for some operations "total" may
8277 relate in some way to the amount of data to be transferred (eg. in
8278 bytes or megabytes), and "position" may be the portion which has been
8279 transferred.
8280 The only defined and stable parts of the API are:
8282 · The callback can display to the user some type of progress bar or
8284 indicator which shows the ratio of "position":"total".
8285 · 0 <= "position" <= "total"
8287 · If any progress notification is sent during a call, then a final
8289 progress notification is always sent when "position" = "total"
8290 (unless the call fails with an error).
8291 This is to simplify caller code, so callers can easily set the
8293 progress indicator to "100%" at the end of the operation, without
8294 requiring special code to detect this case.
8295 The callback also receives the procedure number and serial number of
8297 the call. These are only useful for debugging protocol issues, and the
8298 callback can normally ignore them. The callback may want to print
8299 these numbers in error messages or debugging messages.
8300
8302 You can attach named pieces of private data to the libguestfs handle,
8303 and fetch them by name for the lifetime of the handle. This is called
8304 the private data area and is only available from the C API.
8305 To attach a named piece of data, use the following call:
8307 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
8309 "key" is the name to associate with this data, and "data" is an
8311 arbitrary pointer (which can be "NULL"). Any previous item with the
8312 same name is overwritten.
8313 You can use any "key" you want, but names beginning with an underscore
8315 character are reserved for internal libguestfs purposes (for
8316 implementing language bindings). It is recommended to prefix the name
8317 with some unique string to avoid collisions with other users.
8318 To retrieve the pointer, use:
8320 void *guestfs_get_private (guestfs_h *g, const char *key);
8322 This function returns "NULL" if either no data is found associated with
8324 "key", or if the user previously set the "key"'s "data" pointer to
8325 "NULL".
8326 Libguestfs does not try to look at or interpret the "data" pointer in
8328 any way. As far as libguestfs is concerned, it need not be a valid
8329 pointer at all. In particular, libguestfs does not try to free the
8330 data when the handle is closed. If the data must be freed, then the
8331 caller must either free it before calling "guestfs_close" or must set
8332 up a close callback to do it (see "guestfs_set_close_callback", and
8333 note that only one callback can be registered for a handle).
8334 The private data area is implemented using a hash table, and should be
8336 reasonably efficient for moderate numbers of keys.
8337
8339 Internally, libguestfs is implemented by running an appliance (a
8340 special type of small virtual machine) using qemu(1). Qemu runs as a
8341 child process of the main program.
8342 ___________________
8344 / \
8345 | main program |
8346 | |
8347 | | child process / appliance
8348 | | __________________________
8349 | | / qemu \
8350 +-------------------+ RPC | +-----------------+ |
8351 | libguestfs <--------------------> guestfsd | |
8352 | | | +-----------------+ |
8353 \___________________/ | | Linux kernel | |
8354 | +--^--------------+ |
8355 \_________|________________/
8356 |
8357 _______v______
8358 / \
8359 | Device or |
8360 | disk image |
8361 \______________/
8362 The library, linked to the main program, creates the child process and
8364 hence the appliance in the "guestfs_launch" function.
8365 Inside the appliance is a Linux kernel and a complete stack of
8367 userspace tools (such as LVM and ext2 programs) and a small controlling
8368 daemon called "guestfsd". The library talks to "guestfsd" using remote
8369 procedure calls (RPC). There is a mostly one-to-one correspondence
8370 between libguestfs API calls and RPC calls to the daemon. Lastly the
8371 disk image(s) are attached to the qemu process which translates device
8372 access by the appliance's Linux kernel into accesses to the image.
8373 A common misunderstanding is that the appliance "is" the virtual
8375 machine. Although the disk image you are attached to might also be
8376 used by some virtual machine, libguestfs doesn't know or care about
8377 this. (But you will care if both libguestfs's qemu process and your
8378 virtual machine are trying to update the disk image at the same time,
8379 since these usually results in massive disk corruption).
8380
8382 libguestfs uses a state machine to model the child process:
8383 |
8385 guestfs_create
8386 |
8387 |
8388 ____V_____
8389 / \
8390 | CONFIG |
8391 \__________/
8392 ^ ^ ^ \
8393 / | \ \ guestfs_launch
8394 / | _\__V______
8395 / | / \
8396 / | | LAUNCHING |
8397 / | \___________/
8398 / | /
8399 / | guestfs_launch
8400 / | /
8401 ______ / __|____V
8402 / \ ------> / \
8403 | BUSY | | READY |
8404 \______/ <------ \________/
8405 The normal transitions are (1) CONFIG (when the handle is created, but
8407 there is no child process), (2) LAUNCHING (when the child process is
8408 booting up), (3) alternating between READY and BUSY as commands are
8409 issued to, and carried out by, the child process.
8410 The guest may be killed by "guestfs_kill_subprocess", or may die
8412 asynchronously at any time (eg. due to some internal error), and that
8413 causes the state to transition back to CONFIG.
8414 Configuration commands for qemu such as "guestfs_add_drive" can only be
8416 issued when in the CONFIG state.
8417 The API offers one call that goes from CONFIG through LAUNCHING to
8419 READY. "guestfs_launch" blocks until the child process is READY to
8420 accept commands (or until some failure or timeout). "guestfs_launch"
8421 internally moves the state from CONFIG to LAUNCHING while it is
8422 running.
8423 API actions such as "guestfs_mount" can only be issued when in the
8425 READY state. These API calls block waiting for the command to be
8426 carried out (ie. the state to transition to BUSY and then back to
8427 READY). There are no non-blocking versions, and no way to issue more
8428 than one command per handle at the same time.
8429 Finally, the child process sends asynchronous messages back to the main
8431 program, such as kernel log messages. You can register a callback to
8432 receive these messages.
8433
8435 COMMUNICATION PROTOCOL
8436 Don't rely on using this protocol directly. This section documents how
8437 it currently works, but it may change at any time.
8438 The protocol used to talk between the library and the daemon running
8440 inside the qemu virtual machine is a simple RPC mechanism built on top
8441 of XDR (RFC 1014, RFC 1832, RFC 4506).
8442 The detailed format of structures is in "src/guestfs_protocol.x" (note:
8444 this file is automatically generated).
8445 There are two broad cases, ordinary functions that don't have any
8447 "FileIn" and "FileOut" parameters, which are handled with very simple
8448 request/reply messages. Then there are functions that have any
8449 "FileIn" or "FileOut" parameters, which use the same request and reply
8450 messages, but they may also be followed by files sent using a chunked
8451 encoding.
8452 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)
8454 For ordinary functions, the request message is:
8456 total length (header + arguments,
8458 but not including the length word itself)
8459 struct guestfs_message_header (encoded as XDR)
8460 struct guestfs_<foo>_args (encoded as XDR)
8461 The total length field allows the daemon to allocate a fixed size
8463 buffer into which it slurps the rest of the message. As a result, the
8464 total length is limited to "GUESTFS_MESSAGE_MAX" bytes (currently 4MB),
8465 which means the effective size of any request is limited to somewhere
8466 under this size.
8467 Note also that many functions don't take any arguments, in which case
8469 the "guestfs_foo_args" is completely omitted.
8470 The header contains the procedure number ("guestfs_proc") which is how
8472 the receiver knows what type of args structure to expect, or none at
8473 all.
8474 For functions that take optional arguments, the optional arguments are
8476 encoded in the "guestfs_foo_args" structure in the same way as ordinary
8477 arguments. A bitmask in the header indicates which optional arguments
8478 are meaningful. The bitmask is also checked to see if it contains bits
8479 set which the daemon does not know about (eg. if more optional
8480 arguments were added in a later version of the library), and this
8481 causes the call to be rejected.
8482 The reply message for ordinary functions is:
8484 total length (header + ret,
8486 but not including the length word itself)
8487 struct guestfs_message_header (encoded as XDR)
8488 struct guestfs_<foo>_ret (encoded as XDR)
8489 As above the "guestfs_foo_ret" structure may be completely omitted for
8491 functions that return no formal return values.
8492 As above the total length of the reply is limited to
8494 "GUESTFS_MESSAGE_MAX".
8495 In the case of an error, a flag is set in the header, and the reply
8497 message is slightly changed:
8498 total length (header + error,
8500 but not including the length word itself)
8501 struct guestfs_message_header (encoded as XDR)
8502 struct guestfs_message_error (encoded as XDR)
8503 The "guestfs_message_error" structure contains the error message as a
8505 string.
8506 FUNCTIONS THAT HAVE FILEIN PARAMETERS
8508 A "FileIn" parameter indicates that we transfer a file into the guest.
8510 The normal request message is sent (see above). However this is
8511 followed by a sequence of file chunks.
8512 total length (header + arguments,
8514 but not including the length word itself,
8515 and not including the chunks)
8516 struct guestfs_message_header (encoded as XDR)
8517 struct guestfs_<foo>_args (encoded as XDR)
8518 sequence of chunks for FileIn param #0
8519 sequence of chunks for FileIn param #1 etc.
8520 The "sequence of chunks" is:
8522 length of chunk (not including length word itself)
8524 struct guestfs_chunk (encoded as XDR)
8525 length of chunk
8526 struct guestfs_chunk (encoded as XDR)
8527 ...
8528 length of chunk
8529 struct guestfs_chunk (with data.data_len == 0)
8530 The final chunk has the "data_len" field set to zero. Additionally a
8532 flag is set in the final chunk to indicate either successful completion
8533 or early cancellation.
8534 At time of writing there are no functions that have more than one
8536 FileIn parameter. However this is (theoretically) supported, by
8537 sending the sequence of chunks for each FileIn parameter one after
8538 another (from left to right).
8539 Both the library (sender) and the daemon (receiver) may cancel the
8541 transfer. The library does this by sending a chunk with a special flag
8542 set to indicate cancellation. When the daemon sees this, it cancels
8543 the whole RPC, does not send any reply, and goes back to reading the
8544 next request.
8545 The daemon may also cancel. It does this by writing a special word
8547 "GUESTFS_CANCEL_FLAG" to the socket. The library listens for this
8548 during the transfer, and if it gets it, it will cancel the transfer (it
8549 sends a cancel chunk). The special word is chosen so that even if
8550 cancellation happens right at the end of the transfer (after the
8551 library has finished writing and has started listening for the reply),
8552 the "spurious" cancel flag will not be confused with the reply message.
8553 This protocol allows the transfer of arbitrary sized files (no 32 bit
8555 limit), and also files where the size is not known in advance (eg. from
8556 pipes or sockets). However the chunks are rather small
8557 ("GUESTFS_MAX_CHUNK_SIZE"), so that neither the library nor the daemon
8558 need to keep much in memory.
8559 FUNCTIONS THAT HAVE FILEOUT PARAMETERS
8561 The protocol for FileOut parameters is exactly the same as for FileIn
8563 parameters, but with the roles of daemon and library reversed.
8564 total length (header + ret,
8566 but not including the length word itself,
8567 and not including the chunks)
8568 struct guestfs_message_header (encoded as XDR)
8569 struct guestfs_<foo>_ret (encoded as XDR)
8570 sequence of chunks for FileOut param #0
8571 sequence of chunks for FileOut param #1 etc.
8572 INITIAL MESSAGE
8574 When the daemon launches it sends an initial word
8576 ("GUESTFS_LAUNCH_FLAG") which indicates that the guest and daemon is
8577 alive. This is what "guestfs_launch" waits for.
8578 PROGRESS NOTIFICATION MESSAGES
8580 The daemon may send progress notification messages at any time. These
8582 are distinguished by the normal length word being replaced by
8583 "GUESTFS_PROGRESS_FLAG", followed by a fixed size progress message.
8584 The library turns them into progress callbacks (see
8586 "guestfs_set_progress_callback") if there is a callback registered, or
8587 discards them if not.
8588 The daemon self-limits the frequency of progress messages it sends (see
8590 "daemon/proto.c:notify_progress"). Not all calls generate progress
8591 messages.
8592
8594 Since April 2010, libguestfs has started to make separate development
8595 and stable releases, along with corresponding branches in our git
8596 repository. These separate releases can be identified by version
8597 number:
8598 even numbers for stable: 1.2.x, 1.4.x, ...
8600 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
8601 |
8602 v
8603 1 . 3 . 5
8604 ^ ^
8605 | |
8606 | `-------- sub-version
8607 |
8608 `------ always '1' because we don't change the ABI
8609 Thus "1.3.5" is the 5th update to the development branch "1.3".
8611 As time passes we cherry pick fixes from the development branch and
8613 backport those into the stable branch, the effect being that the stable
8614 branch should get more stable and less buggy over time. So the stable
8615 releases are ideal for people who don't need new features but would
8616 just like the software to work.
8617 Our criteria for backporting changes are:
8619 · Documentation changes which don't affect any code are backported
8621 unless the documentation refers to a future feature which is not in
8622 stable.
8623 · Bug fixes which are not controversial, fix obvious problems, and
8625 have been well tested are backported.
8626 · Simple rearrangements of code which shouldn't affect how it works
8628 get backported. This is so that the code in the two branches
8629 doesn't get too far out of step, allowing us to backport future
8630 fixes more easily.
8631 · We don't backport new features, new APIs, new tools etc, except in
8633 one exceptional case: the new feature is required in order to
8634 implement an important bug fix.
8635 A new stable branch starts when we think the new features in
8637 development are substantial and compelling enough over the current
8638 stable branch to warrant it. When that happens we create new stable
8639 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
8640 oh release won't necessarily be so stable at this point, but by
8641 backporting fixes from development, that branch will stabilize over
8642 time.
8643
8645 ADDING A NEW API ACTION
8646 Large amounts of boilerplate code in libguestfs (RPC, bindings,
8647 documentation) are generated, and this makes it easy to extend the
8648 libguestfs API.
8649 To add a new API action there are two changes:
8651 1. You need to add a description of the call (name, parameters, return
8653 type, tests, documentation) to "generator/generator_actions.ml".
8654 There are two sorts of API action, depending on whether the call
8656 goes through to the daemon in the appliance, or is serviced
8657 entirely by the library (see "ARCHITECTURE" above). "guestfs_sync"
8658 is an example of the former, since the sync is done in the
8659 appliance. "guestfs_set_trace" is an example of the latter, since
8660 a trace flag is maintained in the handle and all tracing is done on
8661 the library side.
8662 Most new actions are of the first type, and get added to the
8664 "daemon_functions" list. Each function has a unique procedure
8665 number used in the RPC protocol which is assigned to that action
8666 when we publish libguestfs and cannot be reused. Take the latest
8667 procedure number and increment it.
8668 For library-only actions of the second type, add to the
8670 "non_daemon_functions" list. Since these functions are serviced by
8671 the library and do not travel over the RPC mechanism to the daemon,
8672 these functions do not need a procedure number, and so the
8673 procedure number is set to "-1".
8674 2. Implement the action (in C):
8676 For daemon actions, implement the function "do_<name>" in the
8678 "daemon/" directory.
8679 For library actions, implement the function "guestfs__<name>"
8681 (note: double underscore) in the "src/" directory.
8682 In either case, use another function as an example of what to do.
8684 After making these changes, use "make" to compile.
8686 Note that you don't need to implement the RPC, language bindings,
8688 manual pages or anything else. It's all automatically generated from
8689 the OCaml description.
8690 ADDING TESTS FOR AN API ACTION
8692 You can supply zero or as many tests as you want per API call. The
8693 tests can either be added as part of the API description
8694 ("generator/generator_actions.ml"), or in some rarer cases you may want
8695 to drop a script into "regressions/". Note that adding a script to
8696 "regressions/" is slower, so if possible use the first method.
8697 The following describes the test environment used when you add an API
8699 test in "generator_actions.ml".
8700 The test environment has 4 block devices:
8702 "/dev/sda" 500MB
8704 General block device for testing.
8705 "/dev/sdb" 50MB
8707 "/dev/sdb1" is an ext2 filesystem used for testing filesystem write
8708 operations.
8709 "/dev/sdc" 10MB
8711 Used in a few tests where two block devices are needed.
8712 "/dev/sdd"
8714 ISO with fixed content (see "images/test.iso").
8715 To be able to run the tests in a reasonable amount of time, the
8717 libguestfs appliance and block devices are reused between tests. So
8718 don't try testing "guestfs_kill_subprocess" :-x
8719 Each test starts with an initial scenario, selected using one of the
8721 "Init*" expressions, described in "generator/generator_types.ml".
8722 These initialize the disks mentioned above in a particular way as
8723 documented in "generator_types.ml". You should not assume anything
8724 about the previous contents of other disks that are not initialized.
8725 You can add a prerequisite clause to any individual test. This is a
8727 run-time check, which, if it fails, causes the test to be skipped.
8728 Useful if testing a command which might not work on all variations of
8729 libguestfs builds. A test that has prerequisite of "Always" means to
8730 run unconditionally.
8731 In addition, packagers can skip individual tests by setting environment
8733 variables before running "make check".
8734 SKIP_TEST_<CMD>_<NUM>=1
8736 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command".
8738 or:
8740 SKIP_TEST_<CMD>=1
8742 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" tests.
8744 Packagers can run only certain tests by setting for example:
8746 TEST_ONLY="vfs_type zerofree"
8748 See "capitests/tests.c" for more details of how these environment
8750 variables work.
8751 DEBUGGING NEW API ACTIONS
8753 Test new actions work before submitting them.
8754 You can use guestfish to try out new commands.
8756 Debugging the daemon is a problem because it runs inside a minimal
8758 environment. However you can fprintf messages in the daemon to stderr,
8759 and they will show up if you use "guestfish -v".
8760 FORMATTING CODE AND OTHER CONVENTIONS
8762 Our C source code generally adheres to some basic code-formatting
8763 conventions. The existing code base is not totally consistent on this
8764 front, but we do prefer that contributed code be formatted similarly.
8765 In short, use spaces-not-TABs for indentation, use 2 spaces for each
8766 indentation level, and other than that, follow the K&R style.
8767 If you use Emacs, add the following to one of one of your start-up
8769 files (e.g., ~/.emacs), to help ensure that you get indentation right:
8770 ;;; In libguestfs, indent with spaces everywhere (not TABs).
8772 ;;; Exceptions: Makefile and ChangeLog modes.
8773 (add-hook 'find-file-hook
8774 '(lambda () (if (and buffer-file-name
8775 (string-match "/libguestfs\\>"
8776 (buffer-file-name))
8777 (not (string-equal mode-name "Change Log"))
8778 (not (string-equal mode-name "Makefile")))
8779 (setq indent-tabs-mode nil))))
8780 ;;; When editing C sources in libguestfs, use this style.
8782 (defun libguestfs-c-mode ()
8783 "C mode with adjusted defaults for use with libguestfs."
8784 (interactive)
8785 (c-set-style "K&R")
8786 (setq c-indent-level 2)
8787 (setq c-basic-offset 2))
8788 (add-hook 'c-mode-hook
8789 '(lambda () (if (string-match "/libguestfs\\>"
8790 (buffer-file-name))
8791 (libguestfs-c-mode))))
8792 Enable warnings when compiling (and fix any problems this finds):
8794 ./configure --enable-gcc-warnings
8796 Useful targets are:
8798 make syntax-check # checks the syntax of the C code
8800 make check # runs the test suite
8801 DAEMON CUSTOM PRINTF FORMATTERS
8803 In the daemon code we have created custom printf formatters %Q and %R,
8804 which are used to do shell quoting.
8805 %Q Simple shell quoted string. Any spaces or other shell characters
8807 are escaped for you.
8808 %R Same as %Q except the string is treated as a path which is prefixed
8810 by the sysroot.
8811 For example:
8813 asprintf (&cmd, "cat %R", path);
8815 would produce "cat /sysroot/some\ path\ with\ spaces"
8817 Note: Do not use these when you are passing parameters to the
8819 "command{,r,v,rv}()" functions. These parameters do NOT need to be
8820 quoted because they are not passed via the shell (instead, straight to
8821 exec). You probably want to use the "sysroot_path()" function however.
8822 SUBMITTING YOUR NEW API ACTIONS
8824 Submit patches to the mailing list:
8825 <http://www.redhat.com/mailman/listinfo/libguestfs> and CC to
8826 rjones@redhat.com.
8827 INTERNATIONALIZATION (I18N) SUPPORT
8829 We support i18n (gettext anyhow) in the library.
8830 However many messages come from the daemon, and we don't translate
8832 those at the moment. One reason is that the appliance generally has
8833 all locale files removed from it, because they take up a lot of space.
8834 So we'd have to readd some of those, as well as copying our PO files
8835 into the appliance.
8836 Debugging messages are never translated, since they are intended for
8838 the programmers.
8839 SOURCE CODE SUBDIRECTORIES
8841 "appliance"
8842 The libguestfs appliance, build scripts and so on.
8843 "capitests"
8845 Automated tests of the C API.
8846 "cat"
8848 The virt-cat(1), virt-filesystems(1) and virt-ls(1) commands and
8849 documentation.
8850 "caution"
8852 Safety and liveness tests of components that libguestfs depends
8853 upon (not of libguestfs itself). Mainly this is for qemu and the
8854 kernel.
8855 "contrib"
8857 Outside contributions, experimental parts.
8858 "daemon"
8860 The daemon that runs inside the libguestfs appliance and carries
8861 out actions.
8862 "df"
8864 virt-df(1) command and documentation.
8865 "examples"
8867 C API example code.
8868 "fish"
8870 guestfish(1), the command-line shell.
8871 "fuse"
8873 guestmount(1), FUSE (userspace filesystem) built on top of
8874 libguestfs.
8875 "generator"
8877 The crucially important generator, used to automatically generate
8878 large amounts of boilerplate C code for things like RPC and
8879 bindings.
8880 "images"
8882 Files used by the test suite.
8883 Some "phony" guest images which we test against.
8885 "inspector"
8887 virt-inspector(1), the virtual machine image inspector.
8888 "m4"
8890 M4 macros used by autoconf.
8891 "po"
8893 Translations of simple gettext strings.
8894 "po-docs"
8896 The build infrastructure and PO files for translations of manpages
8897 and POD files. Eventually this will be combined with the "po"
8898 directory, but that is rather complicated.
8899 "regressions"
8901 Regression tests.
8902 "rescue"
8904 virt-rescue(1) command and documentation.
8905 "src"
8907 Source code to the C library.
8908 "tools"
8910 Command line tools written in Perl (virt-resize(1) and many
8911 others).
8912 "test-tool"
8914 Test tool for end users to test if their qemu/kernel combination
8915 will work with libguestfs.
8916 "csharp"
8918 "haskell"
8919 "java"
8920 "ocaml"
8921 "php"
8922 "perl"
8923 "python"
8924 "ruby"
8925 Language bindings.
8926
8928 LIBGUESTFS_APPEND
8929 Pass additional options to the guest kernel.
8930 LIBGUESTFS_DEBUG
8932 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
8933 same effect as calling "guestfs_set_verbose (g, 1)".
8934 LIBGUESTFS_MEMSIZE
8936 Set the memory allocated to the qemu process, in megabytes. For
8937 example:
8938 LIBGUESTFS_MEMSIZE=700
8940 LIBGUESTFS_PATH
8942 Set the path that libguestfs uses to search for a supermin
8943 appliance. See the discussion of paths in section "PATH" above.
8944 LIBGUESTFS_QEMU
8946 Set the default qemu binary that libguestfs uses. If not set, then
8947 the qemu which was found at compile time by the configure script is
8948 used.
8949 See also "QEMU WRAPPERS" above.
8951 LIBGUESTFS_TRACE
8953 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
8954 same effect as calling "guestfs_set_trace (g, 1)".
8955 TMPDIR
8957 Location of temporary directory, defaults to "/tmp".
8958 If libguestfs was compiled to use the supermin appliance then the
8960 real appliance is cached in this directory, shared between all
8961 handles belonging to the same EUID. You can use $TMPDIR to
8962 configure another directory to use in case "/tmp" is not large
8963 enough.
8964
8966 guestfs-examples(3), guestfs-ocaml(3), guestfs-python(3),
8967 guestfs-ruby(3), guestfish(1), guestmount(1), virt-cat(1), virt-df(1),
8968 virt-edit(1), virt-filesystems(1), virt-inspector(1),
8969 virt-list-filesystems(1), virt-list-partitions(1), virt-ls(1),
8970 virt-make-fs(1), virt-rescue(1), virt-tar(1), virt-win-reg(1), qemu(1),
8971 febootstrap(1), hivex(3), <http://libguestfs.org/>.
8972 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
8974 disktype(1).
8975
8977 To get a list of bugs against libguestfs use this link:
8978 <https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools>
8980 To report a new bug against libguestfs use this link:
8982 <https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools>
8984 When reporting a bug, please check:
8986 · That the bug hasn't been reported already.
8988 · That you are testing a recent version.
8990 · Describe the bug accurately, and give a way to reproduce it.
8992 · Run libguestfs-test-tool and paste the complete, unedited output
8994 into the bug report.
8995
8997 Richard W.M. Jones ("rjones at redhat dot com")
8998
9000 Copyright (C) 2009-2010 Red Hat Inc. <http://libguestfs.org/>
9001 This library is free software; you can redistribute it and/or modify it
9003 under the terms of the GNU Lesser General Public License as published
9004 by the Free Software Foundation; either version 2 of the License, or
9005 (at your option) any later version.
9006 This library is distributed in the hope that it will be useful, but
9008 WITHOUT ANY WARRANTY; without even the implied warranty of
9009 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
9010 Lesser General Public License for more details.
9011 You should have received a copy of the GNU Lesser General Public
9013 License along with this library; if not, write to the Free Software
9014 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
9015 02110-1301 USA
9016libguestfs-1.8.15 2011-11-10 guestfs(3)