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_shutdown (g);
18 guestfs_close (g);
19 cc prog.c -o prog -lguestfs
21 or:
22 cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
23
25 Libguestfs is a library for accessing and modifying disk images and
26 virtual machines. This manual page documents the C API.
27 If you are looking for an introduction to libguestfs, see the web site:
29 http://libguestfs.org/
30 Each virt tool has its own man page (for a full list, go to "SEE ALSO"
32 at the end of this file).
33 The libguestfs FAQ contains many useful answers: guestfs-faq(1).
35 For examples of using the API from C, see guestfs-examples(3). For
37 examples in other languages, see "USING LIBGUESTFS WITH OTHER
38 PROGRAMMING LANGUAGES" below.
39 For tips and recipes, see guestfs-recipes(1).
41 If you are having performance problems, read guestfs-performance(1).
43 To help test libguestfs, read libguestfs-test-tool(1) and
44 guestfs-testing(1).
45
47 This section provides a gentler overview of the libguestfs API. We
48 also try to group API calls together, where that may not be obvious
49 from reading about the individual calls in the main section of this
50 manual.
51 HANDLES
53 Before you can use libguestfs calls, you have to create a handle. Then
54 you must add at least one disk image to the handle, followed by
55 launching the handle, then performing whatever operations you want, and
56 finally closing the handle. By convention we use the single letter "g"
57 for the name of the handle variable, although of course you can use any
58 name you want.
59 The general structure of all libguestfs-using programs looks like this:
61 guestfs_h *g = guestfs_create ();
63 /* Call guestfs_add_drive additional times if there are
65 * multiple disk images.
66 */
67 guestfs_add_drive (g, "guest.img");
68 /* Most manipulation calls won't work until you've launched
70 * the handle 'g'. You have to do this _after_ adding drives
71 * and _before_ other commands.
72 */
73 guestfs_launch (g);
74 /* Either: examine what partitions, LVs etc are available: */
76 char **partitions = guestfs_list_partitions (g);
77 char **logvols = guestfs_lvs (g);
78 /* Or: ask libguestfs to find filesystems for you: */
80 char **filesystems = guestfs_list_filesystems (g);
81 /* Or: use inspection (see INSPECTION section below). */
83 /* To access a filesystem in the image, you must mount it. */
85 guestfs_mount (g, "/dev/sda1", "/");
86 /* Now you can perform filesystem actions on the guest
88 * disk image.
89 */
90 guestfs_touch (g, "/hello");
91 /* Synchronize the disk. This is the opposite of guestfs_launch. */
93 guestfs_shutdown (g);
94 /* Close and free the handle 'g'. */
96 guestfs_close (g);
97 The code above doesn't include any error checking. In real code you
99 should check return values carefully for errors. In general all
100 functions that return integers return "-1" on error, and all functions
101 that return pointers return "NULL" on error. See section "ERROR
102 HANDLING" below for how to handle errors, and consult the documentation
103 for each function call below to see precisely how they return error
104 indications. See guestfs-examples(3) for fully worked examples.
105 DISK IMAGES
107 The image filename ("guest.img" in the example above) could be a disk
108 image from a virtual machine, a dd(1) copy of a physical hard disk, an
109 actual block device, or simply an empty file of zeroes that you have
110 created through posix_fallocate(3). Libguestfs lets you do useful
111 things to all of these.
112 The call you should use in modern code for adding drives is
114 "guestfs_add_drive_opts". To add a disk image, allowing writes, and
115 specifying that the format is raw, do:
116 guestfs_add_drive_opts (g, filename,
118 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
119 -1);
120 You can add a disk read-only using:
122 guestfs_add_drive_opts (g, filename,
124 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
125 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
126 -1);
127 or by calling the older function "guestfs_add_drive_ro". If you use
129 the readonly flag, libguestfs won't modify the file. (See also "DISK
130 IMAGE FORMATS" below).
131 Be extremely cautious if the disk image is in use, eg. if it is being
133 used by a virtual machine. Adding it read-write will almost certainly
134 cause disk corruption, but adding it read-only is safe.
135 You should usually add at least one disk image, and you may add
137 multiple disk images. If adding multiple disk images, they usually
138 have to be "related", ie. from the same guest. In the API, the disk
139 images are usually referred to as "/dev/sda" (for the first one you
140 added), "/dev/sdb" (for the second one you added), etc.
141 Once "guestfs_launch" has been called you cannot add any more images.
143 You can call "guestfs_list_devices" to get a list of the device names,
144 in the order that you added them. See also "BLOCK DEVICE NAMING"
145 below.
146 There are slightly different rules when hotplugging disks (in
148 libguestfs ≥ 1.20). See "HOTPLUGGING" below.
149 MOUNTING
151 Before you can read or write files, create directories and so on in a
152 disk image that contains filesystems, you have to mount those
153 filesystems using "guestfs_mount" or "guestfs_mount_ro". If you
154 already know that a disk image contains (for example) one partition
155 with a filesystem on that partition, then you can mount it directly:
156 guestfs_mount (g, "/dev/sda1", "/");
158 where "/dev/sda1" means literally the first partition (1) of the first
160 disk image that we added ("/dev/sda"). If the disk contains Linux LVM2
161 logical volumes you could refer to those instead (eg. "/dev/VG/LV").
162 Note that these are libguestfs virtual devices, and are nothing to do
163 with host devices.
164 If you are given a disk image and you don't know what it contains then
166 you have to find out. Libguestfs can do that too: use
167 "guestfs_list_partitions" and "guestfs_lvs" to list possible partitions
168 and LVs, and either try mounting each to see what is mountable, or else
169 examine them with "guestfs_vfs_type" or "guestfs_file". To list just
170 filesystems, use "guestfs_list_filesystems".
171 Libguestfs also has a set of APIs for inspection of unknown disk images
173 (see "INSPECTION" below). You might also want to look at higher level
174 programs built on top of libguestfs, in particular virt-inspector(1).
175 To mount a filesystem read-only, use "guestfs_mount_ro". There are
177 several other variations of the "guestfs_mount_*" call.
178 FILESYSTEM ACCESS AND MODIFICATION
180 The majority of the libguestfs API consists of fairly low-level calls
181 for accessing and modifying the files, directories, symlinks etc on
182 mounted filesystems. There are over a hundred such calls which you can
183 find listed in detail below in this man page, and we don't even pretend
184 to cover them all in this overview.
185 Specify filenames as full paths, starting with "/" and including the
187 mount point.
188 For example, if you mounted a filesystem at "/" and you want to read
190 the file called "etc/passwd" then you could do:
191 char *data = guestfs_cat (g, "/etc/passwd");
193 This would return "data" as a newly allocated buffer containing the
195 full content of that file (with some conditions: see also "DOWNLOADING"
196 below), or "NULL" if there was an error.
197 As another example, to create a top-level directory on that filesystem
199 called "var" you would do:
200 guestfs_mkdir (g, "/var");
202 To create a symlink you could do:
204 guestfs_ln_s (g, "/etc/init.d/portmap",
206 "/etc/rc3.d/S30portmap");
207 Libguestfs will reject attempts to use relative paths and there is no
209 concept of a current working directory.
210 Libguestfs can return errors in many situations: for example if the
212 filesystem isn't writable, or if a file or directory that you requested
213 doesn't exist. If you are using the C API (documented here) you have
214 to check for those error conditions after each call. (Other language
215 bindings turn these errors into exceptions).
216 File writes are affected by the per-handle umask, set by calling
218 "guestfs_umask" and defaulting to 022. See "UMASK".
219 Since RHEL 6.4, it is possible to mount the libguestfs filesystem on a
221 local directory, subject to some restrictions. See "MOUNT LOCAL"
222 below.
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/.
247 DOWNLOADING
249 Use "guestfs_cat" to download small, text only files. This call cannot
250 handle files containing any ASCII NUL ("\0") characters. However the
251 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.
255 "guestfs_download" can be used to download any file, with no limits on
257 content or size.
258 To download multiple files, see "guestfs_tar_out" and
260 "guestfs_tgz_out".
261 UPLOADING
263 To write a small file with fixed content, use "guestfs_write". To
264 create a file of all zeroes, use "guestfs_truncate_size" (sparse) or
265 "guestfs_fallocate64" (with all disk blocks allocated). There are a
266 variety of other functions for creating test files, for example
267 "guestfs_fill" and "guestfs_fill_pattern".
268 To upload a single file, use "guestfs_upload". This call has no limits
270 on file content or size.
271 To upload multiple files, see "guestfs_tar_in" and "guestfs_tgz_in".
273 However the fastest way to upload large numbers of arbitrary files is
275 to turn them into a squashfs or CD ISO (see mksquashfs(8) and
276 mkisofs(8)), then attach this using "guestfs_add_drive_ro". If you add
277 the drive in a predictable way (eg. adding it last after all other
278 drives) then you can get the device name from "guestfs_list_devices"
279 and mount it directly using "guestfs_mount_ro". Note that squashfs
280 images are sometimes non-portable between kernel versions, and they
281 don't support labels or UUIDs. If you want to pre-build an image or
282 you need to mount it using a label or UUID, use an ISO image instead.
283 COPYING
285 There are various different commands for copying between files and
286 devices and in and out of the guest filesystem. These are summarised
287 in the table below.
288 file to file
290 Use "guestfs_cp" to copy a single file, or "guestfs_cp_a" to copy
291 directories recursively.
292 To copy part of a file (offset and size) use
294 "guestfs_copy_file_to_file".
295 file to device
297 device to file
298 device to device
299 Use "guestfs_copy_file_to_device", "guestfs_copy_device_to_file",
300 or "guestfs_copy_device_to_device".
301 Example: duplicate the contents of an LV:
303 guestfs_copy_device_to_device (g,
305 "/dev/VG/Original", "/dev/VG/Copy",
306 /* -1 marks the end of the list of optional parameters */
307 -1);
308 The destination ("/dev/VG/Copy") must be at least as large as the
310 source ("/dev/VG/Original"). To copy less than the whole source
311 device, use the optional "size" parameter:
312 guestfs_copy_device_to_device (g,
314 "/dev/VG/Original", "/dev/VG/Copy",
315 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
316 -1);
317 file on the host to file or device
319 Use "guestfs_upload". See "UPLOADING" above.
320 file or device to file on the host
322 Use "guestfs_download". See "DOWNLOADING" above.
323 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
325 Calls like "guestfs_upload", "guestfs_download", "guestfs_tar_in",
326 "guestfs_tar_out" etc appear to only take filenames as arguments, so it
327 appears you can only upload and download to files. However many
328 Un*x-like hosts let you use the special device files "/dev/stdin",
329 "/dev/stdout", "/dev/stderr" and "/dev/fd/N" to read and write from
330 stdin, stdout, stderr, and arbitrary file descriptor N.
331 For example, virt-cat(1) writes its output to stdout by doing:
333 guestfs_download (g, filename, "/dev/stdout");
335 and you can write tar output to a file descriptor "fd" by doing:
337 char devfd[64];
339 snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
340 guestfs_tar_out (g, "/", devfd);
341 LISTING FILES
343 "guestfs_ll" is just designed for humans to read (mainly when using the
344 guestfish(1)-equivalent command "ll").
345 "guestfs_ls" is a quick way to get a list of files in a directory from
347 programs, as a flat list of strings.
348 "guestfs_readdir" is a programmatic way to get a list of files in a
350 directory, plus additional information about each one. It is more
351 equivalent to using the readdir(3) call on a local filesystem.
352 "guestfs_find" and "guestfs_find0" can be used to recursively list
354 files.
355 RUNNING COMMANDS
357 Although libguestfs is primarily an API for manipulating files inside
358 guest images, we also provide some limited facilities for running
359 commands inside guests.
360 There are many limitations to this:
362 · The kernel version that the command runs under will be different
364 from what it expects.
365 · If the command needs to communicate with daemons, then most likely
367 they won't be running.
368 · The command will be running in limited memory.
370 · The network may not be available unless you enable it (see
372 "guestfs_set_network").
373 · Only supports Linux guests (not Windows, BSD, etc).
375 · Architecture limitations (eg. won't work for a PPC guest on an X86
377 host).
378 · For SELinux guests, you may need to enable SELinux and load policy
380 first. See "SELINUX" in this manpage.
381 · Security: It is not safe to run commands from untrusted, possibly
383 malicious guests. These commands may attempt to exploit your
384 program by sending unexpected output. They could also try to
385 exploit the Linux kernel or qemu provided by the libguestfs
386 appliance. They could use the network provided by the libguestfs
387 appliance to bypass ordinary network partitions and firewalls.
388 They could use the elevated privileges or different SELinux context
389 of your program to their advantage.
390 A secure alternative is to use libguestfs to install a "firstboot"
392 script (a script which runs when the guest next boots normally),
393 and to have this script run the commands you want in the normal
394 context of the running guest, network security and so on. For
395 information about other security issues, see "SECURITY".
396 The two main API calls to run commands are "guestfs_command" and
398 "guestfs_sh" (there are also variations).
399 The difference is that "guestfs_sh" runs commands using the shell, so
401 any shell globs, redirections, etc will work.
402 CONFIGURATION FILES
404 To read and write configuration files in Linux guest filesystems, we
405 strongly recommend using Augeas. For example, Augeas understands how
406 to read and write, say, a Linux shadow password file or X.org
407 configuration file, and so avoids you having to write that code.
408 The main Augeas calls are bound through the "guestfs_aug_*" APIs. We
410 don't document Augeas itself here because there is excellent
411 documentation on the http://augeas.net/ website.
412 If you don't want to use Augeas (you fool!) then try calling
414 "guestfs_read_lines" to get the file as a list of lines which you can
415 iterate over.
416 SELINUX
418 We support SELinux guests. To ensure that labeling happens correctly
419 in SELinux guests, you need to enable SELinux and load the guest's
420 policy:
421 1. Before launching, do:
423 guestfs_set_selinux (g, 1);
425 2. After mounting the guest's filesystem(s), load the policy. This is
427 best done by running the load_policy(8) command in the guest
428 itself:
429 guestfs_sh (g, "/usr/sbin/load_policy");
431 (Older versions of "load_policy" require you to specify the name of
433 the policy file).
434 3. Optionally, set the security context for the API. The correct
436 security context to use can only be known by inspecting the guest.
437 As an example:
438 guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
440 This will work for running commands and editing existing files.
442 When new files are created, you may need to label them explicitly, for
444 example by running the external command "restorecon pathname".
445 UMASK
447 Certain calls are affected by the current file mode creation mask (the
448 "umask"). In particular ones which create files or directories, such
449 as "guestfs_touch", "guestfs_mknod" or "guestfs_mkdir". This affects
450 either the default mode that the file is created with or modifies the
451 mode that you supply.
452 The default umask is 022, so files are created with modes such as 0644
454 and directories with 0755.
455 There are two ways to avoid being affected by umask. Either set umask
457 to 0 (call "guestfs_umask (g, 0)" early after launching). Or call
458 "guestfs_chmod" after creating each file or directory.
459 For more information about umask, see umask(2).
461 ENCRYPTED DISKS
463 Libguestfs allows you to access Linux guests which have been encrypted
464 using whole disk encryption that conforms to the Linux Unified Key
465 Setup (LUKS) standard. This includes nearly all whole disk encryption
466 systems used by modern Linux guests.
467 Use "guestfs_vfs_type" to identify LUKS-encrypted block devices (it
469 returns the string "crypto_LUKS").
470 Then open these devices by calling "guestfs_luks_open". Obviously you
472 will require the passphrase!
473 Opening a LUKS device creates a new device mapper device called
475 "/dev/mapper/mapname" (where "mapname" is the string you supply to
476 "guestfs_luks_open"). Reads and writes to this mapper device are
477 decrypted from and encrypted to the underlying block device
478 respectively.
479 LVM volume groups on the device can be made visible by calling
481 "guestfs_vgscan" followed by "guestfs_vg_activate_all". The logical
482 volume(s) can now be mounted in the usual way.
483 Use the reverse process to close a LUKS device. Unmount any logical
485 volumes on it, deactivate the volume groups by caling
486 "guestfs_vg_activate (g, 0, ["/dev/VG"])". Then close the mapper
487 device by calling "guestfs_luks_close" on the "/dev/mapper/mapname"
488 device (not the underlying encrypted block device).
489 MOUNT LOCAL
491 In RHEL ≥ 6.4, it is possible to mount the libguestfs filesystem on a
492 local directory and access it using ordinary POSIX calls and programs.
493 Availability of this is subject to a number of restrictions: it
495 requires FUSE (the Filesystem in USErspace), and libfuse must also have
496 been available when libguestfs was compiled. FUSE may require that a
497 kernel module is loaded, and it may be necessary to add the current
498 user to a special "fuse" group. See the documentation for your
499 distribution and http://fuse.sf.net for further information.
500 The call to mount the libguestfs filesystem on a local directory is
502 "guestfs_mount_local" (q.v.) followed by "guestfs_mount_local_run".
503 The latter does not return until you unmount the filesystem. The
504 reason is that the call enters the FUSE main loop and processes kernel
505 requests, turning them into libguestfs calls. An alternative design
506 would have been to create a background thread to do this, but
507 libguestfs doesn't require pthreads. This way is also more flexible:
508 for example the user can create another thread for
509 "guestfs_mount_local_run".
510 "guestfs_mount_local" needs a certain amount of time to set up the
512 mountpoint. The mountpoint is not ready to use until the call returns.
513 At this point, accesses to the filesystem will block until the main
514 loop is entered (ie. "guestfs_mount_local_run"). So if you need to
515 start another process to access the filesystem, put the fork between
516 "guestfs_mount_local" and "guestfs_mount_local_run".
517 MOUNT LOCAL COMPATIBILITY
519 Since local mounting was only added in RHEL 6.4, you should consider
521 writing code so that it doesn't depend on this feature, and can fall
522 back to using libguestfs file system calls.
523 If libguestfs was compiled without support for "guestfs_mount_local"
525 then calling it will return an error with errno set to "ENOTSUP" (see
526 "guestfs_last_errno").
527 MOUNT LOCAL PERFORMANCE
529 Libguestfs on top of FUSE performs quite poorly. For best performance
531 do not use it. Use ordinary libguestfs filesystem calls, upload,
532 download etc. instead.
533 HOTPLUGGING
535 In libguestfs ≥ 1.20, you may add drives and remove after calling
536 "guestfs_launch". There are some restrictions, see below. This is
537 called hotplugging.
538 Only a subset of the attach-method backends support hotplugging
540 (currently only the libvirt attach-method has support). It also
541 requires that you use libvirt ≥ 0.10.3 and qemu ≥ 1.2.
542 To hot-add a disk, simply call "guestfs_add_drive_opts" after
544 "guestfs_launch". It is mandatory to specify the "label" parameter so
545 that the newly added disk has a predictable name. For example:
546 if (guestfs_launch (g) == -1)
548 error ("launch failed");
549 if (guestfs_add_drive_opts (g, filename,
551 GUESTFS_ADD_DRIVE_OPTS_LABEL, "newdisk",
552 -1) == -1)
553 error ("hot-add of disk failed");
554 if (guestfs_part_disk ("/dev/disk/guestfs/newdisk", "mbr") == -1)
556 error ("partitioning of hot-added disk failed");
557 To hot-remove a disk, call "guestfs_remove_drive". You can call this
559 before or after "guestfs_launch". You can only remove disks that were
560 previously added with a label.
561 Backends that support hotplugging do not require that you add ≥ 1 disk
563 before calling launch. When hotplugging is supported you don't need to
564 add any disks.
565 INSPECTION
567 Libguestfs has APIs for inspecting an unknown disk image to find out if
568 it contains operating systems, an install CD or a live CD. (These APIs
569 used to be in a separate Perl-only library called Sys::Guestfs::Lib(3)
570 but since version 1.5.3 the most frequently used part of this library
571 has been rewritten in C and moved into the core code).
572 Add all disks belonging to the unknown virtual machine and call
574 "guestfs_launch" in the usual way.
575 Then call "guestfs_inspect_os". This function uses other libguestfs
577 calls and certain heuristics, and returns a list of operating systems
578 that were found. An empty list means none were found. A single
579 element is the root filesystem of the operating system. For dual- or
580 multi-boot guests, multiple roots can be returned, each one
581 corresponding to a separate operating system. (Multi-boot virtual
582 machines are extremely rare in the world of virtualization, but since
583 this scenario can happen, we have built libguestfs to deal with it.)
584 For each root, you can then call various "guestfs_inspect_get_*"
586 functions to get additional details about that operating system. For
587 example, call "guestfs_inspect_get_type" to return the string "windows"
588 or "linux" for Windows and Linux-based operating systems respectively.
589 Un*x-like and Linux-based operating systems usually consist of several
591 filesystems which are mounted at boot time (for example, a separate
592 boot partition mounted on "/boot"). The inspection rules are able to
593 detect how filesystems correspond to mount points. Call
594 "guestfs_inspect_get_mountpoints" to get this mapping. It might return
595 a hash table like this example:
596 /boot => /dev/sda1
598 / => /dev/vg_guest/lv_root
599 /usr => /dev/vg_guest/lv_usr
600 The caller can then make calls to "guestfs_mount" to mount the
602 filesystems as suggested.
603 Be careful to mount filesystems in the right order (eg. "/" before
605 "/usr"). Sorting the keys of the hash by length, shortest first,
606 should work.
607 Inspection currently only works for some common operating systems.
609 Contributors are welcome to send patches for other operating systems
610 that we currently cannot detect.
611 Encrypted disks must be opened before inspection. See "ENCRYPTED
613 DISKS" for more details. The "guestfs_inspect_os" function just
614 ignores any encrypted devices.
615 A note on the implementation: The call "guestfs_inspect_os" performs
617 inspection and caches the results in the guest handle. Subsequent
618 calls to "guestfs_inspect_get_*" return this cached information, but do
619 not re-read the disks. If you change the content of the guest disks,
620 you can redo inspection by calling "guestfs_inspect_os" again.
621 ("guestfs_inspect_list_applications2" works a little differently from
622 the other calls and does read the disks. See documentation for that
623 function for details).
624 INSPECTING INSTALL DISKS
626 Libguestfs (since 1.9.4) can detect some install disks, install CDs,
628 live CDs and more.
629 Call "guestfs_inspect_get_format" to return the format of the operating
631 system, which currently can be "installed" (a regular operating system)
632 or "installer" (some sort of install disk).
633 Further information is available about the operating system that can be
635 installed using the regular inspection APIs like
636 "guestfs_inspect_get_product_name", "guestfs_inspect_get_major_version"
637 etc.
638 Some additional information specific to installer disks is also
640 available from the "guestfs_inspect_is_live",
641 "guestfs_inspect_is_netinst" and "guestfs_inspect_is_multipart" calls.
642 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
644 Libguestfs can mount NTFS partitions. It does this using the
645 http://www.ntfs-3g.org/ driver.
646 DRIVE LETTERS AND PATHS
648 DOS and Windows still use drive letters, and the filesystems are always
650 treated as case insensitive by Windows itself, and therefore you might
651 find a Windows configuration file referring to a path like
652 "c:\windows\system32". When the filesystem is mounted in libguestfs,
653 that directory might be referred to as "/WINDOWS/System32".
654 Drive letter mappings can be found using inspection (see "INSPECTION"
656 and "guestfs_inspect_get_drive_mappings")
657 Dealing with separator characters (backslash vs forward slash) is
659 outside the scope of libguestfs, but usually a simple character
660 replacement will work.
661 To resolve the case insensitivity of paths, call
663 "guestfs_case_sensitive_path".
664 LONG FILENAMES ON NTFS
666 NTFS supports filenames up to 255 characters long. "Character" means a
668 2 byte UTF-16 codepoint which can encode the most common Unicode
669 codepoints.
670 Most Linux filesystems support filenames up to 255 bytes. This means
672 you may get an error:
673 File name too long
675 when you copy a file from NTFS to a Linux filesystem if the name, when
677 reencoded as UTF-8, would exceed 255 bytes in length.
678 This will most often happen when using non-ASCII names that are longer
680 than ~127 characters (eg. Greek, Cyrillic) or longer than ~85
681 characters (Asian languages).
682 A workaround is not to try to store such long filenames on Linux native
684 filesystems. Since the tar(1) format can store unlimited length
685 filenames, keep the files in a tarball.
686 ACCESSING THE WINDOWS REGISTRY
688 Libguestfs also provides some help for decoding Windows Registry "hive"
690 files, through a separate C library called hivex(3).
691 Before libguestfs 1.19.35 you had to download the hive file, operate on
693 it locally using hivex, and upload it again. Since this version, we
694 have included the major hivex APIs directly in the libguestfs API (see
695 "guestfs_hivex_open"). This means that if you have opened a Windows
696 guest, you can read and write the registry directly.
697 See also virt-win-reg(1).
699 SYMLINKS ON NTFS-3G FILESYSTEMS
701 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
703 provide something which looks like a Linux symlink. The way it tries
704 to do the rewriting is described here:
705 http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
707 The essential problem is that ntfs-3g simply does not have enough
709 information to do a correct job. NTFS links can contain drive letters
710 and references to external device GUIDs that ntfs-3g has no way of
711 resolving. It is almost certainly the case that libguestfs callers
712 should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
713 NTFS volumes).
714 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
716 "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
717 attribute, and read the raw reparse data from that (you can find the
718 format documented in various places around the web).
719 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
721 There are other useful extended attributes that can be read from
723 ntfs-3g filesystems (using "guestfs_getxattr"). See:
724 http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
726 WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP
728 Windows guests which have been hibernated (instead of fully shut down)
730 cannot be mounted. This is a limitation of ntfs-3g. You will see an
731 error like this:
732 The disk contains an unclean file system (0, 0).
734 Metadata kept in Windows cache, refused to mount.
735 Failed to mount '/dev/sda2': Operation not permitted
736 The NTFS partition is in an unsafe state. Please resume
737 and shutdown Windows fully (no hibernation or fast
738 restarting), or mount the volume read-only with the
739 'ro' mount option.
740 In Windows 8, the shutdown button does not shut down the guest at all.
742 Instead it usually hibernates the guest. This is known as "fast
743 startup".
744 Some suggested workarounds are:
746 · Mount read-only (eg. "guestfs_mount_ro").
748 · On Windows 8, turn off fast startup. It is in the Control Panel →
750 Power Options → Choose what the power buttons do → Change settings
751 that are currently unavailable → Turn on fast startup.
752 · On Windows 7 and earlier, shut the guest off properly instead of
754 hibernating it.
755 RESIZE2FS ERRORS
757 The "guestfs_resize2fs", "guestfs_resize2fs_size" and
758 "guestfs_resize2fs_M" calls are used to resize ext2/3/4 filesystems.
759 The underlying program (resize2fs(8)) requires that the filesystem is
761 clean and recently fsck'd before you can resize it. Also, if the
762 resize operation fails for some reason, then you had to call fsck the
763 filesystem again to fix it.
764 In libguestfs "lt" 1.17.14, you usually had to call "guestfs_e2fsck_f"
766 before the resize. However, in "ge" 1.17.14, e2fsck(8) is called
767 automatically before the resize, so you no longer need to do this.
768 The resize2fs(8) program can still fail, in which case it prints an
770 error message similar to:
771 Please run 'e2fsck -fy <device>' to fix the filesystem
773 after the aborted resize operation.
774 You can do this by calling "guestfs_e2fsck" with the "forceall" option.
776 However in the context of disk images, it is usually better to avoid
777 this situation, eg. by rolling back to an earlier snapshot, or by
778 copying and resizing and on failure going back to the original.
779 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
781 Although we don't want to discourage you from using the C API, we will
782 mention here that the same API is also available in other languages.
783 The API is broadly identical in all supported languages. This means
785 that the C call "guestfs_add_drive_ro(g,file)" is
786 "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
787 and "g#add_drive_ro file" in OCaml. In other words, a straightforward,
788 predictable isomorphism between each language.
789 Error messages are automatically transformed into exceptions if the
791 language supports it.
792 We don't try to "object orientify" parts of the API in OO languages,
794 although contributors are welcome to write higher level APIs above what
795 we provide in their favourite languages if they wish.
796 C++ You can use the guestfs.h header file from C++ programs. The C++
798 API is identical to the C API. C++ classes and exceptions are not
799 used.
800 C# The C# bindings are highly experimental. Please read the warnings
802 at the top of "csharp/Libguestfs.cs".
803 Erlang
805 See guestfs-erlang(3).
806 GObject
808 Experimental GObject bindings (with GObject Introspection support)
809 are available. See the "gobject" directory in the source.
810 Haskell
812 This is the only language binding that is working but incomplete.
813 Only calls which return simple integers have been bound in Haskell,
814 and we are looking for help to complete this binding.
815 Java
817 Full documentation is contained in the Javadoc which is distributed
818 with libguestfs. For examples, see guestfs-java(3).
819 Lua See guestfs-lua(3).
821 OCaml
823 See guestfs-ocaml(3).
824 Perl
826 See guestfs-perl(3) and Sys::Guestfs(3).
827 PHP For documentation see "README-PHP" supplied with libguestfs sources
829 or in the php-libguestfs package for your distribution.
830 The PHP binding only works correctly on 64 bit machines.
832 Python
834 See guestfs-python(3).
835 Ruby
837 See guestfs-ruby(3).
838 For JRuby, use the Java bindings.
840 shell scripts
842 See guestfish(1).
843 LIBGUESTFS GOTCHAS
845 http://en.wikipedia.org/wiki/Gotcha_(programming): "A feature of a
846 system [...] that works in the way it is documented but is
847 counterintuitive and almost invites mistakes."
848 Since we developed libguestfs and the associated tools, there are
850 several things we would have designed differently, but are now stuck
851 with for backwards compatibility or other reasons. If there is ever a
852 libguestfs 2.0 release, you can expect these to change. Beware of
853 them.
854 Read-only should be the default.
856 In guestfish(3), --ro should be the default, and you should have to
857 specify --rw if you want to make changes to the image.
858 This would reduce the potential to corrupt live VM images.
860 Note that many filesystems change the disk when you just mount and
862 unmount, even if you didn't perform any writes. You need to use
863 "guestfs_add_drive_ro" to guarantee that the disk is not changed.
864 guestfish command line is hard to use.
866 "guestfish disk.img" doesn't do what people expect (open "disk.img"
867 for examination). It tries to run a guestfish command "disk.img"
868 which doesn't exist, so it fails. In earlier versions of guestfish
869 the error message was also unintuitive, but we have corrected this
870 since. Like the Bourne shell, we should have used "guestfish -c
871 command" to run commands.
872 guestfish megabyte modifiers don't work right on all commands
874 In recent guestfish you can use "1M" to mean 1 megabyte (and
875 similarly for other modifiers). What guestfish actually does is to
876 multiply the number part by the modifier part and pass the result
877 to the C API. However this doesn't work for a few APIs which
878 aren't expecting bytes, but are already expecting some other unit
879 (eg. megabytes).
880 The most common is "guestfs_lvcreate". The guestfish command:
882 lvcreate LV VG 100M
884 does not do what you might expect. Instead because
886 "guestfs_lvcreate" is already expecting megabytes, this tries to
887 create a 100 terabyte (100 megabytes * megabytes) logical volume.
888 The error message you get from this is also a little obscure.
889 This could be fixed in the generator by specially marking
891 parameters and return values which take bytes or other units.
892 Ambiguity between devices and paths
894 There is a subtle ambiguity in the API between a device name (eg.
895 "/dev/sdb2") and a similar pathname. A file might just happen to
896 be called "sdb2" in the directory "/dev" (consider some non-Unix VM
897 image).
898 In the current API we usually resolve this ambiguity by having two
900 separate calls, for example "guestfs_checksum" and
901 "guestfs_checksum_device". Some API calls are ambiguous and
902 (incorrectly) resolve the problem by detecting if the path supplied
903 begins with "/dev/".
904 To avoid both the ambiguity and the need to duplicate some calls,
906 we could make paths/devices into structured names. One way to do
907 this would be to use a notation like grub ("hd(0,0)"), although
908 nobody really likes this aspect of grub. Another way would be to
909 use a structured type, equivalent to this OCaml type:
910 type path = Path of string | Device of int | Partition of int * int
912 which would allow you to pass arguments like:
914 Path "/foo/bar"
916 Device 1 (* /dev/sdb, or perhaps /dev/sda *)
917 Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
918 Path "/dev/sdb2" (* not a device *)
919 As you can see there are still problems to resolve even with this
921 representation. Also consider how it might work in guestfish.
922 KEYS AND PASSPHRASES
924 Certain libguestfs calls take a parameter that contains sensitive key
925 material, passed in as a C string.
926 In the future we would hope to change the libguestfs implementation so
928 that keys are mlock(2)-ed into physical RAM, and thus can never end up
929 in swap. However this is not done at the moment, because of the
930 complexity of such an implementation.
931 Therefore you should be aware that any key parameter you pass to
933 libguestfs might end up being written out to the swap partition. If
934 this is a concern, scrub the swap partition or don't use libguestfs on
935 encrypted devices.
936 MULTIPLE HANDLES AND MULTIPLE THREADS
938 All high-level libguestfs actions are synchronous. If you want to use
939 libguestfs asynchronously then you must create a thread.
940 Only use the handle from a single thread. Either use the handle
942 exclusively from one thread, or provide your own mutex so that two
943 threads cannot issue calls on the same handle at the same time. Even
944 apparently innocent functions like "guestfs_get_trace" are not safe to
945 be called from multiple threads without a mutex.
946 See the graphical program guestfs-browser for one possible architecture
948 for multithreaded programs using libvirt and libguestfs.
949 PATH
951 Libguestfs needs a supermin appliance, which it finds by looking along
952 an internal path.
953 By default it looks for these in the directory "$libdir/guestfs" (eg.
955 "/usr/local/lib/guestfs" or "/usr/lib64/guestfs").
956 Use "guestfs_set_path" or set the environment variable
958 "LIBGUESTFS_PATH" to change the directories that libguestfs will search
959 in. The value is a colon-separated list of paths. The current
960 directory is not searched unless the path contains an empty element or
961 ".". For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
962 current directory and then "/usr/lib/guestfs".
963 QEMU WRAPPERS
965 If you want to compile your own qemu, run qemu from a non-standard
966 location, or pass extra arguments to qemu, then you can write a shell-
967 script wrapper around qemu.
968 There is one important rule to remember: you must "exec qemu" as the
970 last command in the shell script (so that qemu replaces the shell and
971 becomes the direct child of the libguestfs-using program). If you
972 don't do this, then the qemu process won't be cleaned up correctly.
973 Here is an example of a wrapper, where I have built my own copy of qemu
975 from source:
976 #!/bin/sh -
978 qemudir=/home/rjones/d/qemu
979 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
980 Save this script as "/tmp/qemu.wrapper" (or wherever), "chmod +x", and
982 then use it by setting the LIBGUESTFS_QEMU environment variable. For
983 example:
984 LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
986 Note that libguestfs also calls qemu with the -help and -version
988 options in order to determine features.
989 Wrappers can also be used to edit the options passed to qemu. In the
991 following example, the "-machine ..." option ("-machine" and the
992 following argument) are removed from the command line and replaced with
993 "-machine pc,accel=tcg". The while loop iterates over the options
994 until it finds the right one to remove, putting the remaining options
995 into the "args" array.
996 #!/bin/bash -
998 i=0
1000 while [ $# -gt 0 ]; do
1001 case "$1" in
1002 -machine)
1003 shift 2;;
1004 *)
1005 args[i]="$1"
1006 (( i++ ))
1007 shift ;;
1008 esac
1009 done
1010 exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
1012 ATTACH METHOD
1014 The attach method controls how libguestfs creates and/or connects to
1015 the back-end daemon, eg. by starting qemu directly, or by using libvirt
1016 to manage an appliance, or connecting to an already running daemon.
1017 You can set the attach method by calling "guestfs_set_attach_method",
1019 or by setting the environment variable "LIBGUESTFS_ATTACH_METHOD".
1020 Possible attach methods are described below:
1022 "appliance"
1024 Run qemu directly to launch an appliance.
1025 This is the ordinary method and normally the default, but see the
1027 note below.
1028 "libvirt"
1030 "libvirt:URI"
1031 Use libvirt to launch and manage the appliance.
1032 The optional URI is the libvirt connection URI to use (see
1034 http://libvirt.org/uri.html). The typical libvirt attach method
1035 with a URI would be "libvirt:qemu:///session"
1036 The libvirt attach method supports more features, including
1038 hotplugging (see "HOTPLUGGING") and sVirt.
1039 "unix:path"
1041 Connect to the Unix domain socket path.
1042 This method lets you connect to an existing daemon or (using
1044 virtio-serial) to a live guest. For more information, see
1045 "ATTACHING TO RUNNING DAEMONS".
1046 "appliance" is usually the default attach method. However since
1048 libguestfs ≥ 1.19.24, libguestfs can be built with a different default
1049 by doing:
1050 ./configure --with-default-attach-method=...
1052 To find out if libguestfs was compiled with a different default attach
1054 method, do:
1055 unset LIBGUESTFS_ATTACH_METHOD
1057 guestfish get-attach-method
1058 ATTACHING TO RUNNING DAEMONS
1060 Note [4m(1): This is highly experimental and has a tendency to eat babies.
1061 Use with caution.
1062 Note [4m(2): This section explains how to attach to a running daemon from
1064 a low level perspective. For most users, simply using virt tools such
1065 as guestfish(1) with the --live option will "just work".
1066 Using guestfs_set_attach_method
1068 By calling "guestfs_set_attach_method" you can change how the library
1070 connects to the "guestfsd" daemon in "guestfs_launch" (read
1071 "ARCHITECTURE" for some background).
1072 The normal attach method is "appliance", where a small appliance is
1074 created containing the daemon, and then the library connects to this.
1075 "libvirt" or "libvirt:URI" are alternatives that use libvirt to start
1076 the appliance.
1077 Setting attach method to "unix:path" (where path is the path of a Unix
1079 domain socket) causes "guestfs_launch" to connect to an existing daemon
1080 over the Unix domain socket.
1081 The normal use for this is to connect to a running virtual machine that
1083 contains a "guestfsd" daemon, and send commands so you can read and
1084 write files inside the live virtual machine.
1085 Using guestfs_add_domain with live flag
1087 "guestfs_add_domain" provides some help for getting the correct attach
1089 method. If you pass the "live" option to this function, then (if the
1090 virtual machine is running) it will examine the libvirt XML looking for
1091 a virtio-serial channel to connect to:
1092 <domain>
1094 ...
1095 <devices>
1096 ...
1097 <channel type='unix'>
1098 <source mode='bind' path='/path/to/socket'/>
1099 <target type='virtio' name='org.libguestfs.channel.0'/>
1100 </channel>
1101 ...
1102 </devices>
1103 </domain>
1104 "guestfs_add_domain" extracts "/path/to/socket" and sets the attach
1106 method to "unix:/path/to/socket".
1107 Some of the libguestfs tools (including guestfish) support a --live
1109 option which is passed through to "guestfs_add_domain" thus allowing
1110 you to attach to and modify live virtual machines.
1111 The virtual machine needs to have been set up beforehand so that it has
1113 the virtio-serial channel and so that guestfsd is running inside it.
1114 ABI GUARANTEE
1116 We guarantee the libguestfs ABI (binary interface), for public, high-
1117 level actions as outlined in this section. Although we will deprecate
1118 some actions, for example if they get replaced by newer calls, we will
1119 keep the old actions forever. This allows you the developer to program
1120 in confidence against the libguestfs API.
1121 BLOCK DEVICE NAMING
1123 In the kernel there is now quite a profusion of schemata for naming
1124 block devices (in this context, by block device I mean a physical or
1125 virtual hard drive). The original Linux IDE driver used names starting
1126 with "/dev/hd*". SCSI devices have historically used a different
1127 naming scheme, "/dev/sd*". When the Linux kernel libata driver became
1128 a popular replacement for the old IDE driver (particularly for SATA
1129 devices) those devices also used the "/dev/sd*" scheme. Additionally
1130 we now have virtual machines with paravirtualized drivers. This has
1131 created several different naming systems, such as "/dev/vd*" for virtio
1132 disks and "/dev/xvd*" for Xen PV disks.
1133 As discussed above, libguestfs uses a qemu appliance running an
1135 embedded Linux kernel to access block devices. We can run a variety of
1136 appliances based on a variety of Linux kernels.
1137 This causes a problem for libguestfs because many API calls use device
1139 or partition names. Working scripts and the recipe (example) scripts
1140 that we make available over the internet could fail if the naming
1141 scheme changes.
1142 Therefore libguestfs defines "/dev/sd*" as the standard naming scheme.
1144 Internally "/dev/sd*" names are translated, if necessary, to other
1145 names as required. For example, under RHEL 5 which uses the "/dev/hd*"
1146 scheme, any device parameter "/dev/sda2" is translated to "/dev/hda2"
1147 transparently.
1148 Note that this only applies to parameters. The "guestfs_list_devices",
1150 "guestfs_list_partitions" and similar calls return the true names of
1151 the devices and partitions as known to the appliance, but see
1152 "guestfs_canonical_device_name".
1153 DISK LABELS
1155 In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1157 using the optional "label" parameter to "guestfs_add_drive_opts".
1158 (Note that disk labels are different from and not related to filesystem
1159 labels).
1160 Not all versions of libguestfs support setting a disk label, and when
1162 it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1163 When you add a disk with a label, it can either be addressed using
1165 "/dev/sd*", or using "/dev/disk/guestfs/label". Partitions on the disk
1166 can be addressed using "/dev/disk/guestfs/labelpartnum".
1167 Listing devices ("guestfs_list_devices") and partitions
1169 ("guestfs_list_partitions") returns the raw block device name. However
1170 you can use "guestfs_list_disk_labels" to map disk labels to raw block
1171 device and partition names.
1172 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
1174 Usually this translation is transparent. However in some (very rare)
1176 cases you may need to know the exact algorithm. Such cases include
1177 where you use "guestfs_config" to add a mixture of virtio and IDE
1178 devices to the qemu-based appliance, so have a mixture of "/dev/sd*"
1179 and "/dev/vd*" devices.
1180 The algorithm is applied only to parameters which are known to be
1182 either device or partition names. Return values from functions such as
1183 "guestfs_list_devices" are never changed.
1184 · Is the string a parameter which is a device or partition name?
1186 · Does the string begin with "/dev/sd"?
1188 · Does the named device exist? If so, we use that device. However
1190 if not then we continue with this algorithm.
1191 · Replace initial "/dev/sd" string with "/dev/hd".
1193 For example, change "/dev/sda2" to "/dev/hda2".
1195 If that named device exists, use it. If not, continue.
1197 · Replace initial "/dev/sd" string with "/dev/vd".
1199 If that named device exists, use it. If not, return an error.
1201 PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING
1203 Although the standard naming scheme and automatic translation is useful
1205 for simple programs and guestfish scripts, for larger programs it is
1206 best not to rely on this mechanism.
1207 Where possible for maximum future portability programs using libguestfs
1209 should use these future-proof techniques:
1210 · Use "guestfs_list_devices" or "guestfs_list_partitions" to list
1212 actual device names, and then use those names directly.
1213 Since those device names exist by definition, they will never be
1215 translated.
1216 · Use higher level ways to identify filesystems, such as LVM names,
1218 UUIDs and filesystem labels.
1219 NULL DISKS
1221 When adding a disk using, eg., "guestfs_add_drive", you can set the
1222 filename to "/dev/null". This string is treated specially by
1223 libguestfs, causing it to add a "null disk".
1224 A null disk has the following properties:
1226 · A null disk will appear as a normal device, eg. in calls to
1228 "guestfs_list_devices".
1229 · You may add "/dev/null" multiple times.
1231 · You should not try to access a null disk in any way. For example,
1233 you shouldn't try to read it or mount it.
1234 Null disks are used for three main purposes:
1236 1. Performance testing of libguestfs (see guestfs-performance(1)).
1238 2. The internal test suite.
1240 3. If you want to use libguestfs APIs that don't refer to disks, since
1242 libguestfs requires that at least one disk is added, you should add
1243 a null disk.
1244 For example, to test if a feature is available, use code like this:
1246 guestfs_h *g;
1248 char **groups = [ "btrfs", NULL ];
1249 g = guestfs_create ();
1251 guestfs_add_drive (g, "/dev/null");
1252 guestfs_launch (g);
1253 if (guestfs_available (g, groups) == 0) {
1254 // group(s) are available
1255 } else {
1256 // group(s) are not available
1257 }
1258 guestfs_close (g);
1259 DISK IMAGE FORMATS
1261 Virtual disks come in a variety of formats. Some common formats are
1262 listed below.
1263 Note that libguestfs itself is not responsible for handling the disk
1265 format: this is done using qemu(1). If support for a particular format
1266 is missing or broken, this has to be fixed in qemu.
1267 COMMON VIRTUAL DISK IMAGE FORMATS
1269 raw Raw format is simply a dump of the sequential bytes of the virtual
1271 hard disk. There is no header, container, compression or
1272 processing of any sort.
1273 Since raw format requires no translation to read or write, it is
1275 both fast and very well supported by qemu and all other
1276 hypervisors. You can consider it to be a universal format that any
1277 hypervisor can access.
1278 Raw format files are not compressed and so take up the full space
1280 of the original disk image even when they are empty. A variation
1281 (on Linux/Unix at least) is to not store ranges of all-zero bytes
1282 by storing the file as a sparse file. This "variant format" is
1283 sometimes called raw sparse. Many utilities, including
1284 virt-sparsify(1), can make raw disk images sparse.
1285 qcow2
1287 Qcow2 is the native disk image format used by qemu. Internally it
1288 uses a two-level directory structure so that only blocks containing
1289 data are stored in the file. It also has many other features such
1290 as compression, snapshots and backing files.
1291 There are at least two distinct variants of this format, although
1293 qemu (and hence libguestfs) handles both transparently to the user.
1294 vmdk
1296 VMDK is VMware's native disk image format. There are many
1297 variations. Modern qemu (hence libguestfs) supports most
1298 variations, but you should be aware that older versions of qemu had
1299 some very bad data-corrupting bugs in this area.
1300 Note that VMware ESX exposes files with the name "guest-flat.vmdk".
1302 These are not VMDK. They are raw format files which happen to have
1303 a ".vmdk" extension.
1304 vdi VDI is VirtualBox's native disk image format. Qemu (hence
1306 libguestfs) has generally good support for this.
1307 vpc
1309 vhd VPC (old) and VHD (modern) are the native disk image format of
1310 Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1311 Obsolete formats
1313 The following formats are obsolete and should not be used: qcow
1314 (aka qcow1), cow, bochs.
1315 DETECTING THE FORMAT OF A DISK IMAGE
1317 Firstly note there is a security issue with auto-detecting the format
1319 of a disk image. It may or may not apply in your use case. Read
1320 "CVE-2010-3851" below.
1321 Libguestfs offers an API to get the format of a disk image
1323 ("guestfs_disk_format", and it is safest to use this.
1324 Don't be tempted to try parsing the text / human-readable output of
1326 "qemu-img" since it cannot be parsed reliably and securely. Also do
1327 not use the "file" command since the output of that changes over time.
1328
1330 This section discusses security implications of using libguestfs,
1331 particularly with untrusted or malicious guests or disk images.
1332 SECURITY OF MOUNTING FILESYSTEMS
1334 You should never mount an untrusted guest filesystem directly on your
1335 host kernel (eg. using loopback or kpartx).
1336 When you mount a filesystem, mistakes in the kernel filesystem (VFS)
1338 can be escalated into exploits by attackers creating a malicious
1339 filesystem. These exploits are very severe for two reasons. Firstly
1340 there are very many filesystem drivers in the kernel, and many of them
1341 are infrequently used and not much developer attention has been paid to
1342 the code. Linux userspace helps potential crackers by detecting the
1343 filesystem type and automatically choosing the right VFS driver, even
1344 if that filesystem type is unexpected. Secondly, a kernel-level
1345 exploit is like a local root exploit (worse in some ways), giving
1346 immediate and total access to the system right down to the hardware
1347 level.
1348 These exploits can be present in the kernel for a very long time
1350 (https://lwn.net/Articles/538898/).
1351 Libguestfs provides a layered approach to protecting you from exploits:
1353 untrusted filesystem
1355 --------------------------------------
1356 appliance kernel
1357 --------------------------------------
1358 qemu process running as non-root
1359 --------------------------------------
1360 sVirt [if using libvirt + SELinux]
1361 --------------------------------------
1362 host kernel
1363 We run a Linux kernel inside a qemu virtual machine, usually running as
1365 a non-root user. The attacker would need to write a filesystem which
1366 first exploited the kernel, and then exploited either qemu
1367 virtualization (eg. a faulty qemu driver) or the libguestfs protocol,
1368 and finally to be as serious as the host kernel exploit it would need
1369 to escalate its privileges to root. Additionally if you use the
1370 libvirt back end and SELinux, sVirt is used to confine the qemu
1371 process. This multi-step escalation, performed by a static piece of
1372 data, is thought to be extremely hard to do, although we never say
1373 'never' about security issues.
1374 Callers can also reduce the attack surface by forcing the filesystem
1376 type when mounting (use "guestfs_mount_vfs").
1377 GENERAL SECURITY CONSIDERATIONS
1379 Be careful with any files or data that you download from a guest (by
1380 "download" we mean not just the "guestfs_download" command but any
1381 command that reads files, filenames, directories or anything else from
1382 a disk image). An attacker could manipulate the data to fool your
1383 program into doing the wrong thing. Consider cases such as:
1384 · the data (file etc) not being present
1386 · being present but empty
1388 · being much larger than normal
1390 · containing arbitrary 8 bit data
1392 · being in an unexpected character encoding
1394 · containing homoglyphs.
1396 PROTOCOL SECURITY
1398 The protocol is designed to be secure, being based on RFC 4506 (XDR)
1399 with a defined upper message size. However a program that uses
1400 libguestfs must also take care - for example you can write a program
1401 that downloads a binary from a disk image and executes it locally, and
1402 no amount of protocol security will save you from the consequences.
1403 INSPECTION SECURITY
1405 Parts of the inspection API (see "INSPECTION") return untrusted strings
1406 directly from the guest, and these could contain any 8 bit data.
1407 Callers should be careful to escape these before printing them to a
1408 structured file (for example, use HTML escaping if creating a web
1409 page).
1410 Guest configuration may be altered in unusual ways by the administrator
1412 of the virtual machine, and may not reflect reality (particularly for
1413 untrusted or actively malicious guests). For example we parse the
1414 hostname from configuration files like "/etc/sysconfig/network" that we
1415 find in the guest, but the guest administrator can easily manipulate
1416 these files to provide the wrong hostname.
1417 The inspection API parses guest configuration using two external
1419 libraries: Augeas (Linux configuration) and hivex (Windows Registry).
1420 Both are designed to be robust in the face of malicious data, although
1421 denial of service attacks are still possible, for example with
1422 oversized configuration files.
1423 RUNNING UNTRUSTED GUEST COMMANDS
1425 Be very cautious about running commands from the guest. By running a
1426 command in the guest, you are giving CPU time to a binary that you do
1427 not control, under the same user account as the library, albeit wrapped
1428 in qemu virtualization. More information and alternatives can be found
1429 in the section "RUNNING COMMANDS".
1430 CVE-2010-3851
1432 https://bugzilla.redhat.com/642934
1433 This security bug concerns the automatic disk format detection that
1435 qemu does on disk images.
1436 A raw disk image is just the raw bytes, there is no header. Other disk
1438 images like qcow2 contain a special header. Qemu deals with this by
1439 looking for one of the known headers, and if none is found then
1440 assuming the disk image must be raw.
1441 This allows a guest which has been given a raw disk image to write some
1443 other header. At next boot (or when the disk image is accessed by
1444 libguestfs) qemu would do autodetection and think the disk image format
1445 was, say, qcow2 based on the header written by the guest.
1446 This in itself would not be a problem, but qcow2 offers many features,
1448 one of which is to allow a disk image to refer to another image (called
1449 the "backing disk"). It does this by placing the path to the backing
1450 disk into the qcow2 header. This path is not validated and could point
1451 to any host file (eg. "/etc/passwd"). The backing disk is then exposed
1452 through "holes" in the qcow2 disk image, which of course is completely
1453 under the control of the attacker.
1454 In libguestfs this is rather hard to exploit except under two
1456 circumstances:
1457 1. You have enabled the network or have opened the disk in write mode.
1459 2. You are also running untrusted code from the guest (see "RUNNING
1461 COMMANDS").
1462 The way to avoid this is to specify the expected disk format when
1464 adding disks (the optional "format" option to
1465 "guestfs_add_drive_opts"). You should always do this if the disk is
1466 raw format, and it's a good idea for other cases too. (See also "DISK
1467 IMAGE FORMATS").
1468 For disks added from libvirt using calls like "guestfs_add_domain", the
1470 format is fetched from libvirt and passed through.
1471 For libguestfs tools, use the --format command line parameter as
1473 appropriate.
1474 CVE-2011-4127
1476 https://bugzilla.redhat.com/752375
1477 This is a bug in the kernel which allowed guests to overwrite parts of
1479 the host's drives which they should not normally have access to.
1480 It is sufficient to update libguestfs to any version ≥ 1.16 which
1482 contains a change that mitigates the problem.
1483 CVE-2012-2690
1485 https://bugzilla.redhat.com/831117
1486 Old versions of both virt-edit and the guestfish "edit" command created
1488 a new file containing the changes but did not set the permissions, etc
1489 of the new file to match the old one. The result of this was that if
1490 you edited a security sensitive file such as "/etc/shadow" then it
1491 would be left world-readable after the edit.
1492 It is sufficient to update libguestfs to any version ≥ 1.16.
1494 CVE-2013-2124
1496 https://bugzilla.redhat.com/968306
1497 This security bug was a flaw in inspection where an untrusted guest
1499 using a specially crafted file in the guest OS could cause a double-
1500 free in the C library (denial of service).
1501 It is sufficient to update libguestfs to a version that is not
1503 vulnerable: libguestfs ≥ 1.20.8, ≥ 1.22.2 or ≥ 1.23.2.
1504 CVE-2013-4419
1506 https://bugzilla.redhat.com/1016960
1507 When using the guestfish(1) --remote or guestfish --listen options,
1509 guestfish would create a socket in a known location
1510 ("/tmp/.guestfish-$UID/socket-$PID").
1511 The location has to be a known one in order for both ends to
1513 communicate. However no checking was done that the containing
1514 directory ("/tmp/.guestfish-$UID") is owned by the user. Thus another
1515 user could create this directory and potentially hijack sockets owned
1516 by another user's guestfish client or server.
1517 It is sufficient to update libguestfs to a version that is not
1519 vulnerable: libguestfs ≥ 1.20.12, ≥ 1.22.7 or ≥ 1.24.
1520
1522 guestfs_h *
1523 "guestfs_h" is the opaque type representing a connection handle.
1524 Create a handle by calling "guestfs_create" or "guestfs_create_flags".
1525 Call "guestfs_close" to free the handle and release all resources used.
1526 For information on using multiple handles and threads, see the section
1528 "MULTIPLE HANDLES AND MULTIPLE THREADS" above.
1529 guestfs_create
1531 guestfs_h *guestfs_create (void);
1532 Create a connection handle.
1534 On success this returns a non-NULL pointer to a handle. On error it
1536 returns NULL.
1537 You have to "configure" the handle after creating it. This includes
1539 calling "guestfs_add_drive_opts" (or one of the equivalent calls) on
1540 the handle at least once.
1541 After configuring the handle, you have to call "guestfs_launch".
1543 You may also want to configure error handling for the handle. See the
1545 "ERROR HANDLING" section below.
1546 guestfs_create_flags
1548 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
1549 Create a connection handle, supplying extra flags and extra arguments
1551 to control how the handle is created.
1552 On success this returns a non-NULL pointer to a handle. On error it
1554 returns NULL.
1555 "guestfs_create" is equivalent to calling guestfs_create_flags(0).
1557 The following flags may be logically ORed together. (Currently no
1559 extra arguments are used).
1560 "GUESTFS_CREATE_NO_ENVIRONMENT"
1562 Don't parse any environment variables (such as "LIBGUESTFS_DEBUG"
1563 etc).
1564 You can call "guestfs_parse_environment" or
1566 "guestfs_parse_environment_list" afterwards to parse environment
1567 variables. Alternately, don't call these functions if you want the
1568 handle to be unaffected by environment variables. See the example
1569 below.
1570 The default (if this flag is not given) is to implicitly call
1572 "guestfs_parse_environment".
1573 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT"
1575 Don't try to close the handle in an atexit(3) handler if the
1576 program exits without explicitly closing the handle.
1577 The default (if this flag is not given) is to install such an
1579 atexit handler.
1580 USING "GUESTFS_CREATE_NO_ENVIRONMENT"
1582 You might use "GUESTFS_CREATE_NO_ENVIRONMENT" and an explicit call to
1584 "guestfs_parse_environment" like this:
1585 guestfs_h *g;
1587 int r;
1588 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
1590 if (!g) {
1591 perror ("guestfs_create_flags");
1592 exit (EXIT_FAILURE);
1593 }
1594 r = guestfs_parse_environment (g);
1595 if (r == -1)
1596 exit (EXIT_FAILURE);
1597 Or to create a handle which is unaffected by environment variables,
1599 omit the call to "guestfs_parse_environment" from the above code.
1600 The above code has another advantage which is that any errors from
1602 parsing the environment are passed through the error handler, whereas
1603 "guestfs_create" prints errors on stderr and ignores them.
1604 guestfs_close
1606 void guestfs_close (guestfs_h *g);
1607 This closes the connection handle and frees up all resources used. If
1609 a close callback was set on the handle, then it is called.
1610 The correct way to close the handle is:
1612 if (guestfs_shutdown (g) == -1) {
1614 /* handle write errors here */
1615 }
1616 guestfs_close (g);
1617 "guestfs_shutdown" is only needed if all of the following are true:
1619 1. one or more disks were added in read-write mode, and
1621 2. guestfs_launch was called, and
1623 3. you made some changes, and
1625 4. you have a way to handle write errors (eg. by exiting with an error
1627 code or reporting something to the user).
1628
1630 API functions can return errors. For example, almost all functions
1631 that return "int" will return "-1" to indicate an error.
1632 Additional information is available for errors: an error message string
1634 and optionally an error number (errno) if the thing that failed was a
1635 system call.
1636 You can get at the additional information about the last error on the
1638 handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1639 setting up an error handler with "guestfs_set_error_handler".
1640 When the handle is created, a default error handler is installed which
1642 prints the error message string to "stderr". For small short-running
1643 command line programs it is sufficient to do:
1644 if (guestfs_launch (g) == -1)
1646 exit (EXIT_FAILURE);
1647 since the default error handler will ensure that an error message has
1649 been printed to "stderr" before the program exits.
1650 For other programs the caller will almost certainly want to install an
1652 alternate error handler or do error handling in-line as in the example
1653 below. The non-C language bindings all install NULL error handlers and
1654 turn errors into exceptions using code similar to this:
1655 const char *msg;
1657 int errnum;
1658 /* This disables the default behaviour of printing errors
1660 on stderr. */
1661 guestfs_set_error_handler (g, NULL, NULL);
1662 if (guestfs_launch (g) == -1) {
1664 /* Examine the error message and print it, throw it,
1665 etc. */
1666 msg = guestfs_last_error (g);
1667 errnum = guestfs_last_errno (g);
1668 fprintf (stderr, "%s", msg);
1670 if (errnum != 0)
1671 fprintf (stderr, ": %s", strerror (errnum));
1672 fprintf (stderr, "\n");
1673 /* ... */
1675 }
1676 "guestfs_create" returns "NULL" if the handle cannot be created, and
1678 because there is no handle if this happens there is no way to get
1679 additional error information. Since libguestfs ≥ 1.20, you can use
1680 "guestfs_create_flags" to properly deal with errors during handle
1681 creation, although the vast majority of programs can continue to use
1682 "guestfs_create" and not worry about this situation.
1683 Out of memory errors are handled differently. The default action is to
1685 call abort(3). If this is undesirable, then you can set a handler
1686 using "guestfs_set_out_of_memory_handler".
1687 guestfs_last_error
1689 const char *guestfs_last_error (guestfs_h *g);
1690 This returns the last error message that happened on "g". If there has
1692 not been an error since the handle was created, then this returns
1693 "NULL".
1694 Note the returned string does not have a newline character at the end.
1696 Most error messages are single lines. Some are split over multiple
1697 lines and contain "\n" characters within the string but not at the end.
1698 The lifetime of the returned string is until the next error occurs on
1700 the same handle, or "guestfs_close" is called. If you need to keep it
1701 longer, copy it.
1702 guestfs_last_errno
1704 int guestfs_last_errno (guestfs_h *g);
1705 This returns the last error number (errno) that happened on "g".
1707 If successful, an errno integer not equal to zero is returned.
1709 In many cases the special errno "ENOTSUP" is returned if you tried to
1711 call a function or use a feature which is not supported.
1712 If no error number is available, this returns 0. This call can return
1714 0 in three situations:
1715 1. There has not been any error on the handle.
1717 2. There has been an error but the errno was meaningless. This
1719 corresponds to the case where the error did not come from a failed
1720 system call, but for some other reason.
1721 3. There was an error from a failed system call, but for some reason
1723 the errno was not captured and returned. This usually indicates a
1724 bug in libguestfs.
1725 Libguestfs tries to convert the errno from inside the applicance into a
1727 corresponding errno for the caller (not entirely trivial: the appliance
1728 might be running a completely different operating system from the
1729 library and error numbers are not standardized across Un*xen). If this
1730 could not be done, then the error is translated to "EINVAL". In
1731 practice this should only happen in very rare circumstances.
1732 guestfs_set_error_handler
1734 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1735 void *opaque,
1736 const char *msg);
1737 void guestfs_set_error_handler (guestfs_h *g,
1738 guestfs_error_handler_cb cb,
1739 void *opaque);
1740 The callback "cb" will be called if there is an error. The parameters
1742 passed to the callback are an opaque data pointer and the error message
1743 string.
1744 "errno" is not passed to the callback. To get that the callback must
1746 call "guestfs_last_errno".
1747 Note that the message string "msg" is freed as soon as the callback
1749 function returns, so if you want to stash it somewhere you must make
1750 your own copy.
1751 The default handler prints messages on "stderr".
1753 If you set "cb" to "NULL" then no handler is called.
1755 guestfs_get_error_handler
1757 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1758 void **opaque_rtn);
1759 Returns the current error handler callback.
1761 guestfs_push_error_handler
1763 void guestfs_push_error_handler (guestfs_h *g,
1764 guestfs_error_handler_cb cb,
1765 void *opaque);
1766 This is the same as "guestfs_set_error_handler", except that the old
1768 error handler is stashed away in a stack inside the handle. You can
1769 restore the previous error handler by calling
1770 "guestfs_pop_error_handler".
1771 Use the following code to temporarily disable errors around a function:
1773 guestfs_push_error_handler (g, NULL, NULL);
1775 guestfs_mkdir (g, "/foo"); /* We don't care if this fails. */
1776 guestfs_pop_error_handler (g);
1777 guestfs_pop_error_handler
1779 void guestfs_pop_error_handler (guestfs_h *g);
1780 Restore the previous error handler (see "guestfs_push_error_handler").
1782 If you pop the stack too many times, then the default error handler is
1784 restored.
1785 guestfs_set_out_of_memory_handler
1787 typedef void (*guestfs_abort_cb) (void);
1788 void guestfs_set_out_of_memory_handler (guestfs_h *g,
1789 guestfs_abort_cb);
1790 The callback "cb" will be called if there is an out of memory
1792 situation. Note this callback must not return.
1793 The default is to call abort(3).
1795 You cannot set "cb" to "NULL". You can't ignore out of memory
1797 situations.
1798 guestfs_get_out_of_memory_handler
1800 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1801 This returns the current out of memory handler.
1803
1805 guestfs_acl_delete_def_file
1806 int
1807 guestfs_acl_delete_def_file (guestfs_h *g,
1808 const char *dir);
1809 This function deletes the default POSIX Access Control List (ACL)
1811 attached to directory "dir".
1812 This function returns 0 on success or -1 on error.
1814 (Added in 1.19.63)
1816 guestfs_acl_get_file
1818 char *
1819 guestfs_acl_get_file (guestfs_h *g,
1820 const char *path,
1821 const char *acltype);
1822 This function returns the POSIX Access Control List (ACL) attached to
1824 "path". The ACL is returned in "long text form" (see acl(5)).
1825 The "acltype" parameter may be:
1827 "access"
1829 Return the ordinary (access) ACL for any file, directory or other
1830 filesystem object.
1831 "default"
1833 Return the default ACL. Normally this only makes sense if "path"
1834 is a directory.
1835 This function returns a string, or NULL on error. The caller must free
1837 the returned string after use.
1838 (Added in 1.19.63)
1840 guestfs_acl_set_file
1842 int
1843 guestfs_acl_set_file (guestfs_h *g,
1844 const char *path,
1845 const char *acltype,
1846 const char *acl);
1847 This function sets the POSIX Access Control List (ACL) attached to
1849 "path".
1850 The "acltype" parameter may be:
1852 "access"
1854 Set the ordinary (access) ACL for any file, directory or other
1855 filesystem object.
1856 "default"
1858 Set the default ACL. Normally this only makes sense if "path" is a
1859 directory.
1860 The "acl" parameter is the new ACL in either "long text form" or "short
1862 text form" (see acl(5)). The new ACL completely replaces any previous
1863 ACL on the file. The ACL must contain the full Unix permissions (eg.
1864 "u::rwx,g::rx,o::rx").
1865 If you are specifying individual users or groups, then the mask field
1867 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1868 "g:ID:..." field(s). A full ACL string might therefore look like this:
1869 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1871 \ Unix permissions / \mask/ \ ACL /
1872 You should use numeric UIDs and GIDs. To map usernames and groupnames
1874 to the correct numeric ID in the context of the guest, use the Augeas
1875 functions (see "guestfs_aug_init").
1876 This function returns 0 on success or -1 on error.
1878 (Added in 1.19.63)
1880 guestfs_add_cdrom
1882 int
1883 guestfs_add_cdrom (guestfs_h *g,
1884 const char *filename);
1885 This function is deprecated. In new code, use the "guestfs_add_drive"
1887 call instead.
1888 Deprecated functions will not be removed from the API, but the fact
1890 that they are deprecated indicates that there are problems with correct
1891 use of these functions.
1892 This function adds a virtual CD-ROM disk image to the guest.
1894 Do not use this function! ISO files are just ordinary read-only disk
1896 images. Use "guestfs_add_drive_ro" instead.
1897 This function returns 0 on success or -1 on error.
1899 (Added in 0.3)
1901 guestfs_add_domain
1903 int
1904 guestfs_add_domain (guestfs_h *g,
1905 const char *dom,
1906 ...);
1907 You may supply a list of optional arguments to this call. Use zero or
1909 more of the following pairs of parameters, and terminate the list with
1910 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
1911 GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
1913 GUESTFS_ADD_DOMAIN_READONLY, int readonly,
1914 GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
1915 GUESTFS_ADD_DOMAIN_LIVE, int live,
1916 GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
1917 GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
1918 This function adds the disk(s) attached to the named libvirt domain
1920 "dom". It works by connecting to libvirt, requesting the domain and
1921 domain XML from libvirt, parsing it for disks, and calling
1922 "guestfs_add_drive_opts" on each one.
1923 The number of disks added is returned. This operation is atomic: if an
1925 error is returned, then no disks are added.
1926 This function does some minimal checks to make sure the libvirt domain
1928 is not running (unless "readonly" is true). In a future version we
1929 will try to acquire the libvirt lock on each disk.
1930 Disks must be accessible locally. This often means that adding disks
1932 from a remote libvirt connection (see http://libvirt.org/remote.html)
1933 will fail unless those disks are accessible via the same device path
1934 locally too.
1935 The optional "libvirturi" parameter sets the libvirt URI (see
1937 http://libvirt.org/uri.html). If this is not set then we connect to
1938 the default libvirt URI (or one set through an environment variable,
1939 see the libvirt documentation for full details).
1940 The optional "live" flag controls whether this call will try to connect
1942 to a running virtual machine "guestfsd" process if it sees a suitable
1943 <channel> element in the libvirt XML definition. The default (if the
1944 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
1945 in guestfs(3) for more information.
1946 If the "allowuuid" flag is true (default is false) then a UUID may be
1948 passed instead of the domain name. The "dom" string is treated as a
1949 UUID first and looked up, and if that lookup fails then we treat "dom"
1950 as a name as usual.
1951 The optional "readonlydisk" parameter controls what we do for disks
1953 which are marked <readonly/> in the libvirt XML. Possible values are:
1954 readonlydisk = "error"
1956 If "readonly" is false:
1957 The whole call is aborted with an error if any disk with the
1959 <readonly/> flag is found.
1960 If "readonly" is true:
1962 Disks with the <readonly/> flag are added read-only.
1964 readonlydisk = "read"
1966 If "readonly" is false:
1967 Disks with the <readonly/> flag are added read-only. Other disks
1969 are added read/write.
1970 If "readonly" is true:
1972 Disks with the <readonly/> flag are added read-only.
1974 readonlydisk = "write" (default)
1976 If "readonly" is false:
1977 Disks with the <readonly/> flag are added read/write.
1979 If "readonly" is true:
1981 Disks with the <readonly/> flag are added read-only.
1983 readonlydisk = "ignore"
1985 If "readonly" is true or false:
1986 Disks with the <readonly/> flag are skipped.
1988 The other optional parameters are passed directly through to
1990 "guestfs_add_drive_opts".
1991 On error this function returns -1.
1993 (Added in 1.7.4)
1995 guestfs_add_domain_va
1997 int
1998 guestfs_add_domain_va (guestfs_h *g,
1999 const char *dom,
2000 va_list args);
2001 This is the "va_list variant" of "guestfs_add_domain".
2003 See "CALLS WITH OPTIONAL ARGUMENTS".
2005 guestfs_add_domain_argv
2007 int
2008 guestfs_add_domain_argv (guestfs_h *g,
2009 const char *dom,
2010 const struct guestfs_add_domain_argv *optargs);
2011 This is the "argv variant" of "guestfs_add_domain".
2013 See "CALLS WITH OPTIONAL ARGUMENTS".
2015 guestfs_add_drive
2017 int
2018 guestfs_add_drive (guestfs_h *g,
2019 const char *filename);
2020 This function is provided for backwards compatibility with earlier
2022 versions of libguestfs. It simply calls "guestfs_add_drive_opts" with
2023 no optional arguments.
2024 (Added in 0.3)
2026 guestfs_add_drive_opts
2028 int
2029 guestfs_add_drive_opts (guestfs_h *g,
2030 const char *filename,
2031 ...);
2032 You may supply a list of optional arguments to this call. Use zero or
2034 more of the following pairs of parameters, and terminate the list with
2035 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2036 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2038 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2039 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2040 GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2041 GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2042 GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2043 This function adds a disk image called "filename" to the handle.
2045 "filename" may be a regular host file or a host device.
2046 When this function is called before "guestfs_launch" (the usual case)
2048 then the first time you call this function, the disk appears in the API
2049 as "/dev/sda", the second time as "/dev/sdb", and so on.
2050 In libguestfs ≥ 1.20 you can also call this function after launch (with
2052 some restrictions). This is called "hotplugging". When hotplugging,
2053 you must specify a "label" so that the new disk gets a predictable
2054 name. For more information see "HOTPLUGGING" in guestfs(3).
2055 You don't necessarily need to be root when using libguestfs. However
2057 you obviously do need sufficient permissions to access the filename for
2058 whatever operations you want to perform (ie. read access if you just
2059 want to read the image or write access if you want to modify the
2060 image).
2061 This call checks that "filename" exists.
2063 "filename" may be the special string "/dev/null". See "NULL DISKS" in
2065 guestfs(3).
2066 The optional arguments are:
2068 "readonly"
2070 If true then the image is treated as read-only. Writes are still
2071 allowed, but they are stored in a temporary snapshot overlay which
2072 is discarded at the end. The disk that you add is not modified.
2073 "format"
2075 This forces the image format. If you omit this (or use
2076 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2077 automatically detected. Possible formats include "raw" and
2078 "qcow2".
2079 Automatic detection of the format opens you up to a potential
2081 security hole when dealing with untrusted raw-format images. See
2082 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
2083 security hole.
2084 "iface"
2086 This rarely-used option lets you emulate the behaviour of the
2087 deprecated "guestfs_add_drive_with_if" call (q.v.)
2088 "name"
2090 The name the drive had in the original guest, e.g. "/dev/sdb".
2091 This is used as a hint to the guest inspection process if it is
2092 available.
2093 "label"
2095 Give the disk a label. The label should be a unique, short string
2096 using only ASCII characters "[a-zA-Z]". As well as its usual name
2097 in the API (such as "/dev/sda"), the drive will also be named
2098 "/dev/disk/guestfs/label".
2099 See "DISK LABELS" in guestfs(3).
2101 "cachemode"
2103 Choose whether or not libguestfs will obey sync operations (safe
2104 but slow) or not (unsafe but fast). The possible values for this
2105 string are:
2106 "cachemode = "writeback""
2108 This is the default.
2109 Write operations in the API do not return until a write(2) call
2111 has completed in the host [but note this does not imply that
2112 anything gets written to disk].
2113 Sync operations in the API, including implicit syncs caused by
2115 filesystem journalling, will not return until an fdatasync(2)
2116 call has completed in the host, indicating that data has been
2117 committed to disk.
2118 "cachemode = "unsafe""
2120 In this mode, there are no guarantees. Libguestfs may cache
2121 anything and ignore sync requests. This is suitable only for
2122 scratch or temporary disks.
2123 This function returns 0 on success or -1 on error.
2125 (Added in 1.5.23)
2127 guestfs_add_drive_opts_va
2129 int
2130 guestfs_add_drive_opts_va (guestfs_h *g,
2131 const char *filename,
2132 va_list args);
2133 This is the "va_list variant" of "guestfs_add_drive_opts".
2135 See "CALLS WITH OPTIONAL ARGUMENTS".
2137 guestfs_add_drive_opts_argv
2139 int
2140 guestfs_add_drive_opts_argv (guestfs_h *g,
2141 const char *filename,
2142 const struct guestfs_add_drive_opts_argv *optargs);
2143 This is the "argv variant" of "guestfs_add_drive_opts".
2145 See "CALLS WITH OPTIONAL ARGUMENTS".
2147 guestfs_add_drive_ro
2149 int
2150 guestfs_add_drive_ro (guestfs_h *g,
2151 const char *filename);
2152 This function is the equivalent of calling "guestfs_add_drive_opts"
2154 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2155 so the disk is added read-only, with the format being detected
2156 automatically.
2157 This function returns 0 on success or -1 on error.
2159 (Added in 1.0.38)
2161 guestfs_add_drive_ro_with_if
2163 int
2164 guestfs_add_drive_ro_with_if (guestfs_h *g,
2165 const char *filename,
2166 const char *iface);
2167 This function is deprecated. In new code, use the "guestfs_add_drive"
2169 call instead.
2170 Deprecated functions will not be removed from the API, but the fact
2172 that they are deprecated indicates that there are problems with correct
2173 use of these functions.
2174 This is the same as "guestfs_add_drive_ro" but it allows you to specify
2176 the QEMU interface emulation to use at run time.
2177 This function returns 0 on success or -1 on error.
2179 (Added in 1.0.84)
2181 guestfs_add_drive_with_if
2183 int
2184 guestfs_add_drive_with_if (guestfs_h *g,
2185 const char *filename,
2186 const char *iface);
2187 This function is deprecated. In new code, use the "guestfs_add_drive"
2189 call instead.
2190 Deprecated functions will not be removed from the API, but the fact
2192 that they are deprecated indicates that there are problems with correct
2193 use of these functions.
2194 This is the same as "guestfs_add_drive" but it allows you to specify
2196 the QEMU interface emulation to use at run time.
2197 This function returns 0 on success or -1 on error.
2199 (Added in 1.0.84)
2201 guestfs_aug_clear
2203 int
2204 guestfs_aug_clear (guestfs_h *g,
2205 const char *augpath);
2206 Set the value associated with "path" to "NULL". This is the same as
2208 the augtool(1) "clear" command.
2209 This function returns 0 on success or -1 on error.
2211 (Added in 1.3.4)
2213 guestfs_aug_close
2215 int
2216 guestfs_aug_close (guestfs_h *g);
2217 Close the current Augeas handle and free up any resources used by it.
2219 After calling this, you have to call "guestfs_aug_init" again before
2220 you can use any other Augeas functions.
2221 This function returns 0 on success or -1 on error.
2223 (Added in 0.7)
2225 guestfs_aug_defnode
2227 struct guestfs_int_bool *
2228 guestfs_aug_defnode (guestfs_h *g,
2229 const char *name,
2230 const char *expr,
2231 const char *val);
2232 Defines a variable "name" whose value is the result of evaluating
2234 "expr".
2235 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2237 to calling "guestfs_aug_set" "expr", "value". "name" will be the
2238 nodeset containing that single node.
2239 On success this returns a pair containing the number of nodes in the
2241 nodeset, and a boolean flag if a node was created.
2242 This function returns a "struct guestfs_int_bool *", or NULL if there
2244 was an error. The caller must call "guestfs_free_int_bool" after use.
2245 (Added in 0.7)
2247 guestfs_aug_defvar
2249 int
2250 guestfs_aug_defvar (guestfs_h *g,
2251 const char *name,
2252 const char *expr);
2253 Defines an Augeas variable "name" whose value is the result of
2255 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2256 On success this returns the number of nodes in "expr", or 0 if "expr"
2258 evaluates to something which is not a nodeset.
2259 On error this function returns -1.
2261 (Added in 0.7)
2263 guestfs_aug_get
2265 char *
2266 guestfs_aug_get (guestfs_h *g,
2267 const char *augpath);
2268 Look up the value associated with "path". If "path" matches exactly
2270 one node, the "value" is returned.
2271 This function returns a string, or NULL on error. The caller must free
2273 the returned string after use.
2274 (Added in 0.7)
2276 guestfs_aug_init
2278 int
2279 guestfs_aug_init (guestfs_h *g,
2280 const char *root,
2281 int flags);
2282 Create a new Augeas handle for editing configuration files. If there
2284 was any previous Augeas handle associated with this guestfs session,
2285 then it is closed.
2286 You must call this before using any other "guestfs_aug_*" commands.
2288 "root" is the filesystem root. "root" must not be NULL, use "/"
2290 instead.
2291 The flags are the same as the flags defined in <augeas.h>, the logical
2293 or of the following integers:
2294 "AUG_SAVE_BACKUP" = 1
2296 Keep the original file with a ".augsave" extension.
2297 "AUG_SAVE_NEWFILE" = 2
2299 Save changes into a file with extension ".augnew", and do not
2300 overwrite original. Overrides "AUG_SAVE_BACKUP".
2301 "AUG_TYPE_CHECK" = 4
2303 Typecheck lenses.
2304 This option is only useful when debugging Augeas lenses. Use of
2306 this option may require additional memory for the libguestfs
2307 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2308 environment variable or call "guestfs_set_memsize".
2309 "AUG_NO_STDINC" = 8
2311 Do not use standard load path for modules.
2312 "AUG_SAVE_NOOP" = 16
2314 Make save a no-op, just record what would have been changed.
2315 "AUG_NO_LOAD" = 32
2317 Do not load the tree in "guestfs_aug_init".
2318 To close the handle, you can call "guestfs_aug_close".
2320 To find out more about Augeas, see http://augeas.net/.
2322 This function returns 0 on success or -1 on error.
2324 (Added in 0.7)
2326 guestfs_aug_insert
2328 int
2329 guestfs_aug_insert (guestfs_h *g,
2330 const char *augpath,
2331 const char *label,
2332 int before);
2333 Create a new sibling "label" for "path", inserting it into the tree
2335 before or after "path" (depending on the boolean flag "before").
2336 "path" must match exactly one existing node in the tree, and "label"
2338 must be a label, ie. not contain "/", "*" or end with a bracketed index
2339 "[N]".
2340 This function returns 0 on success or -1 on error.
2342 (Added in 0.7)
2344 guestfs_aug_load
2346 int
2347 guestfs_aug_load (guestfs_h *g);
2348 Load files into the tree.
2350 See "aug_load" in the Augeas documentation for the full gory details.
2352 This function returns 0 on success or -1 on error.
2354 (Added in 0.7)
2356 guestfs_aug_ls
2358 char **
2359 guestfs_aug_ls (guestfs_h *g,
2360 const char *augpath);
2361 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2363 sorting the resulting nodes into alphabetical order.
2364 This function returns a NULL-terminated array of strings (like
2366 environ(3)), or NULL if there was an error. The caller must free the
2367 strings and the array after use.
2368 (Added in 0.8)
2370 guestfs_aug_match
2372 char **
2373 guestfs_aug_match (guestfs_h *g,
2374 const char *augpath);
2375 Returns a list of paths which match the path expression "path". The
2377 returned paths are sufficiently qualified so that they match exactly
2378 one node in the current tree.
2379 This function returns a NULL-terminated array of strings (like
2381 environ(3)), or NULL if there was an error. The caller must free the
2382 strings and the array after use.
2383 (Added in 0.7)
2385 guestfs_aug_mv
2387 int
2388 guestfs_aug_mv (guestfs_h *g,
2389 const char *src,
2390 const char *dest);
2391 Move the node "src" to "dest". "src" must match exactly one node.
2393 "dest" is overwritten if it exists.
2394 This function returns 0 on success or -1 on error.
2396 (Added in 0.7)
2398 guestfs_aug_rm
2400 int
2401 guestfs_aug_rm (guestfs_h *g,
2402 const char *augpath);
2403 Remove "path" and all of its children.
2405 On success this returns the number of entries which were removed.
2407 On error this function returns -1.
2409 (Added in 0.7)
2411 guestfs_aug_save
2413 int
2414 guestfs_aug_save (guestfs_h *g);
2415 This writes all pending changes to disk.
2417 The flags which were passed to "guestfs_aug_init" affect exactly how
2419 files are saved.
2420 This function returns 0 on success or -1 on error.
2422 (Added in 0.7)
2424 guestfs_aug_set
2426 int
2427 guestfs_aug_set (guestfs_h *g,
2428 const char *augpath,
2429 const char *val);
2430 Set the value associated with "path" to "val".
2432 In the Augeas API, it is possible to clear a node by setting the value
2434 to NULL. Due to an oversight in the libguestfs API you cannot do that
2435 with this call. Instead you must use the "guestfs_aug_clear" call.
2436 This function returns 0 on success or -1 on error.
2438 (Added in 0.7)
2440 guestfs_available
2442 int
2443 guestfs_available (guestfs_h *g,
2444 char *const *groups);
2445 This command is used to check the availability of some groups of
2447 functionality in the appliance, which not all builds of the libguestfs
2448 appliance will be able to provide.
2449 The libguestfs groups, and the functions that those groups correspond
2451 to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch
2452 this list at runtime by calling "guestfs_available_all_groups".
2453 The argument "groups" is a list of group names, eg: "["inotify",
2455 "augeas"]" would check for the availability of the Linux inotify
2456 functions and Augeas (configuration file editing) functions.
2457 The command returns no error if all requested groups are available.
2459 It fails with an error if one or more of the requested groups is
2461 unavailable in the appliance.
2462 If an unknown group name is included in the list of groups then an
2464 error is always returned.
2465 Notes:
2467 · You must call "guestfs_launch" before calling this function.
2469 The reason is because we don't know what groups are supported by
2471 the appliance/daemon until it is running and can be queried.
2472 · If a group of functions is available, this does not necessarily
2474 mean that they will work. You still have to check for errors when
2475 calling individual API functions even if they are available.
2476 · It is usually the job of distro packagers to build complete
2478 functionality into the libguestfs appliance. Upstream libguestfs,
2479 if built from source with all requirements satisfied, will support
2480 everything.
2481 · This call was added in version 1.0.80. In previous versions of
2483 libguestfs all you could do would be to speculatively execute a
2484 command to find out if the daemon implemented it. See also
2485 "guestfs_version".
2486 See also "guestfs_filesystem_available".
2488 This function returns 0 on success or -1 on error.
2490 (Added in 1.0.80)
2492 guestfs_available_all_groups
2494 char **
2495 guestfs_available_all_groups (guestfs_h *g);
2496 This command returns a list of all optional groups that this daemon
2498 knows about. Note this returns both supported and unsupported groups.
2499 To find out which ones the daemon can actually support you have to call
2500 "guestfs_available" on each member of the returned list.
2501 See also "guestfs_available" and "AVAILABILITY" in guestfs(3).
2503 This function returns a NULL-terminated array of strings (like
2505 environ(3)), or NULL if there was an error. The caller must free the
2506 strings and the array after use.
2507 (Added in 1.3.15)
2509 guestfs_base64_in
2511 int
2512 guestfs_base64_in (guestfs_h *g,
2513 const char *base64file,
2514 const char *filename);
2515 This command uploads base64-encoded data from "base64file" to
2517 "filename".
2518 This function returns 0 on success or -1 on error.
2520 (Added in 1.3.5)
2522 guestfs_base64_out
2524 int
2525 guestfs_base64_out (guestfs_h *g,
2526 const char *filename,
2527 const char *base64file);
2528 This command downloads the contents of "filename", writing it out to
2530 local file "base64file" encoded as base64.
2531 This function returns 0 on success or -1 on error.
2533 (Added in 1.3.5)
2535 guestfs_blkid
2537 char **
2538 guestfs_blkid (guestfs_h *g,
2539 const char *device);
2540 This command returns block device attributes for "device". The
2542 following fields are usually present in the returned hash. Other fields
2543 may also be present.
2544 "UUID"
2546 The uuid of this device.
2547 "LABEL"
2549 The label of this device.
2550 "VERSION"
2552 The version of blkid command.
2553 "TYPE"
2555 The filesystem type or RAID of this device.
2556 "USAGE"
2558 The usage of this device, for example "filesystem" or "raid".
2559 This function returns a NULL-terminated array of strings, or NULL if
2561 there was an error. The array of strings will always have length
2562 "2n+1", where "n" keys and values alternate, followed by the trailing
2563 NULL entry. The caller must free the strings and the array after use.
2564 (Added in 1.15.9)
2566 guestfs_blockdev_flushbufs
2568 int
2569 guestfs_blockdev_flushbufs (guestfs_h *g,
2570 const char *device);
2571 This tells the kernel to flush internal buffers associated with
2573 "device".
2574 This uses the blockdev(8) command.
2576 This function returns 0 on success or -1 on error.
2578 (Added in 0.9.3)
2580 guestfs_blockdev_getbsz
2582 int
2583 guestfs_blockdev_getbsz (guestfs_h *g,
2584 const char *device);
2585 This returns the block size of a device.
2587 Note: this is different from both size in blocks and filesystem block
2589 size. Also this setting is not really used by anything. You should
2590 probably not use it for anything. Filesystems have their own idea
2591 about what block size to choose.
2592 This uses the blockdev(8) command.
2594 On error this function returns -1.
2596 (Added in 0.9.3)
2598 guestfs_blockdev_getro
2600 int
2601 guestfs_blockdev_getro (guestfs_h *g,
2602 const char *device);
2603 Returns a boolean indicating if the block device is read-only (true if
2605 read-only, false if not).
2606 This uses the blockdev(8) command.
2608 This function returns a C truth value on success or -1 on error.
2610 (Added in 0.9.3)
2612 guestfs_blockdev_getsize64
2614 int64_t
2615 guestfs_blockdev_getsize64 (guestfs_h *g,
2616 const char *device);
2617 This returns the size of the device in bytes.
2619 See also "guestfs_blockdev_getsz".
2621 This uses the blockdev(8) command.
2623 On error this function returns -1.
2625 (Added in 0.9.3)
2627 guestfs_blockdev_getss
2629 int
2630 guestfs_blockdev_getss (guestfs_h *g,
2631 const char *device);
2632 This returns the size of sectors on a block device. Usually 512, but
2634 can be larger for modern devices.
2635 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
2637 for that).
2638 This uses the blockdev(8) command.
2640 On error this function returns -1.
2642 (Added in 0.9.3)
2644 guestfs_blockdev_getsz
2646 int64_t
2647 guestfs_blockdev_getsz (guestfs_h *g,
2648 const char *device);
2649 This returns the size of the device in units of 512-byte sectors (even
2651 if the sectorsize isn't 512 bytes ... weird).
2652 See also "guestfs_blockdev_getss" for the real sector size of the
2654 device, and "guestfs_blockdev_getsize64" for the more useful size in
2655 bytes.
2656 This uses the blockdev(8) command.
2658 On error this function returns -1.
2660 (Added in 0.9.3)
2662 guestfs_blockdev_rereadpt
2664 int
2665 guestfs_blockdev_rereadpt (guestfs_h *g,
2666 const char *device);
2667 Reread the partition table on "device".
2669 This uses the blockdev(8) command.
2671 This function returns 0 on success or -1 on error.
2673 (Added in 0.9.3)
2675 guestfs_blockdev_setbsz
2677 int
2678 guestfs_blockdev_setbsz (guestfs_h *g,
2679 const char *device,
2680 int blocksize);
2681 This function is deprecated. In new code, use the "guestfs_mkfs" call
2683 instead.
2684 Deprecated functions will not be removed from the API, but the fact
2686 that they are deprecated indicates that there are problems with correct
2687 use of these functions.
2688 This call does nothing and has never done anything because of a bug in
2690 blockdev. Do not use it.
2691 If you need to set the filesystem block size, use the "blocksize"
2693 option of "guestfs_mkfs".
2694 This function returns 0 on success or -1 on error.
2696 (Added in 0.9.3)
2698 guestfs_blockdev_setro
2700 int
2701 guestfs_blockdev_setro (guestfs_h *g,
2702 const char *device);
2703 Sets the block device named "device" to read-only.
2705 This uses the blockdev(8) command.
2707 This function returns 0 on success or -1 on error.
2709 (Added in 0.9.3)
2711 guestfs_blockdev_setrw
2713 int
2714 guestfs_blockdev_setrw (guestfs_h *g,
2715 const char *device);
2716 Sets the block device named "device" to read-write.
2718 This uses the blockdev(8) command.
2720 This function returns 0 on success or -1 on error.
2722 (Added in 0.9.3)
2724 guestfs_btrfs_device_add
2726 int
2727 guestfs_btrfs_device_add (guestfs_h *g,
2728 char *const *devices,
2729 const char *fs);
2730 Add the list of device(s) in "devices" to the btrfs filesystem mounted
2732 at "fs". If "devices" is an empty list, this does nothing.
2733 This function returns 0 on success or -1 on error.
2735 (Added in 1.17.35)
2737 guestfs_btrfs_device_delete
2739 int
2740 guestfs_btrfs_device_delete (guestfs_h *g,
2741 char *const *devices,
2742 const char *fs);
2743 Remove the "devices" from the btrfs filesystem mounted at "fs". If
2745 "devices" is an empty list, this does nothing.
2746 This function returns 0 on success or -1 on error.
2748 (Added in 1.17.35)
2750 guestfs_btrfs_filesystem_balance
2752 int
2753 guestfs_btrfs_filesystem_balance (guestfs_h *g,
2754 const char *fs);
2755 Balance the chunks in the btrfs filesystem mounted at "fs" across the
2757 underlying devices.
2758 This function returns 0 on success or -1 on error.
2760 (Added in 1.17.35)
2762 guestfs_btrfs_filesystem_resize
2764 int
2765 guestfs_btrfs_filesystem_resize (guestfs_h *g,
2766 const char *mountpoint,
2767 ...);
2768 You may supply a list of optional arguments to this call. Use zero or
2770 more of the following pairs of parameters, and terminate the list with
2771 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2772 GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
2774 This command resizes a btrfs filesystem.
2776 Note that unlike other resize calls, the filesystem has to be mounted
2778 and the parameter is the mountpoint not the device (this is a
2779 requirement of btrfs itself).
2780 The optional parameters are:
2782 "size"
2784 The new size (in bytes) of the filesystem. If omitted, the
2785 filesystem is resized to the maximum size.
2786 See also btrfs(8).
2788 This function returns 0 on success or -1 on error.
2790 (Added in 1.11.17)
2792 guestfs_btrfs_filesystem_resize_va
2794 int
2795 guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
2796 const char *mountpoint,
2797 va_list args);
2798 This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
2800 See "CALLS WITH OPTIONAL ARGUMENTS".
2802 guestfs_btrfs_filesystem_resize_argv
2804 int
2805 guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
2806 const char *mountpoint,
2807 const struct guestfs_btrfs_filesystem_resize_argv *optargs);
2808 This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
2810 See "CALLS WITH OPTIONAL ARGUMENTS".
2812 guestfs_btrfs_filesystem_sync
2814 int
2815 guestfs_btrfs_filesystem_sync (guestfs_h *g,
2816 const char *fs);
2817 Force sync on the btrfs filesystem mounted at "fs".
2819 This function returns 0 on success or -1 on error.
2821 (Added in 1.17.35)
2823 guestfs_btrfs_fsck
2825 int
2826 guestfs_btrfs_fsck (guestfs_h *g,
2827 const char *device,
2828 ...);
2829 You may supply a list of optional arguments to this call. Use zero or
2831 more of the following pairs of parameters, and terminate the list with
2832 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2833 GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
2835 GUESTFS_BTRFS_FSCK_REPAIR, int repair,
2836 Used to check a btrfs filesystem, "device" is the device file where the
2838 filesystem is stored.
2839 This function returns 0 on success or -1 on error.
2841 (Added in 1.17.43)
2843 guestfs_btrfs_fsck_va
2845 int
2846 guestfs_btrfs_fsck_va (guestfs_h *g,
2847 const char *device,
2848 va_list args);
2849 This is the "va_list variant" of "guestfs_btrfs_fsck".
2851 See "CALLS WITH OPTIONAL ARGUMENTS".
2853 guestfs_btrfs_fsck_argv
2855 int
2856 guestfs_btrfs_fsck_argv (guestfs_h *g,
2857 const char *device,
2858 const struct guestfs_btrfs_fsck_argv *optargs);
2859 This is the "argv variant" of "guestfs_btrfs_fsck".
2861 See "CALLS WITH OPTIONAL ARGUMENTS".
2863 guestfs_btrfs_set_seeding
2865 int
2866 guestfs_btrfs_set_seeding (guestfs_h *g,
2867 const char *device,
2868 int seeding);
2869 Enable or disable the seeding feature of a device that contains a btrfs
2871 filesystem.
2872 This function returns 0 on success or -1 on error.
2874 (Added in 1.17.43)
2876 guestfs_btrfs_subvolume_create
2878 int
2879 guestfs_btrfs_subvolume_create (guestfs_h *g,
2880 const char *dest);
2881 Create a btrfs subvolume. The "dest" argument is the destination
2883 directory and the name of the snapshot, in the form
2884 "/path/to/dest/name".
2885 This function returns 0 on success or -1 on error.
2887 (Added in 1.17.35)
2889 guestfs_btrfs_subvolume_delete
2891 int
2892 guestfs_btrfs_subvolume_delete (guestfs_h *g,
2893 const char *subvolume);
2894 Delete the named btrfs subvolume.
2896 This function returns 0 on success or -1 on error.
2898 (Added in 1.17.35)
2900 guestfs_btrfs_subvolume_list
2902 struct guestfs_btrfssubvolume_list *
2903 guestfs_btrfs_subvolume_list (guestfs_h *g,
2904 const char *fs);
2905 List the btrfs snapshots and subvolumes of the btrfs filesystem which
2907 is mounted at "fs".
2908 This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
2910 if there was an error. The caller must call
2911 "guestfs_free_btrfssubvolume_list" after use.
2912 (Added in 1.17.35)
2914 guestfs_btrfs_subvolume_set_default
2916 int
2917 guestfs_btrfs_subvolume_set_default (guestfs_h *g,
2918 int64_t id,
2919 const char *fs);
2920 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
2922 default. See "guestfs_btrfs_subvolume_list" to get a list of
2923 subvolumes.
2924 This function returns 0 on success or -1 on error.
2926 (Added in 1.17.35)
2928 guestfs_btrfs_subvolume_snapshot
2930 int
2931 guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
2932 const char *source,
2933 const char *dest);
2934 Create a writable snapshot of the btrfs subvolume "source". The "dest"
2936 argument is the destination directory and the name of the snapshot, in
2937 the form "/path/to/dest/name".
2938 This function returns 0 on success or -1 on error.
2940 (Added in 1.17.35)
2942 guestfs_canonical_device_name
2944 char *
2945 guestfs_canonical_device_name (guestfs_h *g,
2946 const char *device);
2947 This utility function is useful when displaying device names to the
2949 user. It takes a number of irregular device names and returns them in
2950 a consistent format:
2951 "/dev/hdX"
2953 "/dev/vdX"
2954 These are returned as "/dev/sdX". Note this works for device names
2955 and partition names. This is approximately the reverse of the
2956 algorithm described in "BLOCK DEVICE NAMING" in guestfs(3).
2957 "/dev/mapper/VG-LV"
2959 "/dev/dm-N"
2960 Converted to "/dev/VG/LV" form using
2961 "guestfs_lvm_canonical_lvm_name".
2962 Other strings are returned unmodified.
2964 This function returns a string, or NULL on error. The caller must free
2966 the returned string after use.
2967 (Added in 1.19.7)
2969 guestfs_cap_get_file
2971 char *
2972 guestfs_cap_get_file (guestfs_h *g,
2973 const char *path);
2974 This function returns the Linux capabilities attached to "path". The
2976 capabilities set is returned in text form (see cap_to_text(3)).
2977 If no capabilities are attached to a file, an empty string is returned.
2979 This function returns a string, or NULL on error. The caller must free
2981 the returned string after use.
2982 (Added in 1.19.63)
2984 guestfs_cap_set_file
2986 int
2987 guestfs_cap_set_file (guestfs_h *g,
2988 const char *path,
2989 const char *cap);
2990 This function sets the Linux capabilities attached to "path". The
2992 capabilities set "cap" should be passed in text form (see
2993 cap_from_text(3)).
2994 This function returns 0 on success or -1 on error.
2996 (Added in 1.19.63)
2998 guestfs_case_sensitive_path
3000 char *
3001 guestfs_case_sensitive_path (guestfs_h *g,
3002 const char *path);
3003 This can be used to resolve case insensitive paths on a filesystem
3005 which is case sensitive. The use case is to resolve paths which you
3006 have read from Windows configuration files or the Windows Registry, to
3007 the true path.
3008 The command handles a peculiarity of the Linux ntfs-3g filesystem
3010 driver (and probably others), which is that although the underlying
3011 filesystem is case-insensitive, the driver exports the filesystem to
3012 Linux as case-sensitive.
3013 One consequence of this is that special directories such as
3015 "c:\windows" may appear as "/WINDOWS" or "/windows" (or other things)
3016 depending on the precise details of how they were created. In Windows
3017 itself this would not be a problem.
3018 Bug or feature? You decide:
3020 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
3021 This function resolves the true case of each element in the path and
3023 returns the case-sensitive path.
3024 Thus "guestfs_case_sensitive_path" ("/Windows/System32") might return
3026 "/WINDOWS/system32" (the exact return value would depend on details of
3027 how the directories were originally created under Windows).
3028 Note: This function does not handle drive names, backslashes etc.
3030 See also "guestfs_realpath".
3032 This function returns a string, or NULL on error. The caller must free
3034 the returned string after use.
3035 (Added in 1.0.75)
3037 guestfs_cat
3039 char *
3040 guestfs_cat (guestfs_h *g,
3041 const char *path);
3042 Return the contents of the file named "path".
3044 Because, in C, this function returns a "char *", there is no way to
3046 differentiate between a "\0" character in a file and end of string. To
3047 handle binary files, use the "guestfs_read_file" or "guestfs_download"
3048 functions.
3049 This function returns a string, or NULL on error. The caller must free
3051 the returned string after use.
3052 (Added in 0.4)
3054 guestfs_checksum
3056 char *
3057 guestfs_checksum (guestfs_h *g,
3058 const char *csumtype,
3059 const char *path);
3060 This call computes the MD5, SHAx or CRC checksum of the file named
3062 "path".
3063 The type of checksum to compute is given by the "csumtype" parameter
3065 which must have one of the following values:
3066 "crc"
3068 Compute the cyclic redundancy check (CRC) specified by POSIX for
3069 the "cksum" command.
3070 "md5"
3072 Compute the MD5 hash (using the "md5sum" program).
3073 "sha1"
3075 Compute the SHA1 hash (using the "sha1sum" program).
3076 "sha224"
3078 Compute the SHA224 hash (using the "sha224sum" program).
3079 "sha256"
3081 Compute the SHA256 hash (using the "sha256sum" program).
3082 "sha384"
3084 Compute the SHA384 hash (using the "sha384sum" program).
3085 "sha512"
3087 Compute the SHA512 hash (using the "sha512sum" program).
3088 The checksum is returned as a printable string.
3090 To get the checksum for a device, use "guestfs_checksum_device".
3092 To get the checksums for many files, use "guestfs_checksums_out".
3094 This function returns a string, or NULL on error. The caller must free
3096 the returned string after use.
3097 (Added in 1.0.2)
3099 guestfs_checksum_device
3101 char *
3102 guestfs_checksum_device (guestfs_h *g,
3103 const char *csumtype,
3104 const char *device);
3105 This call computes the MD5, SHAx or CRC checksum of the contents of the
3107 device named "device". For the types of checksums supported see the
3108 "guestfs_checksum" command.
3109 This function returns a string, or NULL on error. The caller must free
3111 the returned string after use.
3112 (Added in 1.3.2)
3114 guestfs_checksums_out
3116 int
3117 guestfs_checksums_out (guestfs_h *g,
3118 const char *csumtype,
3119 const char *directory,
3120 const char *sumsfile);
3121 This command computes the checksums of all regular files in "directory"
3123 and then emits a list of those checksums to the local output file
3124 "sumsfile".
3125 This can be used for verifying the integrity of a virtual machine.
3127 However to be properly secure you should pay attention to the output of
3128 the checksum command (it uses the ones from GNU coreutils). In
3129 particular when the filename is not printable, coreutils uses a special
3130 backslash syntax. For more information, see the GNU coreutils info
3131 file.
3132 This function returns 0 on success or -1 on error.
3134 (Added in 1.3.7)
3136 guestfs_chmod
3138 int
3139 guestfs_chmod (guestfs_h *g,
3140 int mode,
3141 const char *path);
3142 Change the mode (permissions) of "path" to "mode". Only numeric modes
3144 are supported.
3145 Note: When using this command from guestfish, "mode" by default would
3147 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
3148 700.
3149 The mode actually set is affected by the umask.
3151 This function returns 0 on success or -1 on error.
3153 (Added in 0.8)
3155 guestfs_chown
3157 int
3158 guestfs_chown (guestfs_h *g,
3159 int owner,
3160 int group,
3161 const char *path);
3162 Change the file owner to "owner" and group to "group".
3164 Only numeric uid and gid are supported. If you want to use names, you
3166 will need to locate and parse the password file yourself (Augeas
3167 support makes this relatively easy).
3168 This function returns 0 on success or -1 on error.
3170 (Added in 0.8)
3172 guestfs_command
3174 char *
3175 guestfs_command (guestfs_h *g,
3176 char *const *arguments);
3177 This call runs a command from the guest filesystem. The filesystem
3179 must be mounted, and must contain a compatible operating system (ie.
3180 something Linux, with the same or compatible processor architecture).
3181 The single parameter is an argv-style list of arguments. The first
3183 element is the name of the program to run. Subsequent elements are
3184 parameters. The list must be non-empty (ie. must contain a program
3185 name). Note that the command runs directly, and is not invoked via the
3186 shell (see "guestfs_sh").
3187 The return value is anything printed to stdout by the command.
3189 If the command returns a non-zero exit status, then this function
3191 returns an error message. The error message string is the content of
3192 stderr from the command.
3193 The $PATH environment variable will contain at least "/usr/bin" and
3195 "/bin". If you require a program from another location, you should
3196 provide the full path in the first parameter.
3197 Shared libraries and data files required by the program must be
3199 available on filesystems which are mounted in the correct places. It
3200 is the caller's responsibility to ensure all filesystems that are
3201 needed are mounted at the right locations.
3202 This function returns a string, or NULL on error. The caller must free
3204 the returned string after use.
3205 Because of the message protocol, there is a transfer limit of somewhere
3207 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3208 (Added in 0.9.1)
3210 guestfs_command_lines
3212 char **
3213 guestfs_command_lines (guestfs_h *g,
3214 char *const *arguments);
3215 This is the same as "guestfs_command", but splits the result into a
3217 list of lines.
3218 See also: "guestfs_sh_lines"
3220 This function returns a NULL-terminated array of strings (like
3222 environ(3)), or NULL if there was an error. The caller must free the
3223 strings and the array after use.
3224 Because of the message protocol, there is a transfer limit of somewhere
3226 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3227 (Added in 0.9.1)
3229 guestfs_compress_device_out
3231 int
3232 guestfs_compress_device_out (guestfs_h *g,
3233 const char *ctype,
3234 const char *device,
3235 const char *zdevice,
3236 ...);
3237 You may supply a list of optional arguments to this call. Use zero or
3239 more of the following pairs of parameters, and terminate the list with
3240 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3241 GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
3243 This command compresses "device" and writes it out to the local file
3245 "zdevice".
3246 The "ctype" and optional "level" parameters have the same meaning as in
3248 "guestfs_compress_out".
3249 This function returns 0 on success or -1 on error.
3251 (Added in 1.13.15)
3253 guestfs_compress_device_out_va
3255 int
3256 guestfs_compress_device_out_va (guestfs_h *g,
3257 const char *ctype,
3258 const char *device,
3259 const char *zdevice,
3260 va_list args);
3261 This is the "va_list variant" of "guestfs_compress_device_out".
3263 See "CALLS WITH OPTIONAL ARGUMENTS".
3265 guestfs_compress_device_out_argv
3267 int
3268 guestfs_compress_device_out_argv (guestfs_h *g,
3269 const char *ctype,
3270 const char *device,
3271 const char *zdevice,
3272 const struct guestfs_compress_device_out_argv *optargs);
3273 This is the "argv variant" of "guestfs_compress_device_out".
3275 See "CALLS WITH OPTIONAL ARGUMENTS".
3277 guestfs_compress_out
3279 int
3280 guestfs_compress_out (guestfs_h *g,
3281 const char *ctype,
3282 const char *file,
3283 const char *zfile,
3284 ...);
3285 You may supply a list of optional arguments to this call. Use zero or
3287 more of the following pairs of parameters, and terminate the list with
3288 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3289 GUESTFS_COMPRESS_OUT_LEVEL, int level,
3291 This command compresses "file" and writes it out to the local file
3293 "zfile".
3294 The compression program used is controlled by the "ctype" parameter.
3296 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
3297 Some compression types may not be supported by particular builds of
3298 libguestfs, in which case you will get an error containing the
3299 substring "not supported".
3300 The optional "level" parameter controls compression level. The meaning
3302 and default for this parameter depends on the compression program being
3303 used.
3304 This function returns 0 on success or -1 on error.
3306 (Added in 1.13.15)
3308 guestfs_compress_out_va
3310 int
3311 guestfs_compress_out_va (guestfs_h *g,
3312 const char *ctype,
3313 const char *file,
3314 const char *zfile,
3315 va_list args);
3316 This is the "va_list variant" of "guestfs_compress_out".
3318 See "CALLS WITH OPTIONAL ARGUMENTS".
3320 guestfs_compress_out_argv
3322 int
3323 guestfs_compress_out_argv (guestfs_h *g,
3324 const char *ctype,
3325 const char *file,
3326 const char *zfile,
3327 const struct guestfs_compress_out_argv *optargs);
3328 This is the "argv variant" of "guestfs_compress_out".
3330 See "CALLS WITH OPTIONAL ARGUMENTS".
3332 guestfs_config
3334 int
3335 guestfs_config (guestfs_h *g,
3336 const char *qemuparam,
3337 const char *qemuvalue);
3338 This can be used to add arbitrary qemu command line parameters of the
3340 form -param value. Actually it's not quite arbitrary - we prevent you
3341 from setting some parameters which would interfere with parameters that
3342 we use.
3343 The first character of "qemuparam" string must be a "-" (dash).
3345 "qemuvalue" can be NULL.
3347 This function returns 0 on success or -1 on error.
3349 (Added in 0.3)
3351 guestfs_copy_device_to_device
3353 int
3354 guestfs_copy_device_to_device (guestfs_h *g,
3355 const char *src,
3356 const char *dest,
3357 ...);
3358 You may supply a list of optional arguments to this call. Use zero or
3360 more of the following pairs of parameters, and terminate the list with
3361 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3362 GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
3364 GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
3365 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
3366 The four calls "guestfs_copy_device_to_device",
3368 "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
3369 "guestfs_copy_file_to_file" let you copy from a source (device|file) to
3370 a destination (device|file).
3371 Partial copies can be made since you can specify optionally the source
3373 offset, destination offset and size to copy. These values are all
3374 specified in bytes. If not given, the offsets both default to zero,
3375 and the size defaults to copying as much as possible until we hit the
3376 end of the source.
3377 The source and destination may be the same object. However overlapping
3379 regions may not be copied correctly.
3380 If the destination is a file, it is created if required. If the
3382 destination file is not large enough, it is extended.
3383 This function returns 0 on success or -1 on error.
3385 This long-running command can generate progress notification messages
3387 so that the caller can display a progress bar or indicator. To receive
3388 these messages, the caller must register a progress event callback.
3389 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
3390 (Added in 1.13.25)
3392 guestfs_copy_device_to_device_va
3394 int
3395 guestfs_copy_device_to_device_va (guestfs_h *g,
3396 const char *src,
3397 const char *dest,
3398 va_list args);
3399 This is the "va_list variant" of "guestfs_copy_device_to_device".
3401 See "CALLS WITH OPTIONAL ARGUMENTS".
3403 guestfs_copy_device_to_device_argv
3405 int
3406 guestfs_copy_device_to_device_argv (guestfs_h *g,
3407 const char *src,
3408 const char *dest,
3409 const struct guestfs_copy_device_to_device_argv *optargs);
3410 This is the "argv variant" of "guestfs_copy_device_to_device".
3412 See "CALLS WITH OPTIONAL ARGUMENTS".
3414 guestfs_copy_device_to_file
3416 int
3417 guestfs_copy_device_to_file (guestfs_h *g,
3418 const char *src,
3419 const char *dest,
3420 ...);
3421 You may supply a list of optional arguments to this call. Use zero or
3423 more of the following pairs of parameters, and terminate the list with
3424 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3425 GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
3427 GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
3428 GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
3429 See "guestfs_copy_device_to_device" for a general overview of this
3431 call.
3432 This function returns 0 on success or -1 on error.
3434 This long-running command can generate progress notification messages
3436 so that the caller can display a progress bar or indicator. To receive
3437 these messages, the caller must register a progress event callback.
3438 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
3439 (Added in 1.13.25)
3441 guestfs_copy_device_to_file_va
3443 int
3444 guestfs_copy_device_to_file_va (guestfs_h *g,
3445 const char *src,
3446 const char *dest,
3447 va_list args);
3448 This is the "va_list variant" of "guestfs_copy_device_to_file".
3450 See "CALLS WITH OPTIONAL ARGUMENTS".
3452 guestfs_copy_device_to_file_argv
3454 int
3455 guestfs_copy_device_to_file_argv (guestfs_h *g,
3456 const char *src,
3457 const char *dest,
3458 const struct guestfs_copy_device_to_file_argv *optargs);
3459 This is the "argv variant" of "guestfs_copy_device_to_file".
3461 See "CALLS WITH OPTIONAL ARGUMENTS".
3463 guestfs_copy_file_to_device
3465 int
3466 guestfs_copy_file_to_device (guestfs_h *g,
3467 const char *src,
3468 const char *dest,
3469 ...);
3470 You may supply a list of optional arguments to this call. Use zero or
3472 more of the following pairs of parameters, and terminate the list with
3473 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3474 GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
3476 GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
3477 GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
3478 See "guestfs_copy_device_to_device" for a general overview of this
3480 call.
3481 This function returns 0 on success or -1 on error.
3483 This long-running command can generate progress notification messages
3485 so that the caller can display a progress bar or indicator. To receive
3486 these messages, the caller must register a progress event callback.
3487 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
3488 (Added in 1.13.25)
3490 guestfs_copy_file_to_device_va
3492 int
3493 guestfs_copy_file_to_device_va (guestfs_h *g,
3494 const char *src,
3495 const char *dest,
3496 va_list args);
3497 This is the "va_list variant" of "guestfs_copy_file_to_device".
3499 See "CALLS WITH OPTIONAL ARGUMENTS".
3501 guestfs_copy_file_to_device_argv
3503 int
3504 guestfs_copy_file_to_device_argv (guestfs_h *g,
3505 const char *src,
3506 const char *dest,
3507 const struct guestfs_copy_file_to_device_argv *optargs);
3508 This is the "argv variant" of "guestfs_copy_file_to_device".
3510 See "CALLS WITH OPTIONAL ARGUMENTS".
3512 guestfs_copy_file_to_file
3514 int
3515 guestfs_copy_file_to_file (guestfs_h *g,
3516 const char *src,
3517 const char *dest,
3518 ...);
3519 You may supply a list of optional arguments to this call. Use zero or
3521 more of the following pairs of parameters, and terminate the list with
3522 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3523 GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
3525 GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
3526 GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
3527 See "guestfs_copy_device_to_device" for a general overview of this
3529 call.
3530 This is not the function you want for copying files. This is for
3532 copying blocks within existing files. See "guestfs_cp", "guestfs_cp_a"
3533 and "guestfs_mv" for general file copying and moving functions.
3534 This function returns 0 on success or -1 on error.
3536 This long-running command can generate progress notification messages
3538 so that the caller can display a progress bar or indicator. To receive
3539 these messages, the caller must register a progress event callback.
3540 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
3541 (Added in 1.13.25)
3543 guestfs_copy_file_to_file_va
3545 int
3546 guestfs_copy_file_to_file_va (guestfs_h *g,
3547 const char *src,
3548 const char *dest,
3549 va_list args);
3550 This is the "va_list variant" of "guestfs_copy_file_to_file".
3552 See "CALLS WITH OPTIONAL ARGUMENTS".
3554 guestfs_copy_file_to_file_argv
3556 int
3557 guestfs_copy_file_to_file_argv (guestfs_h *g,
3558 const char *src,
3559 const char *dest,
3560 const struct guestfs_copy_file_to_file_argv *optargs);
3561 This is the "argv variant" of "guestfs_copy_file_to_file".
3563 See "CALLS WITH OPTIONAL ARGUMENTS".
3565 guestfs_copy_size
3567 int
3568 guestfs_copy_size (guestfs_h *g,
3569 const char *src,
3570 const char *dest,
3571 int64_t size);
3572 This function is deprecated. In new code, use the
3574 "guestfs_copy_device_to_device" call instead.
3575 Deprecated functions will not be removed from the API, but the fact
3577 that they are deprecated indicates that there are problems with correct
3578 use of these functions.
3579 This command copies exactly "size" bytes from one source device or file
3581 "src" to another destination device or file "dest".
3582 Note this will fail if the source is too short or if the destination is
3584 not large enough.
3585 This function returns 0 on success or -1 on error.
3587 This long-running command can generate progress notification messages
3589 so that the caller can display a progress bar or indicator. To receive
3590 these messages, the caller must register a progress event callback.
3591 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
3592 (Added in 1.0.87)
3594 guestfs_cp
3596 int
3597 guestfs_cp (guestfs_h *g,
3598 const char *src,
3599 const char *dest);
3600 This copies a file from "src" to "dest" where "dest" is either a
3602 destination filename or destination directory.
3603 This function returns 0 on success or -1 on error.
3605 (Added in 1.0.18)
3607 guestfs_cp_a
3609 int
3610 guestfs_cp_a (guestfs_h *g,
3611 const char *src,
3612 const char *dest);
3613 This copies a file or directory from "src" to "dest" recursively using
3615 the "cp -a" command.
3616 This function returns 0 on success or -1 on error.
3618 (Added in 1.0.18)
3620 guestfs_dd
3622 int
3623 guestfs_dd (guestfs_h *g,
3624 const char *src,
3625 const char *dest);
3626 This function is deprecated. In new code, use the
3628 "guestfs_copy_device_to_device" call instead.
3629 Deprecated functions will not be removed from the API, but the fact
3631 that they are deprecated indicates that there are problems with correct
3632 use of these functions.
3633 This command copies from one source device or file "src" to another
3635 destination device or file "dest". Normally you would use this to copy
3636 to or from a device or partition, for example to duplicate a
3637 filesystem.
3638 If the destination is a device, it must be as large or larger than the
3640 source file or device, otherwise the copy will fail. This command
3641 cannot do partial copies (see "guestfs_copy_device_to_device").
3642 This function returns 0 on success or -1 on error.
3644 (Added in 1.0.80)
3646 guestfs_device_index
3648 int
3649 guestfs_device_index (guestfs_h *g,
3650 const char *device);
3651 This function takes a device name (eg. "/dev/sdb") and returns the
3653 index of the device in the list of devices.
3654 Index numbers start from 0. The named device must exist, for example
3656 as a string returned from "guestfs_list_devices".
3657 See also "guestfs_list_devices", "guestfs_part_to_dev".
3659 On error this function returns -1.
3661 (Added in 1.19.7)
3663 guestfs_df
3665 char *
3666 guestfs_df (guestfs_h *g);
3667 This command runs the "df" command to report disk space used.
3669 This command is mostly useful for interactive sessions. It is not
3671 intended that you try to parse the output string. Use
3672 "guestfs_statvfs" from programs.
3673 This function returns a string, or NULL on error. The caller must free
3675 the returned string after use.
3676 (Added in 1.0.54)
3678 guestfs_df_h
3680 char *
3681 guestfs_df_h (guestfs_h *g);
3682 This command runs the "df -h" command to report disk space used in
3684 human-readable format.
3685 This command is mostly useful for interactive sessions. It is not
3687 intended that you try to parse the output string. Use
3688 "guestfs_statvfs" from programs.
3689 This function returns a string, or NULL on error. The caller must free
3691 the returned string after use.
3692 (Added in 1.0.54)
3694 guestfs_disk_format
3696 char *
3697 guestfs_disk_format (guestfs_h *g,
3698 const char *filename);
3699 Detect and return the format of the disk image called "filename".
3701 "filename" can also be a host device, etc. If the format of the image
3702 could not be detected, then "unknown" is returned.
3703 Note that detecting the disk format can be insecure under some
3705 circumstances. See "CVE-2010-3851" in guestfs(3).
3706 See also: "DISK IMAGE FORMATS" in guestfs(3)
3708 This function returns a string, or NULL on error. The caller must free
3710 the returned string after use.
3711 (Added in 1.19.38)
3713 guestfs_disk_has_backing_file
3715 int
3716 guestfs_disk_has_backing_file (guestfs_h *g,
3717 const char *filename);
3718 Detect and return whether the disk image "filename" has a backing file.
3720 Note that detecting disk features can be insecure under some
3722 circumstances. See "CVE-2010-3851" in guestfs(3).
3723 This function returns a C truth value on success or -1 on error.
3725 (Added in 1.19.39)
3727 guestfs_disk_virtual_size
3729 int64_t
3730 guestfs_disk_virtual_size (guestfs_h *g,
3731 const char *filename);
3732 Detect and return the virtual size in bytes of the disk image called
3734 "filename".
3735 Note that detecting disk features can be insecure under some
3737 circumstances. See "CVE-2010-3851" in guestfs(3).
3738 On error this function returns -1.
3740 (Added in 1.19.39)
3742 guestfs_dmesg
3744 char *
3745 guestfs_dmesg (guestfs_h *g);
3746 This returns the kernel messages ("dmesg" output) from the guest
3748 kernel. This is sometimes useful for extended debugging of problems.
3749 Another way to get the same information is to enable verbose messages
3751 with "guestfs_set_verbose" or by setting the environment variable
3752 "LIBGUESTFS_DEBUG=1" before running the program.
3753 This function returns a string, or NULL on error. The caller must free
3755 the returned string after use.
3756 (Added in 1.0.18)
3758 guestfs_download
3760 int
3761 guestfs_download (guestfs_h *g,
3762 const char *remotefilename,
3763 const char *filename);
3764 Download file "remotefilename" and save it as "filename" on the local
3766 machine.
3767 "filename" can also be a named pipe.
3769 See also "guestfs_upload", "guestfs_cat".
3771 This function returns 0 on success or -1 on error.
3773 This long-running command can generate progress notification messages
3775 so that the caller can display a progress bar or indicator. To receive
3776 these messages, the caller must register a progress event callback.
3777 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
3778 (Added in 1.0.2)
3780 guestfs_download_offset
3782 int
3783 guestfs_download_offset (guestfs_h *g,
3784 const char *remotefilename,
3785 const char *filename,
3786 int64_t offset,
3787 int64_t size);
3788 Download file "remotefilename" and save it as "filename" on the local
3790 machine.
3791 "remotefilename" is read for "size" bytes starting at "offset" (this
3793 region must be within the file or device).
3794 Note that there is no limit on the amount of data that can be
3796 downloaded with this call, unlike with "guestfs_pread", and this call
3797 always reads the full amount unless an error occurs.
3798 See also "guestfs_download", "guestfs_pread".
3800 This function returns 0 on success or -1 on error.
3802 This long-running command can generate progress notification messages
3804 so that the caller can display a progress bar or indicator. To receive
3805 these messages, the caller must register a progress event callback.
3806 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
3807 (Added in 1.5.17)
3809 guestfs_drop_caches
3811 int
3812 guestfs_drop_caches (guestfs_h *g,
3813 int whattodrop);
3814 This instructs the guest kernel to drop its page cache, and/or dentries
3816 and inode caches. The parameter "whattodrop" tells the kernel what
3817 precisely to drop, see http://linux-mm.org/Drop_Caches
3818 Setting "whattodrop" to 3 should drop everything.
3820 This automatically calls sync(2) before the operation, so that the
3822 maximum guest memory is freed.
3823 This function returns 0 on success or -1 on error.
3825 (Added in 1.0.18)
3827 guestfs_du
3829 int64_t
3830 guestfs_du (guestfs_h *g,
3831 const char *path);
3832 This command runs the "du -s" command to estimate file space usage for
3834 "path".
3835 "path" can be a file or a directory. If "path" is a directory then the
3837 estimate includes the contents of the directory and all subdirectories
3838 (recursively).
3839 The result is the estimated size in kilobytes (ie. units of 1024
3841 bytes).
3842 On error this function returns -1.
3844 This long-running command can generate progress notification messages
3846 so that the caller can display a progress bar or indicator. To receive
3847 these messages, the caller must register a progress event callback.
3848 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
3849 (Added in 1.0.54)
3851 guestfs_e2fsck
3853 int
3854 guestfs_e2fsck (guestfs_h *g,
3855 const char *device,
3856 ...);
3857 You may supply a list of optional arguments to this call. Use zero or
3859 more of the following pairs of parameters, and terminate the list with
3860 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3861 GUESTFS_E2FSCK_CORRECT, int correct,
3863 GUESTFS_E2FSCK_FORCEALL, int forceall,
3864 This runs the ext2/ext3 filesystem checker on "device". It can take
3866 the following optional arguments:
3867 "correct"
3869 Automatically repair the file system. This option will cause e2fsck
3870 to automatically fix any filesystem problems that can be safely
3871 fixed without human intervention.
3872 This option may not be specified at the same time as the "forceall"
3874 option.
3875 "forceall"
3877 Assume an answer of 'yes' to all questions; allows e2fsck to be
3878 used non-interactively.
3879 This option may not be specified at the same time as the "correct"
3881 option.
3882 This function returns 0 on success or -1 on error.
3884 (Added in 1.15.17)
3886 guestfs_e2fsck_va
3888 int
3889 guestfs_e2fsck_va (guestfs_h *g,
3890 const char *device,
3891 va_list args);
3892 This is the "va_list variant" of "guestfs_e2fsck".
3894 See "CALLS WITH OPTIONAL ARGUMENTS".
3896 guestfs_e2fsck_argv
3898 int
3899 guestfs_e2fsck_argv (guestfs_h *g,
3900 const char *device,
3901 const struct guestfs_e2fsck_argv *optargs);
3902 This is the "argv variant" of "guestfs_e2fsck".
3904 See "CALLS WITH OPTIONAL ARGUMENTS".
3906 guestfs_e2fsck_f
3908 int
3909 guestfs_e2fsck_f (guestfs_h *g,
3910 const char *device);
3911 This function is deprecated. In new code, use the "guestfs_e2fsck"
3913 call instead.
3914 Deprecated functions will not be removed from the API, but the fact
3916 that they are deprecated indicates that there are problems with correct
3917 use of these functions.
3918 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
3920 checker on "device", noninteractively (-p), even if the filesystem
3921 appears to be clean (-f).
3922 This function returns 0 on success or -1 on error.
3924 (Added in 1.0.29)
3926 guestfs_echo_daemon
3928 char *
3929 guestfs_echo_daemon (guestfs_h *g,
3930 char *const *words);
3931 This command concatenates the list of "words" passed with single spaces
3933 between them and returns the resulting string.
3934 You can use this command to test the connection through to the daemon.
3936 See also "guestfs_ping_daemon".
3938 This function returns a string, or NULL on error. The caller must free
3940 the returned string after use.
3941 (Added in 1.0.69)
3943 guestfs_egrep
3945 char **
3946 guestfs_egrep (guestfs_h *g,
3947 const char *regex,
3948 const char *path);
3949 This function is deprecated. In new code, use the "guestfs_grep" call
3951 instead.
3952 Deprecated functions will not be removed from the API, but the fact
3954 that they are deprecated indicates that there are problems with correct
3955 use of these functions.
3956 This calls the external "egrep" program and returns the matching lines.
3958 This function returns a NULL-terminated array of strings (like
3960 environ(3)), or NULL if there was an error. The caller must free the
3961 strings and the array after use.
3962 Because of the message protocol, there is a transfer limit of somewhere
3964 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3965 (Added in 1.0.66)
3967 guestfs_egrepi
3969 char **
3970 guestfs_egrepi (guestfs_h *g,
3971 const char *regex,
3972 const char *path);
3973 This function is deprecated. In new code, use the "guestfs_grep" call
3975 instead.
3976 Deprecated functions will not be removed from the API, but the fact
3978 that they are deprecated indicates that there are problems with correct
3979 use of these functions.
3980 This calls the external "egrep -i" program and returns the matching
3982 lines.
3983 This function returns a NULL-terminated array of strings (like
3985 environ(3)), or NULL if there was an error. The caller must free the
3986 strings and the array after use.
3987 Because of the message protocol, there is a transfer limit of somewhere
3989 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3990 (Added in 1.0.66)
3992 guestfs_equal
3994 int
3995 guestfs_equal (guestfs_h *g,
3996 const char *file1,
3997 const char *file2);
3998 This compares the two files "file1" and "file2" and returns true if
4000 their content is exactly equal, or false otherwise.
4001 The external cmp(1) program is used for the comparison.
4003 This function returns a C truth value on success or -1 on error.
4005 (Added in 1.0.18)
4007 guestfs_exists
4009 int
4010 guestfs_exists (guestfs_h *g,
4011 const char *path);
4012 This returns "true" if and only if there is a file, directory (or
4014 anything) with the given "path" name.
4015 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
4017 This function returns a C truth value on success or -1 on error.
4019 (Added in 0.8)
4021 guestfs_fallocate
4023 int
4024 guestfs_fallocate (guestfs_h *g,
4025 const char *path,
4026 int len);
4027 This function is deprecated. In new code, use the
4029 "guestfs_fallocate64" call instead.
4030 Deprecated functions will not be removed from the API, but the fact
4032 that they are deprecated indicates that there are problems with correct
4033 use of these functions.
4034 This command preallocates a file (containing zero bytes) named "path"
4036 of size "len" bytes. If the file exists already, it is overwritten.
4037 Do not confuse this with the guestfish-specific "alloc" command which
4039 allocates a file in the host and attaches it as a device.
4040 This function returns 0 on success or -1 on error.
4042 (Added in 1.0.66)
4044 guestfs_fallocate64
4046 int
4047 guestfs_fallocate64 (guestfs_h *g,
4048 const char *path,
4049 int64_t len);
4050 This command preallocates a file (containing zero bytes) named "path"
4052 of size "len" bytes. If the file exists already, it is overwritten.
4053 Note that this call allocates disk blocks for the file. To create a
4055 sparse file use "guestfs_truncate_size" instead.
4056 The deprecated call "guestfs_fallocate" does the same, but owing to an
4058 oversight it only allowed 30 bit lengths to be specified, effectively
4059 limiting the maximum size of files created through that call to 1GB.
4060 Do not confuse this with the guestfish-specific "alloc" and "sparse"
4062 commands which create a file in the host and attach it as a device.
4063 This function returns 0 on success or -1 on error.
4065 (Added in 1.3.17)
4067 guestfs_fgrep
4069 char **
4070 guestfs_fgrep (guestfs_h *g,
4071 const char *pattern,
4072 const char *path);
4073 This function is deprecated. In new code, use the "guestfs_grep" call
4075 instead.
4076 Deprecated functions will not be removed from the API, but the fact
4078 that they are deprecated indicates that there are problems with correct
4079 use of these functions.
4080 This calls the external "fgrep" program and returns the matching lines.
4082 This function returns a NULL-terminated array of strings (like
4084 environ(3)), or NULL if there was an error. The caller must free the
4085 strings and the array after use.
4086 Because of the message protocol, there is a transfer limit of somewhere
4088 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4089 (Added in 1.0.66)
4091 guestfs_fgrepi
4093 char **
4094 guestfs_fgrepi (guestfs_h *g,
4095 const char *pattern,
4096 const char *path);
4097 This function is deprecated. In new code, use the "guestfs_grep" call
4099 instead.
4100 Deprecated functions will not be removed from the API, but the fact
4102 that they are deprecated indicates that there are problems with correct
4103 use of these functions.
4104 This calls the external "fgrep -i" program and returns the matching
4106 lines.
4107 This function returns a NULL-terminated array of strings (like
4109 environ(3)), or NULL if there was an error. The caller must free the
4110 strings and the array after use.
4111 Because of the message protocol, there is a transfer limit of somewhere
4113 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4114 (Added in 1.0.66)
4116 guestfs_file
4118 char *
4119 guestfs_file (guestfs_h *g,
4120 const char *path);
4121 This call uses the standard file(1) command to determine the type or
4123 contents of the file.
4124 This call will also transparently look inside various types of
4126 compressed file.
4127 The exact command which runs is "file -zb path". Note in particular
4129 that the filename is not prepended to the output (the -b option).
4130 The output depends on the output of the underlying file(1) command and
4132 it can change in future in ways beyond our control. In other words,
4133 the output is not guaranteed by the ABI.
4134 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
4136 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
4137 This function returns a string, or NULL on error. The caller must free
4139 the returned string after use.
4140 (Added in 0.9.1)
4142 guestfs_file_architecture
4144 char *
4145 guestfs_file_architecture (guestfs_h *g,
4146 const char *filename);
4147 This detects the architecture of the binary "filename", and returns it
4149 if known.
4150 Currently defined architectures are:
4152 "i386"
4154 This string is returned for all 32 bit i386, i486, i586, i686
4155 binaries irrespective of the precise processor requirements of the
4156 binary.
4157 "x86_64"
4159 64 bit x86-64.
4160 "sparc"
4162 32 bit SPARC.
4163 "sparc64"
4165 64 bit SPARC V9 and above.
4166 "ia64"
4168 Intel Itanium.
4169 "ppc"
4171 32 bit Power PC.
4172 "ppc64"
4174 64 bit Power PC.
4175 Libguestfs may return other architecture strings in future.
4177 The function works on at least the following types of files:
4179 · many types of Un*x and Linux binary
4181 · many types of Un*x and Linux shared library
4183 · Windows Win32 and Win64 binaries
4185 · Windows Win32 and Win64 DLLs
4187 Win32 binaries and DLLs return "i386".
4189 Win64 binaries and DLLs return "x86_64".
4191 · Linux kernel modules
4193 · Linux new-style initrd images
4195 · some non-x86 Linux vmlinuz kernels
4197 What it can't do currently:
4199 · static libraries (libfoo.a)
4201 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
4203 · x86 Linux vmlinuz kernels
4205 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
4207 and compressed code, and are horribly hard to unpack. If you want
4208 to find the architecture of a kernel, use the architecture of the
4209 associated initrd or kernel module(s) instead.
4210 This function returns a string, or NULL on error. The caller must free
4212 the returned string after use.
4213 (Added in 1.5.3)
4215 guestfs_filesize
4217 int64_t
4218 guestfs_filesize (guestfs_h *g,
4219 const char *file);
4220 This command returns the size of "file" in bytes.
4222 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
4224 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
4225 devices, use "guestfs_blockdev_getsize64".
4226 On error this function returns -1.
4228 (Added in 1.0.82)
4230 guestfs_filesystem_available
4232 int
4233 guestfs_filesystem_available (guestfs_h *g,
4234 const char *filesystem);
4235 Check whether libguestfs supports the named filesystem. The argument
4237 "filesystem" is a filesystem name, such as "ext3".
4238 You must call "guestfs_launch" before using this command.
4240 This is mainly useful as a negative test. If this returns true, it
4242 doesn't mean that a particular filesystem can be created or mounted,
4243 since filesystems can fail for other reasons such as it being a later
4244 version of the filesystem, or having incompatible features, or lacking
4245 the right mkfs.<fs> tool.
4246 See also "guestfs_available", "AVAILABILITY" in guestfs(3).
4248 This function returns a C truth value on success or -1 on error.
4250 (Added in 1.19.5)
4252 guestfs_fill
4254 int
4255 guestfs_fill (guestfs_h *g,
4256 int c,
4257 int len,
4258 const char *path);
4259 This command creates a new file called "path". The initial content of
4261 the file is "len" octets of "c", where "c" must be a number in the
4262 range "[0..255]".
4263 To fill a file with zero bytes (sparsely), it is much more efficient to
4265 use "guestfs_truncate_size". To create a file with a pattern of
4266 repeating bytes use "guestfs_fill_pattern".
4267 This function returns 0 on success or -1 on error.
4269 This long-running command can generate progress notification messages
4271 so that the caller can display a progress bar or indicator. To receive
4272 these messages, the caller must register a progress event callback.
4273 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
4274 (Added in 1.0.79)
4276 guestfs_fill_dir
4278 int
4279 guestfs_fill_dir (guestfs_h *g,
4280 const char *dir,
4281 int nr);
4282 This function, useful for testing filesystems, creates "nr" empty files
4284 in the directory "dir" with names 00000000 through "nr-1" (ie. each
4285 file name is 8 digits long padded with zeroes).
4286 This function returns 0 on success or -1 on error.
4288 (Added in 1.19.32)
4290 guestfs_fill_pattern
4292 int
4293 guestfs_fill_pattern (guestfs_h *g,
4294 const char *pattern,
4295 int len,
4296 const char *path);
4297 This function is like "guestfs_fill" except that it creates a new file
4299 of length "len" containing the repeating pattern of bytes in "pattern".
4300 The pattern is truncated if necessary to ensure the length of the file
4301 is exactly "len" bytes.
4302 This function returns 0 on success or -1 on error.
4304 This long-running command can generate progress notification messages
4306 so that the caller can display a progress bar or indicator. To receive
4307 these messages, the caller must register a progress event callback.
4308 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
4309 (Added in 1.3.12)
4311 guestfs_find
4313 char **
4314 guestfs_find (guestfs_h *g,
4315 const char *directory);
4316 This command lists out all files and directories, recursively, starting
4318 at "directory". It is essentially equivalent to running the shell
4319 command "find directory -print" but some post-processing happens on the
4320 output, described below.
4321 This returns a list of strings without any prefix. Thus if the
4323 directory structure was:
4324 /tmp/a
4326 /tmp/b
4327 /tmp/c/d
4328 then the returned list from "guestfs_find" "/tmp" would be 4 elements:
4330 a
4332 b
4333 c
4334 c/d
4335 If "directory" is not a directory, then this command returns an error.
4337 The returned list is sorted.
4339 This function returns a NULL-terminated array of strings (like
4341 environ(3)), or NULL if there was an error. The caller must free the
4342 strings and the array after use.
4343 (Added in 1.0.27)
4345 guestfs_find0
4347 int
4348 guestfs_find0 (guestfs_h *g,
4349 const char *directory,
4350 const char *files);
4351 This command lists out all files and directories, recursively, starting
4353 at "directory", placing the resulting list in the external file called
4354 "files".
4355 This command works the same way as "guestfs_find" with the following
4357 exceptions:
4358 · The resulting list is written to an external file.
4360 · Items (filenames) in the result are separated by "\0" characters.
4362 See find(1) option -print0.
4363 · The result list is not sorted.
4365 This function returns 0 on success or -1 on error.
4367 (Added in 1.0.74)
4369 guestfs_findfs_label
4371 char *
4372 guestfs_findfs_label (guestfs_h *g,
4373 const char *label);
4374 This command searches the filesystems and returns the one which has the
4376 given label. An error is returned if no such filesystem can be found.
4377 To find the label of a filesystem, use "guestfs_vfs_label".
4379 This function returns a string, or NULL on error. The caller must free
4381 the returned string after use.
4382 (Added in 1.5.3)
4384 guestfs_findfs_uuid
4386 char *
4387 guestfs_findfs_uuid (guestfs_h *g,
4388 const char *uuid);
4389 This command searches the filesystems and returns the one which has the
4391 given UUID. An error is returned if no such filesystem can be found.
4392 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
4394 This function returns a string, or NULL on error. The caller must free
4396 the returned string after use.
4397 (Added in 1.5.3)
4399 guestfs_fsck
4401 int
4402 guestfs_fsck (guestfs_h *g,
4403 const char *fstype,
4404 const char *device);
4405 This runs the filesystem checker (fsck) on "device" which should have
4407 filesystem type "fstype".
4408 The returned integer is the status. See fsck(8) for the list of status
4410 codes from "fsck".
4411 Notes:
4413 · Multiple status codes can be summed together.
4415 · A non-zero return code can mean "success", for example if errors
4417 have been corrected on the filesystem.
4418 · Checking or repairing NTFS volumes is not supported (by linux-
4420 ntfs).
4421 This command is entirely equivalent to running "fsck -a -t fstype
4423 device".
4424 On error this function returns -1.
4426 (Added in 1.0.16)
4428 guestfs_get_append
4430 const char *
4431 guestfs_get_append (guestfs_h *g);
4432 Return the additional kernel options which are added to the libguestfs
4434 appliance kernel command line.
4435 If "NULL" then no options are added.
4437 This function returns a string which may be NULL. There is no way to
4439 return an error from this function. The string is owned by the guest
4440 handle and must not be freed.
4441 (Added in 1.0.26)
4443 guestfs_get_attach_method
4445 char *
4446 guestfs_get_attach_method (guestfs_h *g);
4447 Return the current attach method.
4449 See "guestfs_set_attach_method" and "ATTACH METHOD" in guestfs(3).
4451 This function returns a string, or NULL on error. The caller must free
4453 the returned string after use.
4454 (Added in 1.9.8)
4456 guestfs_get_autosync
4458 int
4459 guestfs_get_autosync (guestfs_h *g);
4460 Get the autosync flag.
4462 This function returns a C truth value on success or -1 on error.
4464 (Added in 0.3)
4466 guestfs_get_cachedir
4468 char *
4469 guestfs_get_cachedir (guestfs_h *g);
4470 Get the directory used by the handle to store the appliance cache.
4472 This function returns a string, or NULL on error. The caller must free
4474 the returned string after use.
4475 (Added in 1.19.58)
4477 guestfs_get_direct
4479 int
4480 guestfs_get_direct (guestfs_h *g);
4481 Return the direct appliance mode flag.
4483 This function returns a C truth value on success or -1 on error.
4485 (Added in 1.0.72)
4487 guestfs_get_e2attrs
4489 char *
4490 guestfs_get_e2attrs (guestfs_h *g,
4491 const char *file);
4492 This returns the file attributes associated with "file".
4494 The attributes are a set of bits associated with each inode which
4496 affect the behaviour of the file. The attributes are returned as a
4497 string of letters (described below). The string may be empty,
4498 indicating that no file attributes are set for this file.
4499 These attributes are only present when the file is located on an
4501 ext2/3/4 filesystem. Using this call on other filesystem types will
4502 result in an error.
4503 The characters (file attributes) in the returned string are currently:
4505 'A' When the file is accessed, its atime is not modified.
4507 'a' The file is append-only.
4509 'c' The file is compressed on-disk.
4511 'D' (Directories only.) Changes to this directory are written
4513 synchronously to disk.
4514 'd' The file is not a candidate for backup (see dump(8)).
4516 'E' The file has compression errors.
4518 'e' The file is using extents.
4520 'h' The file is storing its blocks in units of the filesystem blocksize
4522 instead of sectors.
4523 'I' (Directories only.) The directory is using hashed trees.
4525 'i' The file is immutable. It cannot be modified, deleted or renamed.
4527 No link can be created to this file.
4528 'j' The file is data-journaled.
4530 's' When the file is deleted, all its blocks will be zeroed.
4532 'S' Changes to this file are written synchronously to disk.
4534 'T' (Directories only.) This is a hint to the block allocator that
4536 subdirectories contained in this directory should be spread across
4537 blocks. If not present, the block allocator will try to group
4538 subdirectories together.
4539 't' For a file, this disables tail-merging. (Not used by upstream
4541 implementations of ext2.)
4542 'u' When the file is deleted, its blocks will be saved, allowing the
4544 file to be undeleted.
4545 'X' The raw contents of the compressed file may be accessed.
4547 'Z' The compressed file is dirty.
4549 More file attributes may be added to this list later. Not all file
4551 attributes may be set for all kinds of files. For detailed
4552 information, consult the chattr(1) man page.
4553 See also "guestfs_set_e2attrs".
4555 Don't confuse these attributes with extended attributes (see
4557 "guestfs_getxattr").
4558 This function returns a string, or NULL on error. The caller must free
4560 the returned string after use.
4561 (Added in 1.17.31)
4563 guestfs_get_e2generation
4565 int64_t
4566 guestfs_get_e2generation (guestfs_h *g,
4567 const char *file);
4568 This returns the ext2 file generation of a file. The generation (which
4570 used to be called the "version") is a number associated with an inode.
4571 This is most commonly used by NFS servers.
4572 The generation is only present when the file is located on an ext2/3/4
4574 filesystem. Using this call on other filesystem types will result in
4575 an error.
4576 See "guestfs_set_e2generation".
4578 On error this function returns -1.
4580 (Added in 1.17.31)
4582 guestfs_get_e2label
4584 char *
4585 guestfs_get_e2label (guestfs_h *g,
4586 const char *device);
4587 This function is deprecated. In new code, use the "guestfs_vfs_label"
4589 call instead.
4590 Deprecated functions will not be removed from the API, but the fact
4592 that they are deprecated indicates that there are problems with correct
4593 use of these functions.
4594 This returns the ext2/3/4 filesystem label of the filesystem on
4596 "device".
4597 This function returns a string, or NULL on error. The caller must free
4599 the returned string after use.
4600 (Added in 1.0.15)
4602 guestfs_get_e2uuid
4604 char *
4605 guestfs_get_e2uuid (guestfs_h *g,
4606 const char *device);
4607 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
4609 call instead.
4610 Deprecated functions will not be removed from the API, but the fact
4612 that they are deprecated indicates that there are problems with correct
4613 use of these functions.
4614 This returns the ext2/3/4 filesystem UUID of the filesystem on
4616 "device".
4617 This function returns a string, or NULL on error. The caller must free
4619 the returned string after use.
4620 (Added in 1.0.15)
4622 guestfs_get_libvirt_requested_credential_challenge
4624 char *
4625 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
4626 int index);
4627 Get the challenge (provided by libvirt) for the "index"'th requested
4629 credential. If libvirt did not provide a challenge, this returns the
4630 empty string "".
4631 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4633 example code.
4634 This function returns a string, or NULL on error. The caller must free
4636 the returned string after use.
4637 (Added in 1.19.52)
4639 guestfs_get_libvirt_requested_credential_defresult
4641 char *
4642 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
4643 int index);
4644 Get the default result (provided by libvirt) for the "index"'th
4646 requested credential. If libvirt did not provide a default result,
4647 this returns the empty string "".
4648 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4650 example code.
4651 This function returns a string, or NULL on error. The caller must free
4653 the returned string after use.
4654 (Added in 1.19.52)
4656 guestfs_get_libvirt_requested_credential_prompt
4658 char *
4659 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
4660 int index);
4661 Get the prompt (provided by libvirt) for the "index"'th requested
4663 credential. If libvirt did not provide a prompt, this returns the
4664 empty string "".
4665 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4667 example code.
4668 This function returns a string, or NULL on error. The caller must free
4670 the returned string after use.
4671 (Added in 1.19.52)
4673 guestfs_get_libvirt_requested_credentials
4675 char **
4676 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
4677 This should only be called during the event callback for events of type
4679 "GUESTFS_EVENT_LIBVIRT_AUTH".
4680 Return the list of credentials requested by libvirt. Possible values
4682 are a subset of the strings provided when you called
4683 "guestfs_set_libvirt_supported_credentials".
4684 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4686 example code.
4687 This function returns a NULL-terminated array of strings (like
4689 environ(3)), or NULL if there was an error. The caller must free the
4690 strings and the array after use.
4691 (Added in 1.19.52)
4693 guestfs_get_memsize
4695 int
4696 guestfs_get_memsize (guestfs_h *g);
4697 This gets the memory size in megabytes allocated to the qemu
4699 subprocess.
4700 If "guestfs_set_memsize" was not called on this handle, and if
4702 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
4703 default value for memsize.
4704 For more information on the architecture of libguestfs, see guestfs(3).
4706 On error this function returns -1.
4708 (Added in 1.0.55)
4710 guestfs_get_network
4712 int
4713 guestfs_get_network (guestfs_h *g);
4714 This returns the enable network flag.
4716 This function returns a C truth value on success or -1 on error.
4718 (Added in 1.5.4)
4720 guestfs_get_path
4722 const char *
4723 guestfs_get_path (guestfs_h *g);
4724 Return the current search path.
4726 This is always non-NULL. If it wasn't set already, then this will
4728 return the default path.
4729 This function returns a string, or NULL on error. The string is owned
4731 by the guest handle and must not be freed.
4732 (Added in 0.3)
4734 guestfs_get_pgroup
4736 int
4737 guestfs_get_pgroup (guestfs_h *g);
4738 This returns the process group flag.
4740 This function returns a C truth value on success or -1 on error.
4742 (Added in 1.11.18)
4744 guestfs_get_pid
4746 int
4747 guestfs_get_pid (guestfs_h *g);
4748 Return the process ID of the qemu subprocess. If there is no qemu
4750 subprocess, then this will return an error.
4751 This is an internal call used for debugging and testing.
4753 On error this function returns -1.
4755 (Added in 1.0.56)
4757 guestfs_get_qemu
4759 const char *
4760 guestfs_get_qemu (guestfs_h *g);
4761 Return the current qemu binary.
4763 This is always non-NULL. If it wasn't set already, then this will
4765 return the default qemu binary name.
4766 This function returns a string, or NULL on error. The string is owned
4768 by the guest handle and must not be freed.
4769 (Added in 1.0.6)
4771 guestfs_get_recovery_proc
4773 int
4774 guestfs_get_recovery_proc (guestfs_h *g);
4775 Return the recovery process enabled flag.
4777 This function returns a C truth value on success or -1 on error.
4779 (Added in 1.0.77)
4781 guestfs_get_selinux
4783 int
4784 guestfs_get_selinux (guestfs_h *g);
4785 This returns the current setting of the selinux flag which is passed to
4787 the appliance at boot time. See "guestfs_set_selinux".
4788 For more information on the architecture of libguestfs, see guestfs(3).
4790 This function returns a C truth value on success or -1 on error.
4792 (Added in 1.0.67)
4794 guestfs_get_smp
4796 int
4797 guestfs_get_smp (guestfs_h *g);
4798 This returns the number of virtual CPUs assigned to the appliance.
4800 On error this function returns -1.
4802 (Added in 1.13.15)
4804 guestfs_get_state
4806 int
4807 guestfs_get_state (guestfs_h *g);
4808 This returns the current state as an opaque integer. This is only
4810 useful for printing debug and internal error messages.
4811 For more information on states, see guestfs(3).
4813 On error this function returns -1.
4815 (Added in 1.0.2)
4817 guestfs_get_tmpdir
4819 char *
4820 guestfs_get_tmpdir (guestfs_h *g);
4821 Get the directory used by the handle to store temporary files.
4823 This function returns a string, or NULL on error. The caller must free
4825 the returned string after use.
4826 (Added in 1.19.58)
4828 guestfs_get_trace
4830 int
4831 guestfs_get_trace (guestfs_h *g);
4832 Return the command trace flag.
4834 This function returns a C truth value on success or -1 on error.
4836 (Added in 1.0.69)
4838 guestfs_get_umask
4840 int
4841 guestfs_get_umask (guestfs_h *g);
4842 Return the current umask. By default the umask is 022 unless it has
4844 been set by calling "guestfs_umask".
4845 On error this function returns -1.
4847 (Added in 1.3.4)
4849 guestfs_get_verbose
4851 int
4852 guestfs_get_verbose (guestfs_h *g);
4853 This returns the verbose messages flag.
4855 This function returns a C truth value on success or -1 on error.
4857 (Added in 0.3)
4859 guestfs_getcon
4861 char *
4862 guestfs_getcon (guestfs_h *g);
4863 This gets the SELinux security context of the daemon.
4865 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
4867 This function returns a string, or NULL on error. The caller must free
4869 the returned string after use.
4870 (Added in 1.0.67)
4872 guestfs_getxattr
4874 char *
4875 guestfs_getxattr (guestfs_h *g,
4876 const char *path,
4877 const char *name,
4878 size_t *size_r);
4879 Get a single extended attribute from file "path" named "name". This
4881 call follows symlinks. If you want to lookup an extended attribute for
4882 the symlink itself, use "guestfs_lgetxattr".
4883 Normally it is better to get all extended attributes from a file in one
4885 go by calling "guestfs_getxattrs". However some Linux filesystem
4886 implementations are buggy and do not provide a way to list out
4887 attributes. For these filesystems (notably ntfs-3g) you have to know
4888 the names of the extended attributes you want in advance and call this
4889 function.
4890 Extended attribute values are blobs of binary data. If there is no
4892 extended attribute named "name", this returns an error.
4893 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
4895 This function returns a buffer, or NULL on error. The size of the
4897 returned buffer is written to *size_r. The caller must free the
4898 returned buffer after use.
4899 (Added in 1.7.24)
4901 guestfs_getxattrs
4903 struct guestfs_xattr_list *
4904 guestfs_getxattrs (guestfs_h *g,
4905 const char *path);
4906 This call lists the extended attributes of the file or directory
4908 "path".
4909 At the system call level, this is a combination of the listxattr(2) and
4911 getxattr(2) calls.
4912 See also: "guestfs_lgetxattrs", attr(5).
4914 This function returns a "struct guestfs_xattr_list *", or NULL if there
4916 was an error. The caller must call "guestfs_free_xattr_list" after
4917 use.
4918 (Added in 1.0.59)
4920 guestfs_glob_expand
4922 char **
4923 guestfs_glob_expand (guestfs_h *g,
4924 const char *pattern);
4925 This command searches for all the pathnames matching "pattern"
4927 according to the wildcard expansion rules used by the shell.
4928 If no paths match, then this returns an empty list (note: not an
4930 error).
4931 It is just a wrapper around the C glob(3) function with flags
4933 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
4934 Notice that there is no equivalent command for expanding a device name
4936 (eg. "/dev/sd*"). Use "guestfs_list_devices",
4937 "guestfs_list_partitions" etc functions instead.
4938 This function returns a NULL-terminated array of strings (like
4940 environ(3)), or NULL if there was an error. The caller must free the
4941 strings and the array after use.
4942 (Added in 1.0.50)
4944 guestfs_grep
4946 char **
4947 guestfs_grep (guestfs_h *g,
4948 const char *regex,
4949 const char *path);
4950 This function is provided for backwards compatibility with earlier
4952 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
4953 optional arguments.
4954 (Added in 1.0.66)
4956 guestfs_grep_opts
4958 char **
4959 guestfs_grep_opts (guestfs_h *g,
4960 const char *regex,
4961 const char *path,
4962 ...);
4963 You may supply a list of optional arguments to this call. Use zero or
4965 more of the following pairs of parameters, and terminate the list with
4966 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4967 GUESTFS_GREP_OPTS_EXTENDED, int extended,
4969 GUESTFS_GREP_OPTS_FIXED, int fixed,
4970 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
4971 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
4972 This calls the external "grep" program and returns the matching lines.
4974 The optional flags are:
4976 "extended"
4978 Use extended regular expressions. This is the same as using the -E
4979 flag.
4980 "fixed"
4982 Match fixed (don't use regular expressions). This is the same as
4983 using the -F flag.
4984 "insensitive"
4986 Match case-insensitive. This is the same as using the -i flag.
4987 "compressed"
4989 Use "zgrep" instead of "grep". This allows the input to be
4990 compress- or gzip-compressed.
4991 This function returns a NULL-terminated array of strings (like
4993 environ(3)), or NULL if there was an error. The caller must free the
4994 strings and the array after use.
4995 Because of the message protocol, there is a transfer limit of somewhere
4997 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4998 (Added in 1.19.28)
5000 guestfs_grep_opts_va
5002 char **
5003 guestfs_grep_opts_va (guestfs_h *g,
5004 const char *regex,
5005 const char *path,
5006 va_list args);
5007 This is the "va_list variant" of "guestfs_grep_opts".
5009 See "CALLS WITH OPTIONAL ARGUMENTS".
5011 guestfs_grep_opts_argv
5013 char **
5014 guestfs_grep_opts_argv (guestfs_h *g,
5015 const char *regex,
5016 const char *path,
5017 const struct guestfs_grep_opts_argv *optargs);
5018 This is the "argv variant" of "guestfs_grep_opts".
5020 See "CALLS WITH OPTIONAL ARGUMENTS".
5022 guestfs_grepi
5024 char **
5025 guestfs_grepi (guestfs_h *g,
5026 const char *regex,
5027 const char *path);
5028 This function is deprecated. In new code, use the "guestfs_grep" call
5030 instead.
5031 Deprecated functions will not be removed from the API, but the fact
5033 that they are deprecated indicates that there are problems with correct
5034 use of these functions.
5035 This calls the external "grep -i" program and returns the matching
5037 lines.
5038 This function returns a NULL-terminated array of strings (like
5040 environ(3)), or NULL if there was an error. The caller must free the
5041 strings and the array after use.
5042 Because of the message protocol, there is a transfer limit of somewhere
5044 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5045 (Added in 1.0.66)
5047 guestfs_grub_install
5049 int
5050 guestfs_grub_install (guestfs_h *g,
5051 const char *root,
5052 const char *device);
5053 This command installs GRUB 1 (the Grand Unified Bootloader) on
5055 "device", with the root directory being "root".
5056 Notes:
5058 · There is currently no way in the API to install grub2, which is
5060 used by most modern Linux guests. It is possible to run the grub2
5061 command from the guest, although see the caveats in "RUNNING
5062 COMMANDS" in guestfs(3).
5063 · This uses "grub-install" from the host. Unfortunately grub is not
5065 always compatible with itself, so this only works in rather narrow
5066 circumstances. Careful testing with each guest version is
5067 advisable.
5068 · If grub-install reports the error "No suitable drive was found in
5070 the generated device map." it may be that you need to create a
5071 "/boot/grub/device.map" file first that contains the mapping
5072 between grub device names and Linux device names. It is usually
5073 sufficient to create a file containing:
5074 (hd0) /dev/vda
5076 replacing "/dev/vda" with the name of the installation device.
5078 This function returns 0 on success or -1 on error.
5080 (Added in 1.0.17)
5082 guestfs_head
5084 char **
5085 guestfs_head (guestfs_h *g,
5086 const char *path);
5087 This command returns up to the first 10 lines of a file as a list of
5089 strings.
5090 This function returns a NULL-terminated array of strings (like
5092 environ(3)), or NULL if there was an error. The caller must free the
5093 strings and the array after use.
5094 Because of the message protocol, there is a transfer limit of somewhere
5096 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5097 (Added in 1.0.54)
5099 guestfs_head_n
5101 char **
5102 guestfs_head_n (guestfs_h *g,
5103 int nrlines,
5104 const char *path);
5105 If the parameter "nrlines" is a positive number, this returns the first
5107 "nrlines" lines of the file "path".
5108 If the parameter "nrlines" is a negative number, this returns lines
5110 from the file "path", excluding the last "nrlines" lines.
5111 If the parameter "nrlines" is zero, this returns an empty list.
5113 This function returns a NULL-terminated array of strings (like
5115 environ(3)), or NULL if there was an error. The caller must free the
5116 strings and the array after use.
5117 Because of the message protocol, there is a transfer limit of somewhere
5119 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5120 (Added in 1.0.54)
5122 guestfs_hexdump
5124 char *
5125 guestfs_hexdump (guestfs_h *g,
5126 const char *path);
5127 This runs "hexdump -C" on the given "path". The result is the human-
5129 readable, canonical hex dump of the file.
5130 This function returns a string, or NULL on error. The caller must free
5132 the returned string after use.
5133 Because of the message protocol, there is a transfer limit of somewhere
5135 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5136 (Added in 1.0.22)
5138 guestfs_hivex_close
5140 int
5141 guestfs_hivex_close (guestfs_h *g);
5142 Close the current hivex handle.
5144 This is a wrapper around the hivex(3) call of the same name.
5146 This function returns 0 on success or -1 on error.
5148 (Added in 1.19.35)
5150 guestfs_hivex_commit
5152 int
5153 guestfs_hivex_commit (guestfs_h *g,
5154 const char *filename);
5155 Commit (write) changes to the hive.
5157 If the optional "filename" parameter is null, then the changes are
5159 written back to the same hive that was opened. If this is not null
5160 then they are written to the alternate filename given and the original
5161 hive is left untouched.
5162 This is a wrapper around the hivex(3) call of the same name.
5164 This function returns 0 on success or -1 on error.
5166 (Added in 1.19.35)
5168 guestfs_hivex_node_add_child
5170 int64_t
5171 guestfs_hivex_node_add_child (guestfs_h *g,
5172 int64_t parent,
5173 const char *name);
5174 Add a child node to "parent" named "name".
5176 This is a wrapper around the hivex(3) call of the same name.
5178 On error this function returns -1.
5180 (Added in 1.19.35)
5182 guestfs_hivex_node_children
5184 struct guestfs_hivex_node_list *
5185 guestfs_hivex_node_children (guestfs_h *g,
5186 int64_t nodeh);
5187 Return the list of nodes which are subkeys of "nodeh".
5189 This is a wrapper around the hivex(3) call of the same name.
5191 This function returns a "struct guestfs_hivex_node_list *", or NULL if
5193 there was an error. The caller must call
5194 "guestfs_free_hivex_node_list" after use.
5195 (Added in 1.19.35)
5197 guestfs_hivex_node_delete_child
5199 int
5200 guestfs_hivex_node_delete_child (guestfs_h *g,
5201 int64_t nodeh);
5202 Delete "nodeh", recursively if necessary.
5204 This is a wrapper around the hivex(3) call of the same name.
5206 This function returns 0 on success or -1 on error.
5208 (Added in 1.19.35)
5210 guestfs_hivex_node_get_child
5212 int64_t
5213 guestfs_hivex_node_get_child (guestfs_h *g,
5214 int64_t nodeh,
5215 const char *name);
5216 Return the child of "nodeh" with the name "name", if it exists. This
5218 can return 0 meaning the name was not found.
5219 This is a wrapper around the hivex(3) call of the same name.
5221 On error this function returns -1.
5223 (Added in 1.19.35)
5225 guestfs_hivex_node_get_value
5227 int64_t
5228 guestfs_hivex_node_get_value (guestfs_h *g,
5229 int64_t nodeh,
5230 const char *key);
5231 Return the value attached to "nodeh" which has the name "key", if it
5233 exists. This can return 0 meaning the key was not found.
5234 This is a wrapper around the hivex(3) call of the same name.
5236 On error this function returns -1.
5238 (Added in 1.19.35)
5240 guestfs_hivex_node_name
5242 char *
5243 guestfs_hivex_node_name (guestfs_h *g,
5244 int64_t nodeh);
5245 Return the name of "nodeh".
5247 This is a wrapper around the hivex(3) call of the same name.
5249 This function returns a string, or NULL on error. The caller must free
5251 the returned string after use.
5252 (Added in 1.19.35)
5254 guestfs_hivex_node_parent
5256 int64_t
5257 guestfs_hivex_node_parent (guestfs_h *g,
5258 int64_t nodeh);
5259 Return the parent node of "nodeh".
5261 This is a wrapper around the hivex(3) call of the same name.
5263 On error this function returns -1.
5265 (Added in 1.19.35)
5267 guestfs_hivex_node_set_value
5269 int
5270 guestfs_hivex_node_set_value (guestfs_h *g,
5271 int64_t nodeh,
5272 const char *key,
5273 int64_t t,
5274 const char *val,
5275 size_t val_size);
5276 Set or replace a single value under the node "nodeh". The "key" is the
5278 name, "t" is the type, and "val" is the data.
5279 This is a wrapper around the hivex(3) call of the same name.
5281 This function returns 0 on success or -1 on error.
5283 (Added in 1.19.35)
5285 guestfs_hivex_node_values
5287 struct guestfs_hivex_value_list *
5288 guestfs_hivex_node_values (guestfs_h *g,
5289 int64_t nodeh);
5290 Return the array of (key, datatype, data) tuples attached to "nodeh".
5292 This is a wrapper around the hivex(3) call of the same name.
5294 This function returns a "struct guestfs_hivex_value_list *", or NULL if
5296 there was an error. The caller must call
5297 "guestfs_free_hivex_value_list" after use.
5298 (Added in 1.19.35)
5300 guestfs_hivex_open
5302 int
5303 guestfs_hivex_open (guestfs_h *g,
5304 const char *filename,
5305 ...);
5306 You may supply a list of optional arguments to this call. Use zero or
5308 more of the following pairs of parameters, and terminate the list with
5309 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5310 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
5312 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
5313 GUESTFS_HIVEX_OPEN_WRITE, int write,
5314 Open the Windows Registry hive file named "filename". If there was any
5316 previous hivex handle associated with this guestfs session, then it is
5317 closed.
5318 This is a wrapper around the hivex(3) call of the same name.
5320 This function returns 0 on success or -1 on error.
5322 (Added in 1.19.35)
5324 guestfs_hivex_open_va
5326 int
5327 guestfs_hivex_open_va (guestfs_h *g,
5328 const char *filename,
5329 va_list args);
5330 This is the "va_list variant" of "guestfs_hivex_open".
5332 See "CALLS WITH OPTIONAL ARGUMENTS".
5334 guestfs_hivex_open_argv
5336 int
5337 guestfs_hivex_open_argv (guestfs_h *g,
5338 const char *filename,
5339 const struct guestfs_hivex_open_argv *optargs);
5340 This is the "argv variant" of "guestfs_hivex_open".
5342 See "CALLS WITH OPTIONAL ARGUMENTS".
5344 guestfs_hivex_root
5346 int64_t
5347 guestfs_hivex_root (guestfs_h *g);
5348 Return the root node of the hive.
5350 This is a wrapper around the hivex(3) call of the same name.
5352 On error this function returns -1.
5354 (Added in 1.19.35)
5356 guestfs_hivex_value_key
5358 char *
5359 guestfs_hivex_value_key (guestfs_h *g,
5360 int64_t valueh);
5361 Return the key (name) field of a (key, datatype, data) tuple.
5363 This is a wrapper around the hivex(3) call of the same name.
5365 This function returns a string, or NULL on error. The caller must free
5367 the returned string after use.
5368 (Added in 1.19.35)
5370 guestfs_hivex_value_type
5372 int64_t
5373 guestfs_hivex_value_type (guestfs_h *g,
5374 int64_t valueh);
5375 Return the data type field from a (key, datatype, data) tuple.
5377 This is a wrapper around the hivex(3) call of the same name.
5379 On error this function returns -1.
5381 (Added in 1.19.35)
5383 guestfs_hivex_value_utf8
5385 char *
5386 guestfs_hivex_value_utf8 (guestfs_h *g,
5387 int64_t valueh);
5388 This calls "guestfs_hivex_value_value" (which returns the data field
5390 from a hivex value tuple). It then assumes that the field is a
5391 UTF-16LE string and converts the result to UTF-8 (or if this is not
5392 possible, it returns an error).
5393 This is useful for reading strings out of the Windows registry.
5395 However it is not foolproof because the registry is not strongly-typed
5396 and fields can contain arbitrary or unexpected data.
5397 This function returns a string, or NULL on error. The caller must free
5399 the returned string after use.
5400 (Added in 1.19.35)
5402 guestfs_hivex_value_value
5404 char *
5405 guestfs_hivex_value_value (guestfs_h *g,
5406 int64_t valueh,
5407 size_t *size_r);
5408 Return the data field of a (key, datatype, data) tuple.
5410 This is a wrapper around the hivex(3) call of the same name.
5412 See also: "guestfs_hivex_value_utf8".
5414 This function returns a buffer, or NULL on error. The size of the
5416 returned buffer is written to *size_r. The caller must free the
5417 returned buffer after use.
5418 (Added in 1.19.35)
5420 guestfs_initrd_cat
5422 char *
5423 guestfs_initrd_cat (guestfs_h *g,
5424 const char *initrdpath,
5425 const char *filename,
5426 size_t *size_r);
5427 This command unpacks the file "filename" from the initrd file called
5429 "initrdpath". The filename must be given without the initial "/"
5430 character.
5431 For example, in guestfish you could use the following command to
5433 examine the boot script (usually called "/init") contained in a Linux
5434 initrd or initramfs image:
5435 initrd-cat /boot/initrd-<version>.img init
5437 See also "guestfs_initrd_list".
5439 This function returns a buffer, or NULL on error. The size of the
5441 returned buffer is written to *size_r. The caller must free the
5442 returned buffer after use.
5443 Because of the message protocol, there is a transfer limit of somewhere
5445 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5446 (Added in 1.0.84)
5448 guestfs_initrd_list
5450 char **
5451 guestfs_initrd_list (guestfs_h *g,
5452 const char *path);
5453 This command lists out files contained in an initrd.
5455 The files are listed without any initial "/" character. The files are
5457 listed in the order they appear (not necessarily alphabetical).
5458 Directory names are listed as separate items.
5459 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
5461 as initrd. We only support the newer initramfs format (compressed cpio
5462 files).
5463 This function returns a NULL-terminated array of strings (like
5465 environ(3)), or NULL if there was an error. The caller must free the
5466 strings and the array after use.
5467 (Added in 1.0.54)
5469 guestfs_inotify_add_watch
5471 int64_t
5472 guestfs_inotify_add_watch (guestfs_h *g,
5473 const char *path,
5474 int mask);
5475 Watch "path" for the events listed in "mask".
5477 Note that if "path" is a directory then events within that directory
5479 are watched, but this does not happen recursively (in subdirectories).
5480 Note for non-C or non-Linux callers: the inotify events are defined by
5482 the Linux kernel ABI and are listed in "/usr/include/sys/inotify.h".
5483 On error this function returns -1.
5485 (Added in 1.0.66)
5487 guestfs_inotify_close
5489 int
5490 guestfs_inotify_close (guestfs_h *g);
5491 This closes the inotify handle which was previously opened by
5493 inotify_init. It removes all watches, throws away any pending events,
5494 and deallocates all resources.
5495 This function returns 0 on success or -1 on error.
5497 (Added in 1.0.66)
5499 guestfs_inotify_files
5501 char **
5502 guestfs_inotify_files (guestfs_h *g);
5503 This function is a helpful wrapper around "guestfs_inotify_read" which
5505 just returns a list of pathnames of objects that were touched. The
5506 returned pathnames are sorted and deduplicated.
5507 This function returns a NULL-terminated array of strings (like
5509 environ(3)), or NULL if there was an error. The caller must free the
5510 strings and the array after use.
5511 (Added in 1.0.66)
5513 guestfs_inotify_init
5515 int
5516 guestfs_inotify_init (guestfs_h *g,
5517 int maxevents);
5518 This command creates a new inotify handle. The inotify subsystem can
5520 be used to notify events which happen to objects in the guest
5521 filesystem.
5522 "maxevents" is the maximum number of events which will be queued up
5524 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
5525 this is passed as 0, then the kernel (or previously set) default is
5526 used. For Linux 2.6.29 the default was 16384 events. Beyond this
5527 limit, the kernel throws away events, but records the fact that it
5528 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
5529 structure list (see "guestfs_inotify_read").
5530 Before any events are generated, you have to add some watches to the
5532 internal watch list. See: "guestfs_inotify_add_watch" and
5533 "guestfs_inotify_rm_watch".
5534 Queued up events should be read periodically by calling
5536 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
5537 helpful wrapper around "guestfs_inotify_read"). If you don't read the
5538 events out often enough then you risk the internal queue overflowing.
5539 The handle should be closed after use by calling
5541 "guestfs_inotify_close". This also removes any watches automatically.
5542 See also inotify(7) for an overview of the inotify interface as exposed
5544 by the Linux kernel, which is roughly what we expose via libguestfs.
5545 Note that there is one global inotify handle per libguestfs instance.
5546 This function returns 0 on success or -1 on error.
5548 (Added in 1.0.66)
5550 guestfs_inotify_read
5552 struct guestfs_inotify_event_list *
5553 guestfs_inotify_read (guestfs_h *g);
5554 Return the complete queue of events that have happened since the
5556 previous read call.
5557 If no events have happened, this returns an empty list.
5559 Note: In order to make sure that all events have been read, you must
5561 call this function repeatedly until it returns an empty list. The
5562 reason is that the call will read events up to the maximum appliance-
5563 to-host message size and leave remaining events in the queue.
5564 This function returns a "struct guestfs_inotify_event_list *", or NULL
5566 if there was an error. The caller must call
5567 "guestfs_free_inotify_event_list" after use.
5568 (Added in 1.0.66)
5570 guestfs_inotify_rm_watch
5572 int
5573 guestfs_inotify_rm_watch (guestfs_h *g,
5574 int wd);
5575 Remove a previously defined inotify watch. See
5577 "guestfs_inotify_add_watch".
5578 This function returns 0 on success or -1 on error.
5580 (Added in 1.0.66)
5582 guestfs_inspect_get_arch
5584 char *
5585 guestfs_inspect_get_arch (guestfs_h *g,
5586 const char *root);
5587 This returns the architecture of the inspected operating system. The
5589 possible return values are listed under "guestfs_file_architecture".
5590 If the architecture could not be determined, then the string "unknown"
5592 is returned.
5593 Please read "INSPECTION" in guestfs(3) for more details.
5595 This function returns a string, or NULL on error. The caller must free
5597 the returned string after use.
5598 (Added in 1.5.3)
5600 guestfs_inspect_get_distro
5602 char *
5603 guestfs_inspect_get_distro (guestfs_h *g,
5604 const char *root);
5605 This returns the distro (distribution) of the inspected operating
5607 system.
5608 Currently defined distros are:
5610 "archlinux"
5612 Arch Linux.
5613 "buildroot"
5615 Buildroot-derived distro, but not one we specifically recognize.
5616 "centos"
5618 CentOS.
5619 "cirros"
5621 Cirros.
5622 "debian"
5624 Debian.
5625 "fedora"
5627 Fedora.
5628 "freedos"
5630 FreeDOS.
5631 "gentoo"
5633 Gentoo.
5634 "linuxmint"
5636 Linux Mint.
5637 "mageia"
5639 Mageia.
5640 "mandriva"
5642 Mandriva.
5643 "meego"
5645 MeeGo.
5646 "openbsd"
5648 OpenBSD.
5649 "opensuse"
5651 OpenSUSE.
5652 "pardus"
5654 Pardus.
5655 "redhat-based"
5657 Some Red Hat-derived distro.
5658 "rhel"
5660 Red Hat Enterprise Linux.
5661 "scientificlinux"
5663 Scientific Linux.
5664 "slackware"
5666 Slackware.
5667 "sles"
5669 SuSE Linux Enterprise Server or Desktop.
5670 "suse-based"
5672 Some openSuSE-derived distro.
5673 "ttylinux"
5675 ttylinux.
5676 "ubuntu"
5678 Ubuntu.
5679 "unknown"
5681 The distro could not be determined.
5682 "windows"
5684 Windows does not have distributions. This string is returned if
5685 the OS type is Windows.
5686 Future versions of libguestfs may return other strings here. The
5688 caller should be prepared to handle any string.
5689 Please read "INSPECTION" in guestfs(3) for more details.
5691 This function returns a string, or NULL on error. The caller must free
5693 the returned string after use.
5694 (Added in 1.5.3)
5696 guestfs_inspect_get_drive_mappings
5698 char **
5699 guestfs_inspect_get_drive_mappings (guestfs_h *g,
5700 const char *root);
5701 This call is useful for Windows which uses a primitive system of
5703 assigning drive letters (like "C:") to partitions. This inspection API
5704 examines the Windows Registry to find out how disks/partitions are
5705 mapped to drive letters, and returns a hash table as in the example
5706 below:
5707 C => /dev/vda2
5709 E => /dev/vdb1
5710 F => /dev/vdc1
5711 Note that keys are drive letters. For Windows, the key is case
5713 insensitive and just contains the drive letter, without the customary
5714 colon separator character.
5715 In future we may support other operating systems that also used drive
5717 letters, but the keys for those might not be case insensitive and might
5718 be longer than 1 character. For example in OS-9, hard drives were
5719 named "h0", "h1" etc.
5720 For Windows guests, currently only hard drive mappings are returned.
5722 Removable disks (eg. DVD-ROMs) are ignored.
5723 For guests that do not use drive mappings, or if the drive mappings
5725 could not be determined, this returns an empty hash table.
5726 Please read "INSPECTION" in guestfs(3) for more details. See also
5728 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
5729 This function returns a NULL-terminated array of strings, or NULL if
5731 there was an error. The array of strings will always have length
5732 "2n+1", where "n" keys and values alternate, followed by the trailing
5733 NULL entry. The caller must free the strings and the array after use.
5734 (Added in 1.9.17)
5736 guestfs_inspect_get_filesystems
5738 char **
5739 guestfs_inspect_get_filesystems (guestfs_h *g,
5740 const char *root);
5741 This returns a list of all the filesystems that we think are associated
5743 with this operating system. This includes the root filesystem, other
5744 ordinary filesystems, and non-mounted devices like swap partitions.
5745 In the case of a multi-boot virtual machine, it is possible for a
5747 filesystem to be shared between operating systems.
5748 Please read "INSPECTION" in guestfs(3) for more details. See also
5750 "guestfs_inspect_get_mountpoints".
5751 This function returns a NULL-terminated array of strings (like
5753 environ(3)), or NULL if there was an error. The caller must free the
5754 strings and the array after use.
5755 (Added in 1.5.3)
5757 guestfs_inspect_get_format
5759 char *
5760 guestfs_inspect_get_format (guestfs_h *g,
5761 const char *root);
5762 This returns the format of the inspected operating system. You can use
5764 it to detect install images, live CDs and similar.
5765 Currently defined formats are:
5767 "installed"
5769 This is an installed operating system.
5770 "installer"
5772 The disk image being inspected is not an installed operating
5773 system, but a bootable install disk, live CD, or similar.
5774 "unknown"
5776 The format of this disk image is not known.
5777 Future versions of libguestfs may return other strings here. The
5779 caller should be prepared to handle any string.
5780 Please read "INSPECTION" in guestfs(3) for more details.
5782 This function returns a string, or NULL on error. The caller must free
5784 the returned string after use.
5785 (Added in 1.9.4)
5787 guestfs_inspect_get_hostname
5789 char *
5790 guestfs_inspect_get_hostname (guestfs_h *g,
5791 const char *root);
5792 This function returns the hostname of the operating system as found by
5794 inspection of the guest's configuration files.
5795 If the hostname could not be determined, then the string "unknown" is
5797 returned.
5798 Please read "INSPECTION" in guestfs(3) for more details.
5800 This function returns a string, or NULL on error. The caller must free
5802 the returned string after use.
5803 (Added in 1.7.9)
5805 guestfs_inspect_get_icon
5807 char *
5808 guestfs_inspect_get_icon (guestfs_h *g,
5809 const char *root,
5810 size_t *size_r,
5811 ...);
5812 You may supply a list of optional arguments to this call. Use zero or
5814 more of the following pairs of parameters, and terminate the list with
5815 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5816 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
5818 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
5819 This function returns an icon corresponding to the inspected operating
5821 system. The icon is returned as a buffer containing a PNG image (re-
5822 encoded to PNG if necessary).
5823 If it was not possible to get an icon this function returns a zero-
5825 length (non-NULL) buffer. Callers must check for this case.
5826 Libguestfs will start by looking for a file called "/etc/favicon.png"
5828 or "C:\etc\favicon.png" and if it has the correct format, the contents
5829 of this file will be returned. You can disable favicons by passing the
5830 optional "favicon" boolean as false (default is true).
5831 If finding the favicon fails, then we look in other places in the guest
5833 for a suitable icon.
5834 If the optional "highquality" boolean is true then only high quality
5836 icons are returned, which means only icons of high resolution with an
5837 alpha channel. The default (false) is to return any icon we can, even
5838 if it is of substandard quality.
5839 Notes:
5841 · Unlike most other inspection API calls, the guest's disks must be
5843 mounted up before you call this, since it needs to read information
5844 from the guest filesystem during the call.
5845 · Security: The icon data comes from the untrusted guest, and should
5847 be treated with caution. PNG files have been known to contain
5848 exploits. Ensure that libpng (or other relevant libraries) are
5849 fully up to date before trying to process or display the icon.
5850 · The PNG image returned can be any size. It might not be square.
5852 Libguestfs tries to return the largest, highest quality icon
5853 available. The application must scale the icon to the required
5854 size.
5855 · Extracting icons from Windows guests requires the external
5857 "wrestool" program from the "icoutils" package, and several
5858 programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
5859 package. These must be installed separately.
5860 · Operating system icons are usually trademarks. Seek legal advice
5862 before using trademarks in applications.
5863 This function returns a buffer, or NULL on error. The size of the
5865 returned buffer is written to *size_r. The caller must free the
5866 returned buffer after use.
5867 (Added in 1.11.12)
5869 guestfs_inspect_get_icon_va
5871 char *
5872 guestfs_inspect_get_icon_va (guestfs_h *g,
5873 const char *root,
5874 size_t *size_r,
5875 va_list args);
5876 This is the "va_list variant" of "guestfs_inspect_get_icon".
5878 See "CALLS WITH OPTIONAL ARGUMENTS".
5880 guestfs_inspect_get_icon_argv
5882 char *
5883 guestfs_inspect_get_icon_argv (guestfs_h *g,
5884 const char *root,
5885 size_t *size_r,
5886 const struct guestfs_inspect_get_icon_argv *optargs);
5887 This is the "argv variant" of "guestfs_inspect_get_icon".
5889 See "CALLS WITH OPTIONAL ARGUMENTS".
5891 guestfs_inspect_get_major_version
5893 int
5894 guestfs_inspect_get_major_version (guestfs_h *g,
5895 const char *root);
5896 This returns the major version number of the inspected operating
5898 system.
5899 Windows uses a consistent versioning scheme which is not reflected in
5901 the popular public names used by the operating system. Notably the
5902 operating system known as "Windows 7" is really version 6.1 (ie. major
5903 = 6, minor = 1). You can find out the real versions corresponding to
5904 releases of Windows by consulting Wikipedia or MSDN.
5905 If the version could not be determined, then 0 is returned.
5907 Please read "INSPECTION" in guestfs(3) for more details.
5909 On error this function returns -1.
5911 (Added in 1.5.3)
5913 guestfs_inspect_get_minor_version
5915 int
5916 guestfs_inspect_get_minor_version (guestfs_h *g,
5917 const char *root);
5918 This returns the minor version number of the inspected operating
5920 system.
5921 If the version could not be determined, then 0 is returned.
5923 Please read "INSPECTION" in guestfs(3) for more details. See also
5925 "guestfs_inspect_get_major_version".
5926 On error this function returns -1.
5928 (Added in 1.5.3)
5930 guestfs_inspect_get_mountpoints
5932 char **
5933 guestfs_inspect_get_mountpoints (guestfs_h *g,
5934 const char *root);
5935 This returns a hash of where we think the filesystems associated with
5937 this operating system should be mounted. Callers should note that this
5938 is at best an educated guess made by reading configuration files such
5939 as "/etc/fstab". In particular note that this may return filesystems
5940 which are non-existent or not mountable and callers should be prepared
5941 to handle or ignore failures if they try to mount them.
5942 Each element in the returned hashtable has a key which is the path of
5944 the mountpoint (eg. "/boot") and a value which is the filesystem that
5945 would be mounted there (eg. "/dev/sda1").
5946 Non-mounted devices such as swap devices are not returned in this list.
5948 For operating systems like Windows which still use drive letters, this
5950 call will only return an entry for the first drive "mounted on" "/".
5951 For information about the mapping of drive letters to partitions, see
5952 "guestfs_inspect_get_drive_mappings".
5953 Please read "INSPECTION" in guestfs(3) for more details. See also
5955 "guestfs_inspect_get_filesystems".
5956 This function returns a NULL-terminated array of strings, or NULL if
5958 there was an error. The array of strings will always have length
5959 "2n+1", where "n" keys and values alternate, followed by the trailing
5960 NULL entry. The caller must free the strings and the array after use.
5961 (Added in 1.5.3)
5963 guestfs_inspect_get_package_format
5965 char *
5966 guestfs_inspect_get_package_format (guestfs_h *g,
5967 const char *root);
5968 This function and "guestfs_inspect_get_package_management" return the
5970 package format and package management tool used by the inspected
5971 operating system. For example for Fedora these functions would return
5972 "rpm" (package format) and "yum" (package management).
5973 This returns the string "unknown" if we could not determine the package
5975 format or if the operating system does not have a real packaging system
5976 (eg. Windows).
5977 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
5979 "pkgsrc". Future versions of libguestfs may return other strings.
5980 Please read "INSPECTION" in guestfs(3) for more details.
5982 This function returns a string, or NULL on error. The caller must free
5984 the returned string after use.
5985 (Added in 1.7.5)
5987 guestfs_inspect_get_package_management
5989 char *
5990 guestfs_inspect_get_package_management (guestfs_h *g,
5991 const char *root);
5992 "guestfs_inspect_get_package_format" and this function return the
5994 package format and package management tool used by the inspected
5995 operating system. For example for Fedora these functions would return
5996 "rpm" (package format) and "yum" (package management).
5997 This returns the string "unknown" if we could not determine the package
5999 management tool or if the operating system does not have a real
6000 packaging system (eg. Windows).
6001 Possible strings include: "yum", "up2date", "apt" (for all Debian
6003 derivatives), "portage", "pisi", "pacman", "urpmi", "zypper". Future
6004 versions of libguestfs may return other strings.
6005 Please read "INSPECTION" in guestfs(3) for more details.
6007 This function returns a string, or NULL on error. The caller must free
6009 the returned string after use.
6010 (Added in 1.7.5)
6012 guestfs_inspect_get_product_name
6014 char *
6015 guestfs_inspect_get_product_name (guestfs_h *g,
6016 const char *root);
6017 This returns the product name of the inspected operating system. The
6019 product name is generally some freeform string which can be displayed
6020 to the user, but should not be parsed by programs.
6021 If the product name could not be determined, then the string "unknown"
6023 is returned.
6024 Please read "INSPECTION" in guestfs(3) for more details.
6026 This function returns a string, or NULL on error. The caller must free
6028 the returned string after use.
6029 (Added in 1.5.3)
6031 guestfs_inspect_get_product_variant
6033 char *
6034 guestfs_inspect_get_product_variant (guestfs_h *g,
6035 const char *root);
6036 This returns the product variant of the inspected operating system.
6038 For Windows guests, this returns the contents of the Registry key
6040 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
6041 which is usually a string such as "Client" or "Server" (other values
6042 are possible). This can be used to distinguish consumer and enterprise
6043 versions of Windows that have the same version number (for example,
6044 Windows 7 and Windows 2008 Server are both version 6.1, but the former
6045 is "Client" and the latter is "Server").
6046 For enterprise Linux guests, in future we intend this to return the
6048 product variant such as "Desktop", "Server" and so on. But this is not
6049 implemented at present.
6050 If the product variant could not be determined, then the string
6052 "unknown" is returned.
6053 Please read "INSPECTION" in guestfs(3) for more details. See also
6055 "guestfs_inspect_get_product_name",
6056 "guestfs_inspect_get_major_version".
6057 This function returns a string, or NULL on error. The caller must free
6059 the returned string after use.
6060 (Added in 1.9.13)
6062 guestfs_inspect_get_roots
6064 char **
6065 guestfs_inspect_get_roots (guestfs_h *g);
6066 This function is a convenient way to get the list of root devices, as
6068 returned from a previous call to "guestfs_inspect_os", but without
6069 redoing the whole inspection process.
6070 This returns an empty list if either no root devices were found or the
6072 caller has not called "guestfs_inspect_os".
6073 Please read "INSPECTION" in guestfs(3) for more details.
6075 This function returns a NULL-terminated array of strings (like
6077 environ(3)), or NULL if there was an error. The caller must free the
6078 strings and the array after use.
6079 (Added in 1.7.3)
6081 guestfs_inspect_get_type
6083 char *
6084 guestfs_inspect_get_type (guestfs_h *g,
6085 const char *root);
6086 This returns the type of the inspected operating system. Currently
6088 defined types are:
6089 "linux"
6091 Any Linux-based operating system.
6092 "windows"
6094 Any Microsoft Windows operating system.
6095 "freebsd"
6097 FreeBSD.
6098 "netbsd"
6100 NetBSD.
6101 "openbsd"
6103 OpenBSD.
6104 "hurd"
6106 GNU/Hurd.
6107 "dos"
6109 MS-DOS, FreeDOS and others.
6110 "unknown"
6112 The operating system type could not be determined.
6113 Future versions of libguestfs may return other strings here. The
6115 caller should be prepared to handle any string.
6116 Please read "INSPECTION" in guestfs(3) for more details.
6118 This function returns a string, or NULL on error. The caller must free
6120 the returned string after use.
6121 (Added in 1.5.3)
6123 guestfs_inspect_get_windows_current_control_set
6125 char *
6126 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
6127 const char *root);
6128 This returns the Windows CurrentControlSet of the inspected guest. The
6130 CurrentControlSet is a registry key name such as "ControlSet001".
6131 This call assumes that the guest is Windows and that the Registry could
6133 be examined by inspection. If this is not the case then an error is
6134 returned.
6135 Please read "INSPECTION" in guestfs(3) for more details.
6137 This function returns a string, or NULL on error. The caller must free
6139 the returned string after use.
6140 (Added in 1.9.17)
6142 guestfs_inspect_get_windows_systemroot
6144 char *
6145 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
6146 const char *root);
6147 This returns the Windows systemroot of the inspected guest. The
6149 systemroot is a directory path such as "/WINDOWS".
6150 This call assumes that the guest is Windows and that the systemroot
6152 could be determined by inspection. If this is not the case then an
6153 error is returned.
6154 Please read "INSPECTION" in guestfs(3) for more details.
6156 This function returns a string, or NULL on error. The caller must free
6158 the returned string after use.
6159 (Added in 1.5.25)
6161 guestfs_inspect_is_live
6163 int
6164 guestfs_inspect_is_live (guestfs_h *g,
6165 const char *root);
6166 If "guestfs_inspect_get_format" returns "installer" (this is an install
6168 disk), then this returns true if a live image was detected on the disk.
6169 Please read "INSPECTION" in guestfs(3) for more details.
6171 This function returns a C truth value on success or -1 on error.
6173 (Added in 1.9.4)
6175 guestfs_inspect_is_multipart
6177 int
6178 guestfs_inspect_is_multipart (guestfs_h *g,
6179 const char *root);
6180 If "guestfs_inspect_get_format" returns "installer" (this is an install
6182 disk), then this returns true if the disk is part of a set.
6183 Please read "INSPECTION" in guestfs(3) for more details.
6185 This function returns a C truth value on success or -1 on error.
6187 (Added in 1.9.4)
6189 guestfs_inspect_is_netinst
6191 int
6192 guestfs_inspect_is_netinst (guestfs_h *g,
6193 const char *root);
6194 If "guestfs_inspect_get_format" returns "installer" (this is an install
6196 disk), then this returns true if the disk is a network installer, ie.
6197 not a self-contained install CD but one which is likely to require
6198 network access to complete the install.
6199 Please read "INSPECTION" in guestfs(3) for more details.
6201 This function returns a C truth value on success or -1 on error.
6203 (Added in 1.9.4)
6205 guestfs_inspect_list_applications
6207 struct guestfs_application_list *
6208 guestfs_inspect_list_applications (guestfs_h *g,
6209 const char *root);
6210 This function is deprecated. In new code, use the
6212 "guestfs_inspect_list_applications2" call instead.
6213 Deprecated functions will not be removed from the API, but the fact
6215 that they are deprecated indicates that there are problems with correct
6216 use of these functions.
6217 Return the list of applications installed in the operating system.
6219 Note: This call works differently from other parts of the inspection
6221 API. You have to call "guestfs_inspect_os", then
6222 "guestfs_inspect_get_mountpoints", then mount up the disks, before
6223 calling this. Listing applications is a significantly more difficult
6224 operation which requires access to the full filesystem. Also note that
6225 unlike the other "guestfs_inspect_get_*" calls which are just returning
6226 data cached in the libguestfs handle, this call actually reads parts of
6227 the mounted filesystems during the call.
6228 This returns an empty list if the inspection code was not able to
6230 determine the list of applications.
6231 The application structure contains the following fields:
6233 "app_name"
6235 The name of the application. For Red Hat-derived and Debian-
6236 derived Linux guests, this is the package name.
6237 "app_display_name"
6239 The display name of the application, sometimes localized to the
6240 install language of the guest operating system.
6241 If unavailable this is returned as an empty string "". Callers
6243 needing to display something can use "app_name" instead.
6244 "app_epoch"
6246 For package managers which use epochs, this contains the epoch of
6247 the package (an integer). If unavailable, this is returned as 0.
6248 "app_version"
6250 The version string of the application or package. If unavailable
6251 this is returned as an empty string "".
6252 "app_release"
6254 The release string of the application or package, for package
6255 managers that use this. If unavailable this is returned as an
6256 empty string "".
6257 "app_install_path"
6259 The installation path of the application (on operating systems such
6260 as Windows which use installation paths). This path is in the
6261 format used by the guest operating system, it is not a libguestfs
6262 path.
6263 If unavailable this is returned as an empty string "".
6265 "app_trans_path"
6267 The install path translated into a libguestfs path. If unavailable
6268 this is returned as an empty string "".
6269 "app_publisher"
6271 The name of the publisher of the application, for package managers
6272 that use this. If unavailable this is returned as an empty string
6273 "".
6274 "app_url"
6276 The URL (eg. upstream URL) of the application. If unavailable this
6277 is returned as an empty string "".
6278 "app_source_package"
6280 For packaging systems which support this, the name of the source
6281 package. If unavailable this is returned as an empty string "".
6282 "app_summary"
6284 A short (usually one line) description of the application or
6285 package. If unavailable this is returned as an empty string "".
6286 "app_description"
6288 A longer description of the application or package. If unavailable
6289 this is returned as an empty string "".
6290 Please read "INSPECTION" in guestfs(3) for more details.
6292 This function returns a "struct guestfs_application_list *", or NULL if
6294 there was an error. The caller must call
6295 "guestfs_free_application_list" after use.
6296 (Added in 1.7.8)
6298 guestfs_inspect_list_applications2
6300 struct guestfs_application2_list *
6301 guestfs_inspect_list_applications2 (guestfs_h *g,
6302 const char *root);
6303 Return the list of applications installed in the operating system.
6305 Note: This call works differently from other parts of the inspection
6307 API. You have to call "guestfs_inspect_os", then
6308 "guestfs_inspect_get_mountpoints", then mount up the disks, before
6309 calling this. Listing applications is a significantly more difficult
6310 operation which requires access to the full filesystem. Also note that
6311 unlike the other "guestfs_inspect_get_*" calls which are just returning
6312 data cached in the libguestfs handle, this call actually reads parts of
6313 the mounted filesystems during the call.
6314 This returns an empty list if the inspection code was not able to
6316 determine the list of applications.
6317 The application structure contains the following fields:
6319 "app2_name"
6321 The name of the application. For Red Hat-derived and Debian-
6322 derived Linux guests, this is the package name.
6323 "app2_display_name"
6325 The display name of the application, sometimes localized to the
6326 install language of the guest operating system.
6327 If unavailable this is returned as an empty string "". Callers
6329 needing to display something can use "app2_name" instead.
6330 "app2_epoch"
6332 For package managers which use epochs, this contains the epoch of
6333 the package (an integer). If unavailable, this is returned as 0.
6334 "app2_version"
6336 The version string of the application or package. If unavailable
6337 this is returned as an empty string "".
6338 "app2_release"
6340 The release string of the application or package, for package
6341 managers that use this. If unavailable this is returned as an
6342 empty string "".
6343 "app2_arch"
6345 The architecture string of the application or package, for package
6346 managers that use this. If unavailable this is returned as an
6347 empty string "".
6348 "app2_install_path"
6350 The installation path of the application (on operating systems such
6351 as Windows which use installation paths). This path is in the
6352 format used by the guest operating system, it is not a libguestfs
6353 path.
6354 If unavailable this is returned as an empty string "".
6356 "app2_trans_path"
6358 The install path translated into a libguestfs path. If unavailable
6359 this is returned as an empty string "".
6360 "app2_publisher"
6362 The name of the publisher of the application, for package managers
6363 that use this. If unavailable this is returned as an empty string
6364 "".
6365 "app2_url"
6367 The URL (eg. upstream URL) of the application. If unavailable this
6368 is returned as an empty string "".
6369 "app2_source_package"
6371 For packaging systems which support this, the name of the source
6372 package. If unavailable this is returned as an empty string "".
6373 "app2_summary"
6375 A short (usually one line) description of the application or
6376 package. If unavailable this is returned as an empty string "".
6377 "app2_description"
6379 A longer description of the application or package. If unavailable
6380 this is returned as an empty string "".
6381 Please read "INSPECTION" in guestfs(3) for more details.
6383 This function returns a "struct guestfs_application2_list *", or NULL
6385 if there was an error. The caller must call
6386 "guestfs_free_application2_list" after use.
6387 (Added in 1.19.56)
6389 guestfs_inspect_os
6391 char **
6392 guestfs_inspect_os (guestfs_h *g);
6393 This function uses other libguestfs functions and certain heuristics to
6395 inspect the disk(s) (usually disks belonging to a virtual machine),
6396 looking for operating systems.
6397 The list returned is empty if no operating systems were found.
6399 If one operating system was found, then this returns a list with a
6401 single element, which is the name of the root filesystem of this
6402 operating system. It is also possible for this function to return a
6403 list containing more than one element, indicating a dual-boot or multi-
6404 boot virtual machine, with each element being the root filesystem of
6405 one of the operating systems.
6406 You can pass the root string(s) returned to other
6408 "guestfs_inspect_get_*" functions in order to query further information
6409 about each operating system, such as the name and version.
6410 This function uses other libguestfs features such as "guestfs_mount_ro"
6412 and "guestfs_umount_all" in order to mount and unmount filesystems and
6413 look at the contents. This should be called with no disks currently
6414 mounted. The function may also use Augeas, so any existing Augeas
6415 handle will be closed.
6416 This function cannot decrypt encrypted disks. The caller must do that
6418 first (supplying the necessary keys) if the disk is encrypted.
6419 Please read "INSPECTION" in guestfs(3) for more details.
6421 See also "guestfs_list_filesystems".
6423 This function returns a NULL-terminated array of strings (like
6425 environ(3)), or NULL if there was an error. The caller must free the
6426 strings and the array after use.
6427 (Added in 1.5.3)
6429 guestfs_is_blockdev
6431 int
6432 guestfs_is_blockdev (guestfs_h *g,
6433 const char *path);
6434 This returns "true" if and only if there is a block device with the
6436 given "path" name.
6437 See also "guestfs_stat".
6439 This function returns a C truth value on success or -1 on error.
6441 (Added in 1.5.10)
6443 guestfs_is_busy
6445 int
6446 guestfs_is_busy (guestfs_h *g);
6447 This always returns false. This function is deprecated with no
6449 replacement. Do not use this function.
6450 For more information on states, see guestfs(3).
6452 This function returns a C truth value on success or -1 on error.
6454 (Added in 1.0.2)
6456 guestfs_is_chardev
6458 int
6459 guestfs_is_chardev (guestfs_h *g,
6460 const char *path);
6461 This returns "true" if and only if there is a character device with the
6463 given "path" name.
6464 See also "guestfs_stat".
6466 This function returns a C truth value on success or -1 on error.
6468 (Added in 1.5.10)
6470 guestfs_is_config
6472 int
6473 guestfs_is_config (guestfs_h *g);
6474 This returns true iff this handle is being configured (in the "CONFIG"
6476 state).
6477 For more information on states, see guestfs(3).
6479 This function returns a C truth value on success or -1 on error.
6481 (Added in 1.0.2)
6483 guestfs_is_dir
6485 int
6486 guestfs_is_dir (guestfs_h *g,
6487 const char *path);
6488 This returns "true" if and only if there is a directory with the given
6490 "path" name. Note that it returns false for other objects like files.
6491 See also "guestfs_stat".
6493 This function returns a C truth value on success or -1 on error.
6495 (Added in 0.8)
6497 guestfs_is_fifo
6499 int
6500 guestfs_is_fifo (guestfs_h *g,
6501 const char *path);
6502 This returns "true" if and only if there is a FIFO (named pipe) with
6504 the given "path" name.
6505 See also "guestfs_stat".
6507 This function returns a C truth value on success or -1 on error.
6509 (Added in 1.5.10)
6511 guestfs_is_file
6513 int
6514 guestfs_is_file (guestfs_h *g,
6515 const char *path);
6516 This returns "true" if and only if there is a regular file with the
6518 given "path" name. Note that it returns false for other objects like
6519 directories.
6520 See also "guestfs_stat".
6522 This function returns a C truth value on success or -1 on error.
6524 (Added in 0.8)
6526 guestfs_is_launching
6528 int
6529 guestfs_is_launching (guestfs_h *g);
6530 This returns true iff this handle is launching the subprocess (in the
6532 "LAUNCHING" state).
6533 For more information on states, see guestfs(3).
6535 This function returns a C truth value on success or -1 on error.
6537 (Added in 1.0.2)
6539 guestfs_is_lv
6541 int
6542 guestfs_is_lv (guestfs_h *g,
6543 const char *device);
6544 This command tests whether "device" is a logical volume, and returns
6546 true iff this is the case.
6547 This function returns a C truth value on success or -1 on error.
6549 (Added in 1.5.3)
6551 guestfs_is_ready
6553 int
6554 guestfs_is_ready (guestfs_h *g);
6555 This returns true iff this handle is ready to accept commands (in the
6557 "READY" state).
6558 For more information on states, see guestfs(3).
6560 This function returns a C truth value on success or -1 on error.
6562 (Added in 1.0.2)
6564 guestfs_is_socket
6566 int
6567 guestfs_is_socket (guestfs_h *g,
6568 const char *path);
6569 This returns "true" if and only if there is a Unix domain socket with
6571 the given "path" name.
6572 See also "guestfs_stat".
6574 This function returns a C truth value on success or -1 on error.
6576 (Added in 1.5.10)
6578 guestfs_is_symlink
6580 int
6581 guestfs_is_symlink (guestfs_h *g,
6582 const char *path);
6583 This returns "true" if and only if there is a symbolic link with the
6585 given "path" name.
6586 See also "guestfs_stat".
6588 This function returns a C truth value on success or -1 on error.
6590 (Added in 1.5.10)
6592 guestfs_is_zero
6594 int
6595 guestfs_is_zero (guestfs_h *g,
6596 const char *path);
6597 This returns true iff the file exists and the file is empty or it
6599 contains all zero bytes.
6600 This function returns a C truth value on success or -1 on error.
6602 (Added in 1.11.8)
6604 guestfs_is_zero_device
6606 int
6607 guestfs_is_zero_device (guestfs_h *g,
6608 const char *device);
6609 This returns true iff the device exists and contains all zero bytes.
6611 Note that for large devices this can take a long time to run.
6613 This function returns a C truth value on success or -1 on error.
6615 (Added in 1.11.8)
6617 guestfs_isoinfo
6619 struct guestfs_isoinfo *
6620 guestfs_isoinfo (guestfs_h *g,
6621 const char *isofile);
6622 This is the same as "guestfs_isoinfo_device" except that it works for
6624 an ISO file located inside some other mounted filesystem. Note that in
6625 the common case where you have added an ISO file as a libguestfs
6626 device, you would not call this. Instead you would call
6627 "guestfs_isoinfo_device".
6628 This function returns a "struct guestfs_isoinfo *", or NULL if there
6630 was an error. The caller must call "guestfs_free_isoinfo" after use.
6631 (Added in 1.17.19)
6633 guestfs_isoinfo_device
6635 struct guestfs_isoinfo *
6636 guestfs_isoinfo_device (guestfs_h *g,
6637 const char *device);
6638 "device" is an ISO device. This returns a struct of information read
6640 from the primary volume descriptor (the ISO equivalent of the
6641 superblock) of the device.
6642 Usually it is more efficient to use the isoinfo(1) command with the -d
6644 option on the host to analyze ISO files, instead of going through
6645 libguestfs.
6646 For information on the primary volume descriptor fields, see
6648 http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
6649 This function returns a "struct guestfs_isoinfo *", or NULL if there
6651 was an error. The caller must call "guestfs_free_isoinfo" after use.
6652 (Added in 1.17.19)
6654 guestfs_kill_subprocess
6656 int
6657 guestfs_kill_subprocess (guestfs_h *g);
6658 This function is deprecated. In new code, use the "guestfs_shutdown"
6660 call instead.
6661 Deprecated functions will not be removed from the API, but the fact
6663 that they are deprecated indicates that there are problems with correct
6664 use of these functions.
6665 This kills the qemu subprocess.
6667 Do not call this. See: "guestfs_shutdown" instead.
6669 This function returns 0 on success or -1 on error.
6671 (Added in 0.3)
6673 guestfs_launch
6675 int
6676 guestfs_launch (guestfs_h *g);
6677 Internally libguestfs is implemented by running a virtual machine using
6679 qemu(1).
6680 You should call this after configuring the handle (eg. adding drives)
6682 but before performing any actions.
6683 Do not call "guestfs_launch" twice on the same handle. Although it
6685 will not give an error (for historical reasons), the precise behaviour
6686 when you do this is not well defined. Handles are very cheap to
6687 create, so create a new one for each launch.
6688 This function returns 0 on success or -1 on error.
6690 This long-running command can generate progress notification messages
6692 so that the caller can display a progress bar or indicator. To receive
6693 these messages, the caller must register a progress event callback.
6694 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
6695 (Added in 0.3)
6697 guestfs_lchown
6699 int
6700 guestfs_lchown (guestfs_h *g,
6701 int owner,
6702 int group,
6703 const char *path);
6704 Change the file owner to "owner" and group to "group". This is like
6706 "guestfs_chown" but if "path" is a symlink then the link itself is
6707 changed, not the target.
6708 Only numeric uid and gid are supported. If you want to use names, you
6710 will need to locate and parse the password file yourself (Augeas
6711 support makes this relatively easy).
6712 This function returns 0 on success or -1 on error.
6714 (Added in 1.0.77)
6716 guestfs_ldmtool_create_all
6718 int
6719 guestfs_ldmtool_create_all (guestfs_h *g);
6720 This function scans all block devices looking for Windows dynamic disk
6722 volumes and partitions, and creates devices for any that were found.
6723 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
6725 return all devices.
6726 Note that you don't normally need to call this explicitly, since it is
6728 done automatically at "guestfs_launch" time. However you might want to
6729 call this function if you have hotplugged disks or have just created a
6730 Windows dynamic disk.
6731 This function returns 0 on success or -1 on error.
6733 guestfs_ldmtool_diskgroup_disks
6735 char **
6736 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
6737 const char *diskgroup);
6738 Return the disks in a Windows dynamic disk group. The "diskgroup"
6740 parameter should be the GUID of a disk group, one element from the list
6741 returned by "guestfs_ldmtool_scan".
6742 This function returns a NULL-terminated array of strings (like
6744 environ(3)), or NULL if there was an error. The caller must free the
6745 strings and the array after use.
6746 guestfs_ldmtool_diskgroup_name
6748 char *
6749 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
6750 const char *diskgroup);
6751 Return the name of a Windows dynamic disk group. The "diskgroup"
6753 parameter should be the GUID of a disk group, one element from the list
6754 returned by "guestfs_ldmtool_scan".
6755 This function returns a string, or NULL on error. The caller must free
6757 the returned string after use.
6758 guestfs_ldmtool_diskgroup_volumes
6760 char **
6761 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
6762 const char *diskgroup);
6763 Return the volumes in a Windows dynamic disk group. The "diskgroup"
6765 parameter should be the GUID of a disk group, one element from the list
6766 returned by "guestfs_ldmtool_scan".
6767 This function returns a NULL-terminated array of strings (like
6769 environ(3)), or NULL if there was an error. The caller must free the
6770 strings and the array after use.
6771 guestfs_ldmtool_remove_all
6773 int
6774 guestfs_ldmtool_remove_all (guestfs_h *g);
6775 This is essentially the opposite of "guestfs_ldmtool_create_all". It
6777 removes the device mapper mappings for all Windows dynamic disk volumes
6778 This function returns 0 on success or -1 on error.
6780 guestfs_ldmtool_scan
6782 char **
6783 guestfs_ldmtool_scan (guestfs_h *g);
6784 This function scans for Windows dynamic disks. It returns a list of
6786 identifiers (GUIDs) for all disk groups that were found. These
6787 identifiers can be passed to other "guestfs_ldmtool_*" functions.
6788 This function scans all block devices. To scan a subset of block
6790 devices, call "guestfs_ldmtool_scan_devices" instead.
6791 This function returns a NULL-terminated array of strings (like
6793 environ(3)), or NULL if there was an error. The caller must free the
6794 strings and the array after use.
6795 guestfs_ldmtool_scan_devices
6797 char **
6798 guestfs_ldmtool_scan_devices (guestfs_h *g,
6799 char *const *devices);
6800 This function scans for Windows dynamic disks. It returns a list of
6802 identifiers (GUIDs) for all disk groups that were found. These
6803 identifiers can be passed to other "guestfs_ldmtool_*" functions.
6804 The parameter "devices" is a list of block devices which are scanned.
6806 If this list is empty, all block devices are scanned.
6807 This function returns a NULL-terminated array of strings (like
6809 environ(3)), or NULL if there was an error. The caller must free the
6810 strings and the array after use.
6811 guestfs_ldmtool_volume_hint
6813 char *
6814 guestfs_ldmtool_volume_hint (guestfs_h *g,
6815 const char *diskgroup,
6816 const char *volume);
6817 Return the hint field of the volume named "volume" in the disk group
6819 with GUID "diskgroup". This may not be defined, in which case the
6820 empty string is returned. The hint field is often, though not always,
6821 the name of a Windows drive, eg. "E:".
6822 This function returns a string, or NULL on error. The caller must free
6824 the returned string after use.
6825 guestfs_ldmtool_volume_partitions
6827 char **
6828 guestfs_ldmtool_volume_partitions (guestfs_h *g,
6829 const char *diskgroup,
6830 const char *volume);
6831 Return the list of partitions in the volume named "volume" in the disk
6833 group with GUID "diskgroup".
6834 This function returns a NULL-terminated array of strings (like
6836 environ(3)), or NULL if there was an error. The caller must free the
6837 strings and the array after use.
6838 guestfs_ldmtool_volume_type
6840 char *
6841 guestfs_ldmtool_volume_type (guestfs_h *g,
6842 const char *diskgroup,
6843 const char *volume);
6844 Return the type of the volume named "volume" in the disk group with
6846 GUID "diskgroup".
6847 Possible volume types that can be returned here include: "simple",
6849 "spanned", "striped", "mirrored", "raid5". Other types may also be
6850 returned.
6851 This function returns a string, or NULL on error. The caller must free
6853 the returned string after use.
6854 guestfs_lgetxattr
6856 char *
6857 guestfs_lgetxattr (guestfs_h *g,
6858 const char *path,
6859 const char *name,
6860 size_t *size_r);
6861 Get a single extended attribute from file "path" named "name". If
6863 "path" is a symlink, then this call returns an extended attribute from
6864 the symlink.
6865 Normally it is better to get all extended attributes from a file in one
6867 go by calling "guestfs_getxattrs". However some Linux filesystem
6868 implementations are buggy and do not provide a way to list out
6869 attributes. For these filesystems (notably ntfs-3g) you have to know
6870 the names of the extended attributes you want in advance and call this
6871 function.
6872 Extended attribute values are blobs of binary data. If there is no
6874 extended attribute named "name", this returns an error.
6875 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
6877 This function returns a buffer, or NULL on error. The size of the
6879 returned buffer is written to *size_r. The caller must free the
6880 returned buffer after use.
6881 (Added in 1.7.24)
6883 guestfs_lgetxattrs
6885 struct guestfs_xattr_list *
6886 guestfs_lgetxattrs (guestfs_h *g,
6887 const char *path);
6888 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
6890 link, then it returns the extended attributes of the link itself.
6891 This function returns a "struct guestfs_xattr_list *", or NULL if there
6893 was an error. The caller must call "guestfs_free_xattr_list" after
6894 use.
6895 (Added in 1.0.59)
6897 guestfs_list_devices
6899 char **
6900 guestfs_list_devices (guestfs_h *g);
6901 List all the block devices.
6903 The full block device names are returned, eg. "/dev/sda".
6905 See also "guestfs_list_filesystems".
6907 This function returns a NULL-terminated array of strings (like
6909 environ(3)), or NULL if there was an error. The caller must free the
6910 strings and the array after use.
6911 (Added in 0.4)
6913 guestfs_list_disk_labels
6915 char **
6916 guestfs_list_disk_labels (guestfs_h *g);
6917 If you add drives using the optional "label" parameter of
6919 "guestfs_add_drive_opts", you can use this call to map between disk
6920 labels, and raw block device and partition names (like "/dev/sda" and
6921 "/dev/sda1").
6922 This returns a hashtable, where keys are the disk labels (without the
6924 "/dev/disk/guestfs" prefix), and the values are the full raw block
6925 device and partition names (eg. "/dev/sda" and "/dev/sda1").
6926 This function returns a NULL-terminated array of strings, or NULL if
6928 there was an error. The array of strings will always have length
6929 "2n+1", where "n" keys and values alternate, followed by the trailing
6930 NULL entry. The caller must free the strings and the array after use.
6931 (Added in 1.19.49)
6933 guestfs_list_dm_devices
6935 char **
6936 guestfs_list_dm_devices (guestfs_h *g);
6937 List all device mapper devices.
6939 The returned list contains "/dev/mapper/*" devices, eg. ones created by
6941 a previous call to "guestfs_luks_open".
6942 Device mapper devices which correspond to logical volumes are not
6944 returned in this list. Call "guestfs_lvs" if you want to list logical
6945 volumes.
6946 This function returns a NULL-terminated array of strings (like
6948 environ(3)), or NULL if there was an error. The caller must free the
6949 strings and the array after use.
6950 (Added in 1.11.15)
6952 guestfs_list_filesystems
6954 char **
6955 guestfs_list_filesystems (guestfs_h *g);
6956 This inspection command looks for filesystems on partitions, block
6958 devices and logical volumes, returning a list of devices containing
6959 filesystems and their type.
6960 The return value is a hash, where the keys are the devices containing
6962 filesystems, and the values are the filesystem types. For example:
6963 "/dev/sda1" => "ntfs"
6965 "/dev/sda2" => "ext2"
6966 "/dev/vg_guest/lv_root" => "ext4"
6967 "/dev/vg_guest/lv_swap" => "swap"
6968 The value can have the special value "unknown", meaning the content of
6970 the device is undetermined or empty. "swap" means a Linux swap
6971 partition.
6972 This command runs other libguestfs commands, which might include
6974 "guestfs_mount" and "guestfs_umount", and therefore you should use this
6975 soon after launch and only when nothing is mounted.
6976 Not all of the filesystems returned will be mountable. In particular,
6978 swap partitions are returned in the list. Also this command does not
6979 check that each filesystem found is valid and mountable, and some
6980 filesystems might be mountable but require special options.
6981 Filesystems may not all belong to a single logical operating system
6982 (use "guestfs_inspect_os" to look for OSes).
6983 This function returns a NULL-terminated array of strings, or NULL if
6985 there was an error. The array of strings will always have length
6986 "2n+1", where "n" keys and values alternate, followed by the trailing
6987 NULL entry. The caller must free the strings and the array after use.
6988 (Added in 1.5.15)
6990 guestfs_list_ldm_partitions
6992 char **
6993 guestfs_list_ldm_partitions (guestfs_h *g);
6994 This function returns all Windows dynamic disk partitions that were
6996 found at launch time. It returns a list of device names.
6997 This function returns a NULL-terminated array of strings (like
6999 environ(3)), or NULL if there was an error. The caller must free the
7000 strings and the array after use.
7001 guestfs_list_ldm_volumes
7003 char **
7004 guestfs_list_ldm_volumes (guestfs_h *g);
7005 This function returns all Windows dynamic disk volumes that were found
7007 at launch time. It returns a list of device names.
7008 This function returns a NULL-terminated array of strings (like
7010 environ(3)), or NULL if there was an error. The caller must free the
7011 strings and the array after use.
7012 guestfs_list_md_devices
7014 char **
7015 guestfs_list_md_devices (guestfs_h *g);
7016 List all Linux md devices.
7018 This function returns a NULL-terminated array of strings (like
7020 environ(3)), or NULL if there was an error. The caller must free the
7021 strings and the array after use.
7022 (Added in 1.15.4)
7024 guestfs_list_partitions
7026 char **
7027 guestfs_list_partitions (guestfs_h *g);
7028 List all the partitions detected on all block devices.
7030 The full partition device names are returned, eg. "/dev/sda1"
7032 This does not return logical volumes. For that you will need to call
7034 "guestfs_lvs".
7035 See also "guestfs_list_filesystems".
7037 This function returns a NULL-terminated array of strings (like
7039 environ(3)), or NULL if there was an error. The caller must free the
7040 strings and the array after use.
7041 (Added in 0.4)
7043 guestfs_ll
7045 char *
7046 guestfs_ll (guestfs_h *g,
7047 const char *directory);
7048 List the files in "directory" (relative to the root directory, there is
7050 no cwd) in the format of 'ls -la'.
7051 This command is mostly useful for interactive sessions. It is not
7053 intended that you try to parse the output string.
7054 This function returns a string, or NULL on error. The caller must free
7056 the returned string after use.
7057 (Added in 0.4)
7059 guestfs_llz
7061 char *
7062 guestfs_llz (guestfs_h *g,
7063 const char *directory);
7064 List the files in "directory" in the format of 'ls -laZ'.
7066 This command is mostly useful for interactive sessions. It is not
7068 intended that you try to parse the output string.
7069 This function returns a string, or NULL on error. The caller must free
7071 the returned string after use.
7072 (Added in 1.17.6)
7074 guestfs_ln
7076 int
7077 guestfs_ln (guestfs_h *g,
7078 const char *target,
7079 const char *linkname);
7080 This command creates a hard link using the "ln" command.
7082 This function returns 0 on success or -1 on error.
7084 (Added in 1.0.66)
7086 guestfs_ln_f
7088 int
7089 guestfs_ln_f (guestfs_h *g,
7090 const char *target,
7091 const char *linkname);
7092 This command creates a hard link using the "ln -f" command. The -f
7094 option removes the link ("linkname") if it exists already.
7095 This function returns 0 on success or -1 on error.
7097 (Added in 1.0.66)
7099 guestfs_ln_s
7101 int
7102 guestfs_ln_s (guestfs_h *g,
7103 const char *target,
7104 const char *linkname);
7105 This command creates a symbolic link using the "ln -s" command.
7107 This function returns 0 on success or -1 on error.
7109 (Added in 1.0.66)
7111 guestfs_ln_sf
7113 int
7114 guestfs_ln_sf (guestfs_h *g,
7115 const char *target,
7116 const char *linkname);
7117 This command creates a symbolic link using the "ln -sf" command, The -f
7119 option removes the link ("linkname") if it exists already.
7120 This function returns 0 on success or -1 on error.
7122 (Added in 1.0.66)
7124 guestfs_lremovexattr
7126 int
7127 guestfs_lremovexattr (guestfs_h *g,
7128 const char *xattr,
7129 const char *path);
7130 This is the same as "guestfs_removexattr", but if "path" is a symbolic
7132 link, then it removes an extended attribute of the link itself.
7133 This function returns 0 on success or -1 on error.
7135 (Added in 1.0.59)
7137 guestfs_ls
7139 char **
7140 guestfs_ls (guestfs_h *g,
7141 const char *directory);
7142 List the files in "directory" (relative to the root directory, there is
7144 no cwd). The '.' and '..' entries are not returned, but hidden files
7145 are shown.
7146 This function returns a NULL-terminated array of strings (like
7148 environ(3)), or NULL if there was an error. The caller must free the
7149 strings and the array after use.
7150 (Added in 0.4)
7152 guestfs_ls0
7154 int
7155 guestfs_ls0 (guestfs_h *g,
7156 const char *dir,
7157 const char *filenames);
7158 This specialized command is used to get a listing of the filenames in
7160 the directory "dir". The list of filenames is written to the local
7161 file "filenames" (on the host).
7162 In the output file, the filenames are separated by "\0" characters.
7164 "." and ".." are not returned. The filenames are not sorted.
7166 This function returns 0 on success or -1 on error.
7168 (Added in 1.19.32)
7170 guestfs_lsetxattr
7172 int
7173 guestfs_lsetxattr (guestfs_h *g,
7174 const char *xattr,
7175 const char *val,
7176 int vallen,
7177 const char *path);
7178 This is the same as "guestfs_setxattr", but if "path" is a symbolic
7180 link, then it sets an extended attribute of the link itself.
7181 This function returns 0 on success or -1 on error.
7183 (Added in 1.0.59)
7185 guestfs_lstat
7187 struct guestfs_stat *
7188 guestfs_lstat (guestfs_h *g,
7189 const char *path);
7190 Returns file information for the given "path".
7192 This is the same as "guestfs_stat" except that if "path" is a symbolic
7194 link, then the link is stat-ed, not the file it refers to.
7195 This is the same as the lstat(2) system call.
7197 This function returns a "struct guestfs_stat *", or NULL if there was
7199 an error. The caller must call "guestfs_free_stat" after use.
7200 (Added in 0.9.2)
7202 guestfs_lstatlist
7204 struct guestfs_stat_list *
7205 guestfs_lstatlist (guestfs_h *g,
7206 const char *path,
7207 char *const *names);
7208 This call allows you to perform the "guestfs_lstat" operation on
7210 multiple files, where all files are in the directory "path". "names"
7211 is the list of files from this directory.
7212 On return you get a list of stat structs, with a one-to-one
7214 correspondence to the "names" list. If any name did not exist or could
7215 not be lstat'd, then the "ino" field of that structure is set to "-1".
7216 This call is intended for programs that want to efficiently list a
7218 directory contents without making many round-trips. See also
7219 "guestfs_lxattrlist" for a similarly efficient call for getting
7220 extended attributes.
7221 This function returns a "struct guestfs_stat_list *", or NULL if there
7223 was an error. The caller must call "guestfs_free_stat_list" after use.
7224 (Added in 1.0.77)
7226 guestfs_luks_add_key
7228 int
7229 guestfs_luks_add_key (guestfs_h *g,
7230 const char *device,
7231 const char *key,
7232 const char *newkey,
7233 int keyslot);
7234 This command adds a new key on LUKS device "device". "key" is any
7236 existing key, and is used to access the device. "newkey" is the new
7237 key to add. "keyslot" is the key slot that will be replaced.
7238 Note that if "keyslot" already contains a key, then this command will
7240 fail. You have to use "guestfs_luks_kill_slot" first to remove that
7241 key.
7242 This function returns 0 on success or -1 on error.
7244 This function takes a key or passphrase parameter which could contain
7246 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
7247 information.
7248 (Added in 1.5.2)
7250 guestfs_luks_close
7252 int
7253 guestfs_luks_close (guestfs_h *g,
7254 const char *device);
7255 This closes a LUKS device that was created earlier by
7257 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
7258 must be the name of the LUKS mapping device (ie. "/dev/mapper/mapname")
7259 and not the name of the underlying block device.
7260 This function returns 0 on success or -1 on error.
7262 (Added in 1.5.1)
7264 guestfs_luks_format
7266 int
7267 guestfs_luks_format (guestfs_h *g,
7268 const char *device,
7269 const char *key,
7270 int keyslot);
7271 This command erases existing data on "device" and formats the device as
7273 a LUKS encrypted device. "key" is the initial key, which is added to
7274 key slot "slot". (LUKS supports 8 key slots, numbered 0-7).
7275 This function returns 0 on success or -1 on error.
7277 This function takes a key or passphrase parameter which could contain
7279 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
7280 information.
7281 (Added in 1.5.2)
7283 guestfs_luks_format_cipher
7285 int
7286 guestfs_luks_format_cipher (guestfs_h *g,
7287 const char *device,
7288 const char *key,
7289 int keyslot,
7290 const char *cipher);
7291 This command is the same as "guestfs_luks_format" but it also allows
7293 you to set the "cipher" used.
7294 This function returns 0 on success or -1 on error.
7296 This function takes a key or passphrase parameter which could contain
7298 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
7299 information.
7300 (Added in 1.5.2)
7302 guestfs_luks_kill_slot
7304 int
7305 guestfs_luks_kill_slot (guestfs_h *g,
7306 const char *device,
7307 const char *key,
7308 int keyslot);
7309 This command deletes the key in key slot "keyslot" from the encrypted
7311 LUKS device "device". "key" must be one of the other keys.
7312 This function returns 0 on success or -1 on error.
7314 This function takes a key or passphrase parameter which could contain
7316 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
7317 information.
7318 (Added in 1.5.2)
7320 guestfs_luks_open
7322 int
7323 guestfs_luks_open (guestfs_h *g,
7324 const char *device,
7325 const char *key,
7326 const char *mapname);
7327 This command opens a block device which has been encrypted according to
7329 the Linux Unified Key Setup (LUKS) standard.
7330 "device" is the encrypted block device or partition.
7332 The caller must supply one of the keys associated with the LUKS block
7334 device, in the "key" parameter.
7335 This creates a new block device called "/dev/mapper/mapname". Reads
7337 and writes to this block device are decrypted from and encrypted to the
7338 underlying "device" respectively.
7339 If this block device contains LVM volume groups, then calling
7341 "guestfs_vgscan" followed by "guestfs_vg_activate_all" will make them
7342 visible.
7343 Use "guestfs_list_dm_devices" to list all device mapper devices.
7345 This function returns 0 on success or -1 on error.
7347 This function takes a key or passphrase parameter which could contain
7349 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
7350 information.
7351 (Added in 1.5.1)
7353 guestfs_luks_open_ro
7355 int
7356 guestfs_luks_open_ro (guestfs_h *g,
7357 const char *device,
7358 const char *key,
7359 const char *mapname);
7360 This is the same as "guestfs_luks_open" except that a read-only mapping
7362 is created.
7363 This function returns 0 on success or -1 on error.
7365 This function takes a key or passphrase parameter which could contain
7367 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
7368 information.
7369 (Added in 1.5.1)
7371 guestfs_lvcreate
7373 int
7374 guestfs_lvcreate (guestfs_h *g,
7375 const char *logvol,
7376 const char *volgroup,
7377 int mbytes);
7378 This creates an LVM logical volume called "logvol" on the volume group
7380 "volgroup", with "size" megabytes.
7381 This function returns 0 on success or -1 on error.
7383 (Added in 0.8)
7385 guestfs_lvcreate_free
7387 int
7388 guestfs_lvcreate_free (guestfs_h *g,
7389 const char *logvol,
7390 const char *volgroup,
7391 int percent);
7392 Create an LVM logical volume called "/dev/volgroup/logvol", using
7394 approximately "percent" % of the free space remaining in the volume
7395 group. Most usefully, when "percent" is 100 this will create the
7396 largest possible LV.
7397 This function returns 0 on success or -1 on error.
7399 (Added in 1.17.18)
7401 guestfs_lvm_canonical_lv_name
7403 char *
7404 guestfs_lvm_canonical_lv_name (guestfs_h *g,
7405 const char *lvname);
7406 This converts alternative naming schemes for LVs that you might find to
7408 the canonical name. For example, "/dev/mapper/VG-LV" is converted to
7409 "/dev/VG/LV".
7410 This command returns an error if the "lvname" parameter does not refer
7412 to a logical volume.
7413 See also "guestfs_is_lv", "guestfs_canonical_device_name".
7415 This function returns a string, or NULL on error. The caller must free
7417 the returned string after use.
7418 (Added in 1.5.24)
7420 guestfs_lvm_clear_filter
7422 int
7423 guestfs_lvm_clear_filter (guestfs_h *g);
7424 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
7426 to see every block device.
7427 This command also clears the LVM cache and performs a volume group
7429 scan.
7430 This function returns 0 on success or -1 on error.
7432 (Added in 1.5.1)
7434 guestfs_lvm_remove_all
7436 int
7437 guestfs_lvm_remove_all (guestfs_h *g);
7438 This command removes all LVM logical volumes, volume groups and
7440 physical volumes.
7441 This function returns 0 on success or -1 on error.
7443 (Added in 0.8)
7445 guestfs_lvm_set_filter
7447 int
7448 guestfs_lvm_set_filter (guestfs_h *g,
7449 char *const *devices);
7450 This sets the LVM device filter so that LVM will only be able to "see"
7452 the block devices in the list "devices", and will ignore all other
7453 attached block devices.
7454 Where disk image(s) contain duplicate PVs or VGs, this command is
7456 useful to get LVM to ignore the duplicates, otherwise LVM can get
7457 confused. Note also there are two types of duplication possible:
7458 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
7459 cloned but just happen to have the same name. In normal operation you
7460 cannot create this situation, but you can do it outside LVM, eg. by
7461 cloning disk images or by bit twiddling inside the LVM metadata.
7462 This command also clears the LVM cache and performs a volume group
7464 scan.
7465 You can filter whole block devices or individual partitions.
7467 You cannot use this if any VG is currently in use (eg. contains a
7469 mounted filesystem), even if you are not filtering out that VG.
7470 This function returns 0 on success or -1 on error.
7472 (Added in 1.5.1)
7474 guestfs_lvremove
7476 int
7477 guestfs_lvremove (guestfs_h *g,
7478 const char *device);
7479 Remove an LVM logical volume "device", where "device" is the path to
7481 the LV, such as "/dev/VG/LV".
7482 You can also remove all LVs in a volume group by specifying the VG
7484 name, "/dev/VG".
7485 This function returns 0 on success or -1 on error.
7487 (Added in 1.0.13)
7489 guestfs_lvrename
7491 int
7492 guestfs_lvrename (guestfs_h *g,
7493 const char *logvol,
7494 const char *newlogvol);
7495 Rename a logical volume "logvol" with the new name "newlogvol".
7497 This function returns 0 on success or -1 on error.
7499 (Added in 1.0.83)
7501 guestfs_lvresize
7503 int
7504 guestfs_lvresize (guestfs_h *g,
7505 const char *device,
7506 int mbytes);
7507 This resizes (expands or shrinks) an existing LVM logical volume to
7509 "mbytes". When reducing, data in the reduced part is lost.
7510 This function returns 0 on success or -1 on error.
7512 (Added in 1.0.27)
7514 guestfs_lvresize_free
7516 int
7517 guestfs_lvresize_free (guestfs_h *g,
7518 const char *lv,
7519 int percent);
7520 This expands an existing logical volume "lv" so that it fills "pc"% of
7522 the remaining free space in the volume group. Commonly you would call
7523 this with pc = 100 which expands the logical volume as much as
7524 possible, using all remaining free space in the volume group.
7525 This function returns 0 on success or -1 on error.
7527 (Added in 1.3.3)
7529 guestfs_lvs
7531 char **
7532 guestfs_lvs (guestfs_h *g);
7533 List all the logical volumes detected. This is the equivalent of the
7535 lvs(8) command.
7536 This returns a list of the logical volume device names (eg.
7538 "/dev/VolGroup00/LogVol00").
7539 See also "guestfs_lvs_full", "guestfs_list_filesystems".
7541 This function returns a NULL-terminated array of strings (like
7543 environ(3)), or NULL if there was an error. The caller must free the
7544 strings and the array after use.
7545 (Added in 0.4)
7547 guestfs_lvs_full
7549 struct guestfs_lvm_lv_list *
7550 guestfs_lvs_full (guestfs_h *g);
7551 List all the logical volumes detected. This is the equivalent of the
7553 lvs(8) command. The "full" version includes all fields.
7554 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
7556 there was an error. The caller must call "guestfs_free_lvm_lv_list"
7557 after use.
7558 (Added in 0.4)
7560 guestfs_lvuuid
7562 char *
7563 guestfs_lvuuid (guestfs_h *g,
7564 const char *device);
7565 This command returns the UUID of the LVM LV "device".
7567 This function returns a string, or NULL on error. The caller must free
7569 the returned string after use.
7570 (Added in 1.0.87)
7572 guestfs_lxattrlist
7574 struct guestfs_xattr_list *
7575 guestfs_lxattrlist (guestfs_h *g,
7576 const char *path,
7577 char *const *names);
7578 This call allows you to get the extended attributes of multiple files,
7580 where all files are in the directory "path". "names" is the list of
7581 files from this directory.
7582 On return you get a flat list of xattr structs which must be
7584 interpreted sequentially. The first xattr struct always has a zero-
7585 length "attrname". "attrval" in this struct is zero-length to indicate
7586 there was an error doing "lgetxattr" for this file, or is a C string
7587 which is a decimal number (the number of following attributes for this
7588 file, which could be "0"). Then after the first xattr struct are the
7589 zero or more attributes for the first named file. This repeats for the
7590 second and subsequent files.
7591 This call is intended for programs that want to efficiently list a
7593 directory contents without making many round-trips. See also
7594 "guestfs_lstatlist" for a similarly efficient call for getting standard
7595 stats.
7596 This function returns a "struct guestfs_xattr_list *", or NULL if there
7598 was an error. The caller must call "guestfs_free_xattr_list" after
7599 use.
7600 (Added in 1.0.77)
7602 guestfs_max_disks
7604 int
7605 guestfs_max_disks (guestfs_h *g);
7606 Return the maximum number of disks that may be added to a handle (eg.
7608 by "guestfs_add_drive_opts" and similar calls).
7609 This function was added in libguestfs 1.19.7. In previous versions of
7611 libguestfs the limit was 25.
7612 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional information
7614 on this topic.
7615 On error this function returns -1.
7617 (Added in 1.19.7)
7619 guestfs_md_create
7621 int
7622 guestfs_md_create (guestfs_h *g,
7623 const char *name,
7624 char *const *devices,
7625 ...);
7626 You may supply a list of optional arguments to this call. Use zero or
7628 more of the following pairs of parameters, and terminate the list with
7629 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7630 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
7632 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
7633 GUESTFS_MD_CREATE_SPARE, int spare,
7634 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
7635 GUESTFS_MD_CREATE_LEVEL, const char *level,
7636 Create a Linux md (RAID) device named "name" on the devices in the list
7638 "devices".
7639 The optional parameters are:
7641 "missingbitmap"
7643 A bitmap of missing devices. If a bit is set it means that a
7644 missing device is added to the array. The least significant bit
7645 corresponds to the first device in the array.
7646 As examples:
7648 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
7650 resulting array would be "[<missing>, "/dev/sda"]".
7651 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
7653 resulting array would be "["/dev/sda", <missing>]".
7654 This defaults to 0 (no missing devices).
7656 The length of "devices" + the number of bits set in "missingbitmap"
7658 must equal "nrdevices" + "spare".
7659 "nrdevices"
7661 The number of active RAID devices.
7662 If not set, this defaults to the length of "devices" plus the
7664 number of bits set in "missingbitmap".
7665 "spare"
7667 The number of spare devices.
7668 If not set, this defaults to 0.
7670 "chunk"
7672 The chunk size in bytes.
7673 "level"
7675 The RAID level, which can be one of: linear, raid0, 0, stripe,
7676 raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10. Some
7677 of these are synonymous, and more levels may be added in future.
7678 If not set, this defaults to "raid1".
7680 This function returns 0 on success or -1 on error.
7682 (Added in 1.15.6)
7684 guestfs_md_create_va
7686 int
7687 guestfs_md_create_va (guestfs_h *g,
7688 const char *name,
7689 char *const *devices,
7690 va_list args);
7691 This is the "va_list variant" of "guestfs_md_create".
7693 See "CALLS WITH OPTIONAL ARGUMENTS".
7695 guestfs_md_create_argv
7697 int
7698 guestfs_md_create_argv (guestfs_h *g,
7699 const char *name,
7700 char *const *devices,
7701 const struct guestfs_md_create_argv *optargs);
7702 This is the "argv variant" of "guestfs_md_create".
7704 See "CALLS WITH OPTIONAL ARGUMENTS".
7706 guestfs_md_detail
7708 char **
7709 guestfs_md_detail (guestfs_h *g,
7710 const char *md);
7711 This command exposes the output of 'mdadm -DY <md>'. The following
7713 fields are usually present in the returned hash. Other fields may also
7714 be present.
7715 "level"
7717 The raid level of the MD device.
7718 "devices"
7720 The number of underlying devices in the MD device.
7721 "metadata"
7723 The metadata version used.
7724 "uuid"
7726 The UUID of the MD device.
7727 "name"
7729 The name of the MD device.
7730 This function returns a NULL-terminated array of strings, or NULL if
7732 there was an error. The array of strings will always have length
7733 "2n+1", where "n" keys and values alternate, followed by the trailing
7734 NULL entry. The caller must free the strings and the array after use.
7735 (Added in 1.15.6)
7737 guestfs_md_stat
7739 struct guestfs_mdstat_list *
7740 guestfs_md_stat (guestfs_h *g,
7741 const char *md);
7742 This call returns a list of the underlying devices which make up the
7744 single software RAID array device "md".
7745 To get a list of software RAID devices, call "guestfs_list_md_devices".
7747 Each structure returned corresponds to one device along with additional
7749 status information:
7750 "mdstat_device"
7752 The name of the underlying device.
7753 "mdstat_index"
7755 The index of this device within the array.
7756 "mdstat_flags"
7758 Flags associated with this device. This is a string containing (in
7759 no specific order) zero or more of the following flags:
7760 "W" write-mostly
7762 "F" device is faulty
7764 "S" device is a RAID spare
7766 "R" replacement
7768 This function returns a "struct guestfs_mdstat_list *", or NULL if
7770 there was an error. The caller must call "guestfs_free_mdstat_list"
7771 after use.
7772 (Added in 1.17.21)
7774 guestfs_md_stop
7776 int
7777 guestfs_md_stop (guestfs_h *g,
7778 const char *md);
7779 This command deactivates the MD array named "md". The device is
7781 stopped, but it is not destroyed or zeroed.
7782 This function returns 0 on success or -1 on error.
7784 (Added in 1.15.6)
7786 guestfs_mkdir
7788 int
7789 guestfs_mkdir (guestfs_h *g,
7790 const char *path);
7791 Create a directory named "path".
7793 This function returns 0 on success or -1 on error.
7795 (Added in 0.8)
7797 guestfs_mkdir_mode
7799 int
7800 guestfs_mkdir_mode (guestfs_h *g,
7801 const char *path,
7802 int mode);
7803 This command creates a directory, setting the initial permissions of
7805 the directory to "mode".
7806 For common Linux filesystems, the actual mode which is set will be
7808 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
7809 the mode in other ways.
7810 See also "guestfs_mkdir", "guestfs_umask"
7812 This function returns 0 on success or -1 on error.
7814 (Added in 1.0.77)
7816 guestfs_mkdir_p
7818 int
7819 guestfs_mkdir_p (guestfs_h *g,
7820 const char *path);
7821 Create a directory named "path", creating any parent directories as
7823 necessary. This is like the "mkdir -p" shell command.
7824 This function returns 0 on success or -1 on error.
7826 (Added in 0.8)
7828 guestfs_mkdtemp
7830 char *
7831 guestfs_mkdtemp (guestfs_h *g,
7832 const char *tmpl);
7833 This command creates a temporary directory. The "tmpl" parameter
7835 should be a full pathname for the temporary directory name with the
7836 final six characters being "XXXXXX".
7837 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
7839 one being suitable for Windows filesystems.
7840 The name of the temporary directory that was created is returned.
7842 The temporary directory is created with mode 0700 and is owned by root.
7844 The caller is responsible for deleting the temporary directory and its
7846 contents after use.
7847 See also: mkdtemp(3)
7849 This function returns a string, or NULL on error. The caller must free
7851 the returned string after use.
7852 (Added in 1.0.54)
7854 guestfs_mke2fs
7856 int
7857 guestfs_mke2fs (guestfs_h *g,
7858 const char *device,
7859 ...);
7860 You may supply a list of optional arguments to this call. Use zero or
7862 more of the following pairs of parameters, and terminate the list with
7863 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7864 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
7866 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
7867 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
7868 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
7869 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
7870 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
7871 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
7872 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
7873 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
7874 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
7875 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
7876 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
7877 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
7878 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
7879 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
7880 GUESTFS_MKE2FS_LABEL, const char *label,
7881 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
7882 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
7883 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
7884 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
7885 GUESTFS_MKE2FS_UUID, const char *uuid,
7886 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
7887 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
7888 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
7889 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
7890 GUESTFS_MKE2FS_TESTFS, int testfs,
7891 GUESTFS_MKE2FS_DISCARD, int discard,
7892 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
7893 GUESTFS_MKE2FS_EXTENT, int extent,
7894 GUESTFS_MKE2FS_FILETYPE, int filetype,
7895 GUESTFS_MKE2FS_FLEXBG, int flexbg,
7896 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
7897 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
7898 GUESTFS_MKE2FS_LARGEFILE, int largefile,
7899 GUESTFS_MKE2FS_QUOTA, int quota,
7900 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
7901 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
7902 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
7903 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
7905 "device".
7906 The optional "blockscount" is the size of the filesystem in blocks. If
7908 omitted it defaults to the size of "device". Note if the filesystem is
7909 too small to contain a journal, "mke2fs" will silently create an ext2
7910 filesystem instead.
7911 This function returns 0 on success or -1 on error.
7913 (Added in 1.19.44)
7915 guestfs_mke2fs_va
7917 int
7918 guestfs_mke2fs_va (guestfs_h *g,
7919 const char *device,
7920 va_list args);
7921 This is the "va_list variant" of "guestfs_mke2fs".
7923 See "CALLS WITH OPTIONAL ARGUMENTS".
7925 guestfs_mke2fs_argv
7927 int
7928 guestfs_mke2fs_argv (guestfs_h *g,
7929 const char *device,
7930 const struct guestfs_mke2fs_argv *optargs);
7931 This is the "argv variant" of "guestfs_mke2fs".
7933 See "CALLS WITH OPTIONAL ARGUMENTS".
7935 guestfs_mke2fs_J
7937 int
7938 guestfs_mke2fs_J (guestfs_h *g,
7939 const char *fstype,
7940 int blocksize,
7941 const char *device,
7942 const char *journal);
7943 This function is deprecated. In new code, use the "guestfs_mke2fs"
7945 call instead.
7946 Deprecated functions will not be removed from the API, but the fact
7948 that they are deprecated indicates that there are problems with correct
7949 use of these functions.
7950 This creates an ext2/3/4 filesystem on "device" with an external
7952 journal on "journal". It is equivalent to the command:
7953 mke2fs -t fstype -b blocksize -J device=<journal> <device>
7955 See also "guestfs_mke2journal".
7957 This function returns 0 on success or -1 on error.
7959 (Added in 1.0.68)
7961 guestfs_mke2fs_JL
7963 int
7964 guestfs_mke2fs_JL (guestfs_h *g,
7965 const char *fstype,
7966 int blocksize,
7967 const char *device,
7968 const char *label);
7969 This function is deprecated. In new code, use the "guestfs_mke2fs"
7971 call instead.
7972 Deprecated functions will not be removed from the API, but the fact
7974 that they are deprecated indicates that there are problems with correct
7975 use of these functions.
7976 This creates an ext2/3/4 filesystem on "device" with an external
7978 journal on the journal labeled "label".
7979 See also "guestfs_mke2journal_L".
7981 This function returns 0 on success or -1 on error.
7983 (Added in 1.0.68)
7985 guestfs_mke2fs_JU
7987 int
7988 guestfs_mke2fs_JU (guestfs_h *g,
7989 const char *fstype,
7990 int blocksize,
7991 const char *device,
7992 const char *uuid);
7993 This function is deprecated. In new code, use the "guestfs_mke2fs"
7995 call instead.
7996 Deprecated functions will not be removed from the API, but the fact
7998 that they are deprecated indicates that there are problems with correct
7999 use of these functions.
8000 This creates an ext2/3/4 filesystem on "device" with an external
8002 journal on the journal with UUID "uuid".
8003 See also "guestfs_mke2journal_U".
8005 This function returns 0 on success or -1 on error.
8007 (Added in 1.0.68)
8009 guestfs_mke2journal
8011 int
8012 guestfs_mke2journal (guestfs_h *g,
8013 int blocksize,
8014 const char *device);
8015 This function is deprecated. In new code, use the "guestfs_mke2fs"
8017 call instead.
8018 Deprecated functions will not be removed from the API, but the fact
8020 that they are deprecated indicates that there are problems with correct
8021 use of these functions.
8022 This creates an ext2 external journal on "device". It is equivalent to
8024 the command:
8025 mke2fs -O journal_dev -b blocksize device
8027 This function returns 0 on success or -1 on error.
8029 (Added in 1.0.68)
8031 guestfs_mke2journal_L
8033 int
8034 guestfs_mke2journal_L (guestfs_h *g,
8035 int blocksize,
8036 const char *label,
8037 const char *device);
8038 This function is deprecated. In new code, use the "guestfs_mke2fs"
8040 call instead.
8041 Deprecated functions will not be removed from the API, but the fact
8043 that they are deprecated indicates that there are problems with correct
8044 use of these functions.
8045 This creates an ext2 external journal on "device" with label "label".
8047 This function returns 0 on success or -1 on error.
8049 (Added in 1.0.68)
8051 guestfs_mke2journal_U
8053 int
8054 guestfs_mke2journal_U (guestfs_h *g,
8055 int blocksize,
8056 const char *uuid,
8057 const char *device);
8058 This function is deprecated. In new code, use the "guestfs_mke2fs"
8060 call instead.
8061 Deprecated functions will not be removed from the API, but the fact
8063 that they are deprecated indicates that there are problems with correct
8064 use of these functions.
8065 This creates an ext2 external journal on "device" with UUID "uuid".
8067 This function returns 0 on success or -1 on error.
8069 (Added in 1.0.68)
8071 guestfs_mkfifo
8073 int
8074 guestfs_mkfifo (guestfs_h *g,
8075 int mode,
8076 const char *path);
8077 This call creates a FIFO (named pipe) called "path" with mode "mode".
8079 It is just a convenient wrapper around "guestfs_mknod".
8080 The mode actually set is affected by the umask.
8082 This function returns 0 on success or -1 on error.
8084 (Added in 1.0.55)
8086 guestfs_mkfs
8088 int
8089 guestfs_mkfs (guestfs_h *g,
8090 const char *fstype,
8091 const char *device);
8092 This function is provided for backwards compatibility with earlier
8094 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
8095 optional arguments.
8096 (Added in 0.8)
8098 guestfs_mkfs_opts
8100 int
8101 guestfs_mkfs_opts (guestfs_h *g,
8102 const char *fstype,
8103 const char *device,
8104 ...);
8105 You may supply a list of optional arguments to this call. Use zero or
8107 more of the following pairs of parameters, and terminate the list with
8108 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8109 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
8111 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
8112 GUESTFS_MKFS_OPTS_INODE, int inode,
8113 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
8114 This function creates a filesystem on "device". The filesystem type is
8116 "fstype", for example "ext3".
8117 The optional arguments are:
8119 "blocksize"
8121 The filesystem block size. Supported block sizes depend on the
8122 filesystem type, but typically they are 1024, 2048 or 4096 for
8123 Linux ext2/3 filesystems.
8124 For VFAT and NTFS the "blocksize" parameter is treated as the
8126 requested cluster size.
8127 For UFS block sizes, please see mkfs.ufs(8).
8129 "features"
8131 This passes the -O parameter to the external mkfs program.
8132 For certain filesystem types, this allows extra filesystem features
8134 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
8135 You cannot use this optional parameter with the "gfs" or "gfs2"
8137 filesystem type.
8138 "inode"
8140 This passes the -I parameter to the external mke2fs(8) program
8141 which sets the inode size (only for ext2/3/4 filesystems at
8142 present).
8143 "sectorsize"
8145 This passes the -S parameter to external mkfs.ufs(8) program, which
8146 sets sector size for ufs filesystem.
8147 This function returns 0 on success or -1 on error.
8149 (Added in 1.7.19)
8151 guestfs_mkfs_opts_va
8153 int
8154 guestfs_mkfs_opts_va (guestfs_h *g,
8155 const char *fstype,
8156 const char *device,
8157 va_list args);
8158 This is the "va_list variant" of "guestfs_mkfs_opts".
8160 See "CALLS WITH OPTIONAL ARGUMENTS".
8162 guestfs_mkfs_opts_argv
8164 int
8165 guestfs_mkfs_opts_argv (guestfs_h *g,
8166 const char *fstype,
8167 const char *device,
8168 const struct guestfs_mkfs_opts_argv *optargs);
8169 This is the "argv variant" of "guestfs_mkfs_opts".
8171 See "CALLS WITH OPTIONAL ARGUMENTS".
8173 guestfs_mkfs_b
8175 int
8176 guestfs_mkfs_b (guestfs_h *g,
8177 const char *fstype,
8178 int blocksize,
8179 const char *device);
8180 This function is deprecated. In new code, use the "guestfs_mkfs" call
8182 instead.
8183 Deprecated functions will not be removed from the API, but the fact
8185 that they are deprecated indicates that there are problems with correct
8186 use of these functions.
8187 This call is similar to "guestfs_mkfs", but it allows you to control
8189 the block size of the resulting filesystem. Supported block sizes
8190 depend on the filesystem type, but typically they are 1024, 2048 or
8191 4096 only.
8192 For VFAT and NTFS the "blocksize" parameter is treated as the requested
8194 cluster size.
8195 This function returns 0 on success or -1 on error.
8197 (Added in 1.0.68)
8199 guestfs_mkfs_btrfs
8201 int
8202 guestfs_mkfs_btrfs (guestfs_h *g,
8203 char *const *devices,
8204 ...);
8205 You may supply a list of optional arguments to this call. Use zero or
8207 more of the following pairs of parameters, and terminate the list with
8208 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8209 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
8211 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
8212 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
8213 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
8214 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
8215 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
8216 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
8217 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
8218 Create a btrfs filesystem, allowing all configurables to be set. For
8220 more information on the optional arguments, see mkfs.btrfs(8).
8221 Since btrfs filesystems can span multiple devices, this takes a non-
8223 empty list of devices.
8224 To create general filesystems, use "guestfs_mkfs".
8226 This function returns 0 on success or -1 on error.
8228 (Added in 1.17.25)
8230 guestfs_mkfs_btrfs_va
8232 int
8233 guestfs_mkfs_btrfs_va (guestfs_h *g,
8234 char *const *devices,
8235 va_list args);
8236 This is the "va_list variant" of "guestfs_mkfs_btrfs".
8238 See "CALLS WITH OPTIONAL ARGUMENTS".
8240 guestfs_mkfs_btrfs_argv
8242 int
8243 guestfs_mkfs_btrfs_argv (guestfs_h *g,
8244 char *const *devices,
8245 const struct guestfs_mkfs_btrfs_argv *optargs);
8246 This is the "argv variant" of "guestfs_mkfs_btrfs".
8248 See "CALLS WITH OPTIONAL ARGUMENTS".
8250 guestfs_mklost_and_found
8252 int
8253 guestfs_mklost_and_found (guestfs_h *g,
8254 const char *mountpoint);
8255 Make the "lost+found" directory, normally in the root directory of an
8257 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
8258 to create the "lost+found" directory.
8259 This function returns 0 on success or -1 on error.
8261 (Added in 1.19.56)
8263 guestfs_mkmountpoint
8265 int
8266 guestfs_mkmountpoint (guestfs_h *g,
8267 const char *exemptpath);
8268 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
8270 that can be used to create extra mountpoints before mounting the first
8271 filesystem.
8272 These calls are only necessary in some very limited circumstances,
8274 mainly the case where you want to mount a mix of unrelated and/or read-
8275 only filesystems together.
8276 For example, live CDs often contain a "Russian doll" nest of
8278 filesystems, an ISO outer layer, with a squashfs image inside, with an
8279 ext2/3 image inside that. You can unpack this as follows in guestfish:
8280 add-ro Fedora-11-i686-Live.iso
8282 run
8283 mkmountpoint /cd
8284 mkmountpoint /sqsh
8285 mkmountpoint /ext3fs
8286 mount /dev/sda /cd
8287 mount-loop /cd/LiveOS/squashfs.img /sqsh
8288 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
8289 The inner filesystem is now unpacked under the /ext3fs mountpoint.
8291 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
8293 You may get unexpected errors if you try to mix these calls. It is
8294 safest to manually unmount filesystems and remove mountpoints after
8295 use.
8296 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
8298 first, so for this to work for manual mountpoints, you must ensure that
8299 the innermost mountpoints have the longest pathnames, as in the example
8300 code above.
8301 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
8303 Autosync [see "guestfs_set_autosync", this is set by default on
8305 handles] can cause "guestfs_umount_all" to be called when the handle is
8306 closed which can also trigger these issues.
8307 This function returns 0 on success or -1 on error.
8309 (Added in 1.0.62)
8311 guestfs_mknod
8313 int
8314 guestfs_mknod (guestfs_h *g,
8315 int mode,
8316 int devmajor,
8317 int devminor,
8318 const char *path);
8319 This call creates block or character special devices, or named pipes
8321 (FIFOs).
8322 The "mode" parameter should be the mode, using the standard constants.
8324 "devmajor" and "devminor" are the device major and minor numbers, only
8325 used when creating block and character special devices.
8326 Note that, just like mknod(2), the mode must be bitwise OR'd with
8328 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
8329 a regular file). These constants are available in the standard Linux
8330 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
8331 "guestfs_mkfifo" which are wrappers around this command which bitwise
8332 OR in the appropriate constant for you.
8333 The mode actually set is affected by the umask.
8335 This function returns 0 on success or -1 on error.
8337 (Added in 1.0.55)
8339 guestfs_mknod_b
8341 int
8342 guestfs_mknod_b (guestfs_h *g,
8343 int mode,
8344 int devmajor,
8345 int devminor,
8346 const char *path);
8347 This call creates a block device node called "path" with mode "mode"
8349 and device major/minor "devmajor" and "devminor". It is just a
8350 convenient wrapper around "guestfs_mknod".
8351 The mode actually set is affected by the umask.
8353 This function returns 0 on success or -1 on error.
8355 (Added in 1.0.55)
8357 guestfs_mknod_c
8359 int
8360 guestfs_mknod_c (guestfs_h *g,
8361 int mode,
8362 int devmajor,
8363 int devminor,
8364 const char *path);
8365 This call creates a char device node called "path" with mode "mode" and
8367 device major/minor "devmajor" and "devminor". It is just a convenient
8368 wrapper around "guestfs_mknod".
8369 The mode actually set is affected by the umask.
8371 This function returns 0 on success or -1 on error.
8373 (Added in 1.0.55)
8375 guestfs_mkswap
8377 int
8378 guestfs_mkswap (guestfs_h *g,
8379 const char *device);
8380 This function is provided for backwards compatibility with earlier
8382 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
8383 optional arguments.
8384 (Added in 1.0.55)
8386 guestfs_mkswap_opts
8388 int
8389 guestfs_mkswap_opts (guestfs_h *g,
8390 const char *device,
8391 ...);
8392 You may supply a list of optional arguments to this call. Use zero or
8394 more of the following pairs of parameters, and terminate the list with
8395 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8396 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
8398 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
8399 Create a Linux swap partition on "device".
8401 The option arguments "label" and "uuid" allow you to set the label
8403 and/or UUID of the new swap partition.
8404 This function returns 0 on success or -1 on error.
8406 (Added in 1.19.34)
8408 guestfs_mkswap_opts_va
8410 int
8411 guestfs_mkswap_opts_va (guestfs_h *g,
8412 const char *device,
8413 va_list args);
8414 This is the "va_list variant" of "guestfs_mkswap_opts".
8416 See "CALLS WITH OPTIONAL ARGUMENTS".
8418 guestfs_mkswap_opts_argv
8420 int
8421 guestfs_mkswap_opts_argv (guestfs_h *g,
8422 const char *device,
8423 const struct guestfs_mkswap_opts_argv *optargs);
8424 This is the "argv variant" of "guestfs_mkswap_opts".
8426 See "CALLS WITH OPTIONAL ARGUMENTS".
8428 guestfs_mkswap_L
8430 int
8431 guestfs_mkswap_L (guestfs_h *g,
8432 const char *label,
8433 const char *device);
8434 This function is deprecated. In new code, use the "guestfs_mkswap"
8436 call instead.
8437 Deprecated functions will not be removed from the API, but the fact
8439 that they are deprecated indicates that there are problems with correct
8440 use of these functions.
8441 Create a swap partition on "device" with label "label".
8443 Note that you cannot attach a swap label to a block device (eg.
8445 "/dev/sda"), just to a partition. This appears to be a limitation of
8446 the kernel or swap tools.
8447 This function returns 0 on success or -1 on error.
8449 (Added in 1.0.55)
8451 guestfs_mkswap_U
8453 int
8454 guestfs_mkswap_U (guestfs_h *g,
8455 const char *uuid,
8456 const char *device);
8457 This function is deprecated. In new code, use the "guestfs_mkswap"
8459 call instead.
8460 Deprecated functions will not be removed from the API, but the fact
8462 that they are deprecated indicates that there are problems with correct
8463 use of these functions.
8464 Create a swap partition on "device" with UUID "uuid".
8466 This function returns 0 on success or -1 on error.
8468 (Added in 1.0.55)
8470 guestfs_mkswap_file
8472 int
8473 guestfs_mkswap_file (guestfs_h *g,
8474 const char *path);
8475 Create a swap file.
8477 This command just writes a swap file signature to an existing file. To
8479 create the file itself, use something like "guestfs_fallocate".
8480 This function returns 0 on success or -1 on error.
8482 (Added in 1.0.66)
8484 guestfs_mktemp
8486 char *
8487 guestfs_mktemp (guestfs_h *g,
8488 const char *tmpl,
8489 ...);
8490 You may supply a list of optional arguments to this call. Use zero or
8492 more of the following pairs of parameters, and terminate the list with
8493 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8494 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
8496 This command creates a temporary file. The "tmpl" parameter should be
8498 a full pathname for the temporary directory name with the final six
8499 characters being "XXXXXX".
8500 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
8502 one being suitable for Windows filesystems.
8503 The name of the temporary file that was created is returned.
8505 The temporary file is created with mode 0600 and is owned by root.
8507 The caller is responsible for deleting the temporary file after use.
8509 If the optional "suffix" parameter is given, then the suffix (eg.
8511 ".txt") is appended to the temporary name.
8512 See also: "guestfs_mkdtemp".
8514 This function returns a string, or NULL on error. The caller must free
8516 the returned string after use.
8517 (Added in 1.19.53)
8519 guestfs_mktemp_va
8521 char *
8522 guestfs_mktemp_va (guestfs_h *g,
8523 const char *tmpl,
8524 va_list args);
8525 This is the "va_list variant" of "guestfs_mktemp".
8527 See "CALLS WITH OPTIONAL ARGUMENTS".
8529 guestfs_mktemp_argv
8531 char *
8532 guestfs_mktemp_argv (guestfs_h *g,
8533 const char *tmpl,
8534 const struct guestfs_mktemp_argv *optargs);
8535 This is the "argv variant" of "guestfs_mktemp".
8537 See "CALLS WITH OPTIONAL ARGUMENTS".
8539 guestfs_modprobe
8541 int
8542 guestfs_modprobe (guestfs_h *g,
8543 const char *modulename);
8544 This loads a kernel module in the appliance.
8546 The kernel module must have been whitelisted when libguestfs was built
8548 (see "appliance/kmod.whitelist.in" in the source).
8549 This function returns 0 on success or -1 on error.
8551 (Added in 1.0.68)
8553 guestfs_mount
8555 int
8556 guestfs_mount (guestfs_h *g,
8557 const char *device,
8558 const char *mountpoint);
8559 Mount a guest disk at a position in the filesystem. Block devices are
8561 named "/dev/sda", "/dev/sdb" and so on, as they were added to the
8562 guest. If those block devices contain partitions, they will have the
8563 usual names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style names can
8564 be used.
8565 The rules are the same as for mount(2): A filesystem must first be
8567 mounted on "/" before others can be mounted. Other filesystems can
8568 only be mounted on directories which already exist.
8569 The mounted filesystem is writable, if we have sufficient permissions
8571 on the underlying device.
8572 Before libguestfs 1.13.16, this call implicitly added the options
8574 "sync" and "noatime". The "sync" option greatly slowed writes and
8575 caused many problems for users. If your program might need to work
8576 with older versions of libguestfs, use "guestfs_mount_options" instead
8577 (using an empty string for the first parameter if you don't want any
8578 options).
8579 This function returns 0 on success or -1 on error.
8581 (Added in 0.3)
8583 guestfs_mount_local
8585 int
8586 guestfs_mount_local (guestfs_h *g,
8587 const char *localmountpoint,
8588 ...);
8589 You may supply a list of optional arguments to this call. Use zero or
8591 more of the following pairs of parameters, and terminate the list with
8592 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8593 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
8595 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
8596 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
8597 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
8598 This call exports the libguestfs-accessible filesystem to a local
8600 mountpoint (directory) called "localmountpoint". Ordinary reads and
8601 writes to files and directories under "localmountpoint" are redirected
8602 through libguestfs.
8603 If the optional "readonly" flag is set to true, then writes to the
8605 filesystem return error "EROFS".
8606 "options" is a comma-separated list of mount options. See
8608 guestmount(1) for some useful options.
8609 "cachetimeout" sets the timeout (in seconds) for cached directory
8611 entries. The default is 60 seconds. See guestmount(1) for further
8612 information.
8613 If "debugcalls" is set to true, then additional debugging information
8615 is generated for every FUSE call.
8616 When "guestfs_mount_local" returns, the filesystem is ready, but is not
8618 processing requests (access to it will block). You have to call
8619 "guestfs_mount_local_run" to run the main loop.
8620 See "MOUNT LOCAL" in guestfs(3) for full documentation.
8622 This function returns 0 on success or -1 on error.
8624 (Added in 1.17.22)
8626 guestfs_mount_local_va
8628 int
8629 guestfs_mount_local_va (guestfs_h *g,
8630 const char *localmountpoint,
8631 va_list args);
8632 This is the "va_list variant" of "guestfs_mount_local".
8634 See "CALLS WITH OPTIONAL ARGUMENTS".
8636 guestfs_mount_local_argv
8638 int
8639 guestfs_mount_local_argv (guestfs_h *g,
8640 const char *localmountpoint,
8641 const struct guestfs_mount_local_argv *optargs);
8642 This is the "argv variant" of "guestfs_mount_local".
8644 See "CALLS WITH OPTIONAL ARGUMENTS".
8646 guestfs_mount_local_run
8648 int
8649 guestfs_mount_local_run (guestfs_h *g);
8650 Run the main loop which translates kernel calls to libguestfs calls.
8652 This should only be called after "guestfs_mount_local" returns
8654 successfully. The call will not return until the filesystem is
8655 unmounted.
8656 Note you must not make concurrent libguestfs calls on the same handle
8658 from another thread.
8659 You may call this from a different thread than the one which called
8661 "guestfs_mount_local", subject to the usual rules for threads and
8662 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in guestfs(3)).
8663 See "MOUNT LOCAL" in guestfs(3) for full documentation.
8665 This function returns 0 on success or -1 on error.
8667 (Added in 1.17.22)
8669 guestfs_mount_loop
8671 int
8672 guestfs_mount_loop (guestfs_h *g,
8673 const char *file,
8674 const char *mountpoint);
8675 This command lets you mount "file" (a filesystem image in a file) on a
8677 mount point. It is entirely equivalent to the command "mount -o loop
8678 file mountpoint".
8679 This function returns 0 on success or -1 on error.
8681 (Added in 1.0.54)
8683 guestfs_mount_options
8685 int
8686 guestfs_mount_options (guestfs_h *g,
8687 const char *options,
8688 const char *device,
8689 const char *mountpoint);
8690 This is the same as the "guestfs_mount" command, but it allows you to
8692 set the mount options as for the mount(8) -o flag.
8693 If the "options" parameter is an empty string, then no options are
8695 passed (all options default to whatever the filesystem uses).
8696 This function returns 0 on success or -1 on error.
8698 (Added in 1.0.10)
8700 guestfs_mount_ro
8702 int
8703 guestfs_mount_ro (guestfs_h *g,
8704 const char *device,
8705 const char *mountpoint);
8706 This is the same as the "guestfs_mount" command, but it mounts the
8708 filesystem with the read-only (-o ro) flag.
8709 This function returns 0 on success or -1 on error.
8711 (Added in 1.0.10)
8713 guestfs_mount_vfs
8715 int
8716 guestfs_mount_vfs (guestfs_h *g,
8717 const char *options,
8718 const char *vfstype,
8719 const char *device,
8720 const char *mountpoint);
8721 This is the same as the "guestfs_mount" command, but it allows you to
8723 set both the mount options and the vfstype as for the mount(8) -o and
8724 -t flags.
8725 This function returns 0 on success or -1 on error.
8727 (Added in 1.0.10)
8729 guestfs_mountpoints
8731 char **
8732 guestfs_mountpoints (guestfs_h *g);
8733 This call is similar to "guestfs_mounts". That call returns a list of
8735 devices. This one returns a hash table (map) of device name to
8736 directory where the device is mounted.
8737 This function returns a NULL-terminated array of strings, or NULL if
8739 there was an error. The array of strings will always have length
8740 "2n+1", where "n" keys and values alternate, followed by the trailing
8741 NULL entry. The caller must free the strings and the array after use.
8742 (Added in 1.0.62)
8744 guestfs_mounts
8746 char **
8747 guestfs_mounts (guestfs_h *g);
8748 This returns the list of currently mounted filesystems. It returns the
8750 list of devices (eg. "/dev/sda1", "/dev/VG/LV").
8751 Some internal mounts are not shown.
8753 See also: "guestfs_mountpoints"
8755 This function returns a NULL-terminated array of strings (like
8757 environ(3)), or NULL if there was an error. The caller must free the
8758 strings and the array after use.
8759 (Added in 0.8)
8761 guestfs_mv
8763 int
8764 guestfs_mv (guestfs_h *g,
8765 const char *src,
8766 const char *dest);
8767 This moves a file from "src" to "dest" where "dest" is either a
8769 destination filename or destination directory.
8770 See also: "guestfs_rename".
8772 This function returns 0 on success or -1 on error.
8774 (Added in 1.0.18)
8776 guestfs_nr_devices
8778 int
8779 guestfs_nr_devices (guestfs_h *g);
8780 This returns the number of whole block devices that were added. This
8782 is the same as the number of devices that would be returned if you
8783 called "guestfs_list_devices".
8784 To find out the maximum number of devices that could be added, call
8786 "guestfs_max_disks".
8787 On error this function returns -1.
8789 (Added in 1.19.15)
8791 guestfs_ntfs_3g_probe
8793 int
8794 guestfs_ntfs_3g_probe (guestfs_h *g,
8795 int rw,
8796 const char *device);
8797 This command runs the ntfs-3g.probe(8) command which probes an NTFS
8799 "device" for mountability. (Not all NTFS volumes can be mounted read-
8800 write, and some cannot be mounted at all).
8801 "rw" is a boolean flag. Set it to true if you want to test if the
8803 volume can be mounted read-write. Set it to false if you want to test
8804 if the volume can be mounted read-only.
8805 The return value is an integer which 0 if the operation would succeed,
8807 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
8808 On error this function returns -1.
8810 (Added in 1.0.43)
8812 guestfs_ntfsclone_in
8814 int
8815 guestfs_ntfsclone_in (guestfs_h *g,
8816 const char *backupfile,
8817 const char *device);
8818 Restore the "backupfile" (from a previous call to
8820 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
8821 of this device.
8822 This function returns 0 on success or -1 on error.
8824 (Added in 1.17.9)
8826 guestfs_ntfsclone_out
8828 int
8829 guestfs_ntfsclone_out (guestfs_h *g,
8830 const char *device,
8831 const char *backupfile,
8832 ...);
8833 You may supply a list of optional arguments to this call. Use zero or
8835 more of the following pairs of parameters, and terminate the list with
8836 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8837 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
8839 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
8840 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
8841 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
8842 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
8843 Stream the NTFS filesystem "device" to the local file "backupfile".
8845 The format used for the backup file is a special format used by the
8846 ntfsclone(8) tool.
8847 If the optional "metadataonly" flag is true, then only the metadata is
8849 saved, losing all the user data (this is useful for diagnosing some
8850 filesystem problems).
8851 The optional "rescue", "ignorefscheck", "preservetimestamps" and
8853 "force" flags have precise meanings detailed in the ntfsclone(8) man
8854 page.
8855 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
8857 device.
8858 This function returns 0 on success or -1 on error.
8860 (Added in 1.17.9)
8862 guestfs_ntfsclone_out_va
8864 int
8865 guestfs_ntfsclone_out_va (guestfs_h *g,
8866 const char *device,
8867 const char *backupfile,
8868 va_list args);
8869 This is the "va_list variant" of "guestfs_ntfsclone_out".
8871 See "CALLS WITH OPTIONAL ARGUMENTS".
8873 guestfs_ntfsclone_out_argv
8875 int
8876 guestfs_ntfsclone_out_argv (guestfs_h *g,
8877 const char *device,
8878 const char *backupfile,
8879 const struct guestfs_ntfsclone_out_argv *optargs);
8880 This is the "argv variant" of "guestfs_ntfsclone_out".
8882 See "CALLS WITH OPTIONAL ARGUMENTS".
8884 guestfs_ntfsfix
8886 int
8887 guestfs_ntfsfix (guestfs_h *g,
8888 const char *device,
8889 ...);
8890 You may supply a list of optional arguments to this call. Use zero or
8892 more of the following pairs of parameters, and terminate the list with
8893 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8894 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
8896 This command repairs some fundamental NTFS inconsistencies, resets the
8898 NTFS journal file, and schedules an NTFS consistency check for the
8899 first boot into Windows.
8900 This is not an equivalent of Windows "chkdsk". It does not scan the
8902 filesystem for inconsistencies.
8903 The optional "clearbadsectors" flag clears the list of bad sectors.
8905 This is useful after cloning a disk with bad sectors to a new disk.
8906 This function returns 0 on success or -1 on error.
8908 (Added in 1.17.9)
8910 guestfs_ntfsfix_va
8912 int
8913 guestfs_ntfsfix_va (guestfs_h *g,
8914 const char *device,
8915 va_list args);
8916 This is the "va_list variant" of "guestfs_ntfsfix".
8918 See "CALLS WITH OPTIONAL ARGUMENTS".
8920 guestfs_ntfsfix_argv
8922 int
8923 guestfs_ntfsfix_argv (guestfs_h *g,
8924 const char *device,
8925 const struct guestfs_ntfsfix_argv *optargs);
8926 This is the "argv variant" of "guestfs_ntfsfix".
8928 See "CALLS WITH OPTIONAL ARGUMENTS".
8930 guestfs_ntfsresize
8932 int
8933 guestfs_ntfsresize (guestfs_h *g,
8934 const char *device);
8935 This function is provided for backwards compatibility with earlier
8937 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
8938 no optional arguments.
8939 (Added in 1.3.2)
8941 guestfs_ntfsresize_opts
8943 int
8944 guestfs_ntfsresize_opts (guestfs_h *g,
8945 const char *device,
8946 ...);
8947 You may supply a list of optional arguments to this call. Use zero or
8949 more of the following pairs of parameters, and terminate the list with
8950 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8951 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
8953 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
8954 This command resizes an NTFS filesystem, expanding or shrinking it to
8956 the size of the underlying device.
8957 The optional parameters are:
8959 "size"
8961 The new size (in bytes) of the filesystem. If omitted, the
8962 filesystem is resized to fit the container (eg. partition).
8963 "force"
8965 If this option is true, then force the resize of the filesystem
8966 even if the filesystem is marked as requiring a consistency check.
8967 After the resize operation, the filesystem is always marked as
8969 requiring a consistency check (for safety). You have to boot into
8970 Windows to perform this check and clear this condition. If you
8971 don't set the "force" option then it is not possible to call
8972 "guestfs_ntfsresize" multiple times on a single filesystem without
8973 booting into Windows between each resize.
8974 See also ntfsresize(8).
8976 This function returns 0 on success or -1 on error.
8978 (Added in 1.11.15)
8980 guestfs_ntfsresize_opts_va
8982 int
8983 guestfs_ntfsresize_opts_va (guestfs_h *g,
8984 const char *device,
8985 va_list args);
8986 This is the "va_list variant" of "guestfs_ntfsresize_opts".
8988 See "CALLS WITH OPTIONAL ARGUMENTS".
8990 guestfs_ntfsresize_opts_argv
8992 int
8993 guestfs_ntfsresize_opts_argv (guestfs_h *g,
8994 const char *device,
8995 const struct guestfs_ntfsresize_opts_argv *optargs);
8996 This is the "argv variant" of "guestfs_ntfsresize_opts".
8998 See "CALLS WITH OPTIONAL ARGUMENTS".
9000 guestfs_ntfsresize_size
9002 int
9003 guestfs_ntfsresize_size (guestfs_h *g,
9004 const char *device,
9005 int64_t size);
9006 This function is deprecated. In new code, use the "guestfs_ntfsresize"
9008 call instead.
9009 Deprecated functions will not be removed from the API, but the fact
9011 that they are deprecated indicates that there are problems with correct
9012 use of these functions.
9013 This command is the same as "guestfs_ntfsresize" except that it allows
9015 you to specify the new size (in bytes) explicitly.
9016 This function returns 0 on success or -1 on error.
9018 (Added in 1.3.14)
9020 guestfs_parse_environment
9022 int
9023 guestfs_parse_environment (guestfs_h *g);
9024 Parse the program's environment and set flags in the handle
9026 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the 'verbose'
9027 flag is set in the handle.
9028 Most programs do not need to call this. It is done implicitly when you
9030 call "guestfs_create".
9031 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
9033 variables that can affect libguestfs handles. See also
9034 "guestfs_create_flags" in guestfs(3), and
9035 "guestfs_parse_environment_list".
9036 This function returns 0 on success or -1 on error.
9038 (Added in 1.19.53)
9040 guestfs_parse_environment_list
9042 int
9043 guestfs_parse_environment_list (guestfs_h *g,
9044 char *const *environment);
9045 Parse the list of strings in the argument "environment" and set flags
9047 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
9048 string in the list, then the 'verbose' flag is set in the handle.
9049 This is the same as "guestfs_parse_environment" except that it parses
9051 an explicit list of strings instead of the program's environment.
9052 This function returns 0 on success or -1 on error.
9054 (Added in 1.19.53)
9056 guestfs_part_add
9058 int
9059 guestfs_part_add (guestfs_h *g,
9060 const char *device,
9061 const char *prlogex,
9062 int64_t startsect,
9063 int64_t endsect);
9064 This command adds a partition to "device". If there is no partition
9066 table on the device, call "guestfs_part_init" first.
9067 The "prlogex" parameter is the type of partition. Normally you should
9069 pass "p" or "primary" here, but MBR partition tables also support "l"
9070 (or "logical") and "e" (or "extended") partition types.
9071 "startsect" and "endsect" are the start and end of the partition in
9073 sectors. "endsect" may be negative, which means it counts backwards
9074 from the end of the disk ("-1" is the last sector).
9075 Creating a partition which covers the whole disk is not so easy. Use
9077 "guestfs_part_disk" to do that.
9078 This function returns 0 on success or -1 on error.
9080 (Added in 1.0.78)
9082 guestfs_part_del
9084 int
9085 guestfs_part_del (guestfs_h *g,
9086 const char *device,
9087 int partnum);
9088 This command deletes the partition numbered "partnum" on "device".
9090 Note that in the case of MBR partitioning, deleting an extended
9092 partition also deletes any logical partitions it contains.
9093 This function returns 0 on success or -1 on error.
9095 (Added in 1.3.2)
9097 guestfs_part_disk
9099 int
9100 guestfs_part_disk (guestfs_h *g,
9101 const char *device,
9102 const char *parttype);
9103 This command is simply a combination of "guestfs_part_init" followed by
9105 "guestfs_part_add" to create a single primary partition covering the
9106 whole disk.
9107 "parttype" is the partition table type, usually "mbr" or "gpt", but
9109 other possible values are described in "guestfs_part_init".
9110 This function returns 0 on success or -1 on error.
9112 (Added in 1.0.78)
9114 guestfs_part_get_bootable
9116 int
9117 guestfs_part_get_bootable (guestfs_h *g,
9118 const char *device,
9119 int partnum);
9120 This command returns true if the partition "partnum" on "device" has
9122 the bootable flag set.
9123 See also "guestfs_part_set_bootable".
9125 This function returns a C truth value on success or -1 on error.
9127 (Added in 1.3.2)
9129 guestfs_part_get_gpt_type
9131 char *
9132 guestfs_part_get_gpt_type (guestfs_h *g,
9133 const char *device,
9134 int partnum);
9135 Return the type GUID of numbered GPT partition "partnum". For MBR
9137 partitions, return an appropriate GUID corresponding to the MBR type.
9138 Behaviour is undefined for other partition types.
9139 This function returns a string, or NULL on error. The caller must free
9141 the returned string after use.
9142 guestfs_part_get_mbr_id
9144 int
9145 guestfs_part_get_mbr_id (guestfs_h *g,
9146 const char *device,
9147 int partnum);
9148 Returns the MBR type byte (also known as the ID byte) from the numbered
9150 partition "partnum".
9151 Note that only MBR (old DOS-style) partitions have type bytes. You
9153 will get undefined results for other partition table types (see
9154 "guestfs_part_get_parttype").
9155 On error this function returns -1.
9157 (Added in 1.3.2)
9159 guestfs_part_get_parttype
9161 char *
9162 guestfs_part_get_parttype (guestfs_h *g,
9163 const char *device);
9164 This command examines the partition table on "device" and returns the
9166 partition table type (format) being used.
9167 Common return values include: "msdos" (a DOS/Windows style MBR
9169 partition table), "gpt" (a GPT/EFI-style partition table). Other
9170 values are possible, although unusual. See "guestfs_part_init" for a
9171 full list.
9172 This function returns a string, or NULL on error. The caller must free
9174 the returned string after use.
9175 (Added in 1.0.78)
9177 guestfs_part_init
9179 int
9180 guestfs_part_init (guestfs_h *g,
9181 const char *device,
9182 const char *parttype);
9183 This creates an empty partition table on "device" of one of the
9185 partition types listed below. Usually "parttype" should be either
9186 "msdos" or "gpt" (for large disks).
9187 Initially there are no partitions. Following this, you should call
9189 "guestfs_part_add" for each partition required.
9190 Possible values for "parttype" are:
9192 efi
9194 gpt Intel EFI / GPT partition table.
9195 This is recommended for >= 2 TB partitions that will be accessed
9197 from Linux and Intel-based Mac OS X. It also has limited backwards
9198 compatibility with the "mbr" format.
9199 mbr
9201 msdos
9202 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
9203 and Windows. This partition type will only work for device sizes
9204 up to 2 TB. For large disks we recommend using "gpt".
9205 Other partition table types that may work but are not supported
9207 include:
9208 aix AIX disk labels.
9210 amiga
9212 rdb Amiga "Rigid Disk Block" format.
9213 bsd BSD disk labels.
9215 dasd
9217 DASD, used on IBM mainframes.
9218 dvh MIPS/SGI volumes.
9220 mac Old Mac partition format. Modern Macs use "gpt".
9222 pc98
9224 NEC PC-98 format, common in Japan apparently.
9225 sun Sun disk labels.
9227 This function returns 0 on success or -1 on error.
9229 (Added in 1.0.78)
9231 guestfs_part_list
9233 struct guestfs_partition_list *
9234 guestfs_part_list (guestfs_h *g,
9235 const char *device);
9236 This command parses the partition table on "device" and returns the
9238 list of partitions found.
9239 The fields in the returned structure are:
9241 part_num
9243 Partition number, counting from 1.
9244 part_start
9246 Start of the partition in bytes. To get sectors you have to divide
9247 by the device's sector size, see "guestfs_blockdev_getss".
9248 part_end
9250 End of the partition in bytes.
9251 part_size
9253 Size of the partition in bytes.
9254 This function returns a "struct guestfs_partition_list *", or NULL if
9256 there was an error. The caller must call "guestfs_free_partition_list"
9257 after use.
9258 (Added in 1.0.78)
9260 guestfs_part_set_bootable
9262 int
9263 guestfs_part_set_bootable (guestfs_h *g,
9264 const char *device,
9265 int partnum,
9266 int bootable);
9267 This sets the bootable flag on partition numbered "partnum" on device
9269 "device". Note that partitions are numbered from 1.
9270 The bootable flag is used by some operating systems (notably Windows)
9272 to determine which partition to boot from. It is by no means
9273 universally recognized.
9274 This function returns 0 on success or -1 on error.
9276 (Added in 1.0.78)
9278 guestfs_part_set_gpt_type
9280 int
9281 guestfs_part_set_gpt_type (guestfs_h *g,
9282 const char *device,
9283 int partnum,
9284 const char *guid);
9285 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
9287 an error if the partition table of "device" isn't GPT, or if "guid" is
9288 not a valid GUID.
9289 See
9291 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
9292 for a useful list of type GUIDs.
9293 This function returns 0 on success or -1 on error.
9295 guestfs_part_set_mbr_id
9297 int
9298 guestfs_part_set_mbr_id (guestfs_h *g,
9299 const char *device,
9300 int partnum,
9301 int idbyte);
9302 Sets the MBR type byte (also known as the ID byte) of the numbered
9304 partition "partnum" to "idbyte". Note that the type bytes quoted in
9305 most documentation are in fact hexadecimal numbers, but usually
9306 documented without any leading "0x" which might be confusing.
9307 Note that only MBR (old DOS-style) partitions have type bytes. You
9309 will get undefined results for other partition table types (see
9310 "guestfs_part_get_parttype").
9311 This function returns 0 on success or -1 on error.
9313 (Added in 1.3.2)
9315 guestfs_part_set_name
9317 int
9318 guestfs_part_set_name (guestfs_h *g,
9319 const char *device,
9320 int partnum,
9321 const char *name);
9322 This sets the partition name on partition numbered "partnum" on device
9324 "device". Note that partitions are numbered from 1.
9325 The partition name can only be set on certain types of partition table.
9327 This works on "gpt" but not on "mbr" partitions.
9328 This function returns 0 on success or -1 on error.
9330 (Added in 1.0.78)
9332 guestfs_part_to_dev
9334 char *
9335 guestfs_part_to_dev (guestfs_h *g,
9336 const char *partition);
9337 This function takes a partition name (eg. "/dev/sdb1") and removes the
9339 partition number, returning the device name (eg. "/dev/sdb").
9340 The named partition must exist, for example as a string returned from
9342 "guestfs_list_partitions".
9343 See also "guestfs_part_to_partnum", "guestfs_device_index".
9345 This function returns a string, or NULL on error. The caller must free
9347 the returned string after use.
9348 (Added in 1.5.15)
9350 guestfs_part_to_partnum
9352 int
9353 guestfs_part_to_partnum (guestfs_h *g,
9354 const char *partition);
9355 This function takes a partition name (eg. "/dev/sdb1") and returns the
9357 partition number (eg. 1).
9358 The named partition must exist, for example as a string returned from
9360 "guestfs_list_partitions".
9361 See also "guestfs_part_to_dev".
9363 On error this function returns -1.
9365 (Added in 1.13.25)
9367 guestfs_ping_daemon
9369 int
9370 guestfs_ping_daemon (guestfs_h *g);
9371 This is a test probe into the guestfs daemon running inside the qemu
9373 subprocess. Calling this function checks that the daemon responds to
9374 the ping message, without affecting the daemon or attached block
9375 device(s) in any other way.
9376 This function returns 0 on success or -1 on error.
9378 (Added in 1.0.18)
9380 guestfs_pread
9382 char *
9383 guestfs_pread (guestfs_h *g,
9384 const char *path,
9385 int count,
9386 int64_t offset,
9387 size_t *size_r);
9388 This command lets you read part of a file. It reads "count" bytes of
9390 the file, starting at "offset", from file "path".
9391 This may read fewer bytes than requested. For further details see the
9393 pread(2) system call.
9394 See also "guestfs_pwrite", "guestfs_pread_device".
9396 This function returns a buffer, or NULL on error. The size of the
9398 returned buffer is written to *size_r. The caller must free the
9399 returned buffer after use.
9400 Because of the message protocol, there is a transfer limit of somewhere
9402 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9403 (Added in 1.0.77)
9405 guestfs_pread_device
9407 char *
9408 guestfs_pread_device (guestfs_h *g,
9409 const char *device,
9410 int count,
9411 int64_t offset,
9412 size_t *size_r);
9413 This command lets you read part of a block device. It reads "count"
9415 bytes of "device", starting at "offset".
9416 This may read fewer bytes than requested. For further details see the
9418 pread(2) system call.
9419 See also "guestfs_pread".
9421 This function returns a buffer, or NULL on error. The size of the
9423 returned buffer is written to *size_r. The caller must free the
9424 returned buffer after use.
9425 Because of the message protocol, there is a transfer limit of somewhere
9427 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9428 (Added in 1.5.21)
9430 guestfs_pvchange_uuid
9432 int
9433 guestfs_pvchange_uuid (guestfs_h *g,
9434 const char *device);
9435 Generate a new random UUID for the physical volume "device".
9437 This function returns 0 on success or -1 on error.
9439 (Added in 1.19.26)
9441 guestfs_pvchange_uuid_all
9443 int
9444 guestfs_pvchange_uuid_all (guestfs_h *g);
9445 Generate new random UUIDs for all physical volumes.
9447 This function returns 0 on success or -1 on error.
9449 (Added in 1.19.26)
9451 guestfs_pvcreate
9453 int
9454 guestfs_pvcreate (guestfs_h *g,
9455 const char *device);
9456 This creates an LVM physical volume on the named "device", where
9458 "device" should usually be a partition name such as "/dev/sda1".
9459 This function returns 0 on success or -1 on error.
9461 (Added in 0.8)
9463 guestfs_pvremove
9465 int
9466 guestfs_pvremove (guestfs_h *g,
9467 const char *device);
9468 This wipes a physical volume "device" so that LVM will no longer
9470 recognise it.
9471 The implementation uses the "pvremove" command which refuses to wipe
9473 physical volumes that contain any volume groups, so you have to remove
9474 those first.
9475 This function returns 0 on success or -1 on error.
9477 (Added in 1.0.13)
9479 guestfs_pvresize
9481 int
9482 guestfs_pvresize (guestfs_h *g,
9483 const char *device);
9484 This resizes (expands or shrinks) an existing LVM physical volume to
9486 match the new size of the underlying device.
9487 This function returns 0 on success or -1 on error.
9489 (Added in 1.0.26)
9491 guestfs_pvresize_size
9493 int
9494 guestfs_pvresize_size (guestfs_h *g,
9495 const char *device,
9496 int64_t size);
9497 This command is the same as "guestfs_pvresize" except that it allows
9499 you to specify the new size (in bytes) explicitly.
9500 This function returns 0 on success or -1 on error.
9502 (Added in 1.3.14)
9504 guestfs_pvs
9506 char **
9507 guestfs_pvs (guestfs_h *g);
9508 List all the physical volumes detected. This is the equivalent of the
9510 pvs(8) command.
9511 This returns a list of just the device names that contain PVs (eg.
9513 "/dev/sda2").
9514 See also "guestfs_pvs_full".
9516 This function returns a NULL-terminated array of strings (like
9518 environ(3)), or NULL if there was an error. The caller must free the
9519 strings and the array after use.
9520 (Added in 0.4)
9522 guestfs_pvs_full
9524 struct guestfs_lvm_pv_list *
9525 guestfs_pvs_full (guestfs_h *g);
9526 List all the physical volumes detected. This is the equivalent of the
9528 pvs(8) command. The "full" version includes all fields.
9529 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
9531 there was an error. The caller must call "guestfs_free_lvm_pv_list"
9532 after use.
9533 (Added in 0.4)
9535 guestfs_pvuuid
9537 char *
9538 guestfs_pvuuid (guestfs_h *g,
9539 const char *device);
9540 This command returns the UUID of the LVM PV "device".
9542 This function returns a string, or NULL on error. The caller must free
9544 the returned string after use.
9545 (Added in 1.0.87)
9547 guestfs_pwrite
9549 int
9550 guestfs_pwrite (guestfs_h *g,
9551 const char *path,
9552 const char *content,
9553 size_t content_size,
9554 int64_t offset);
9555 This command writes to part of a file. It writes the data buffer
9557 "content" to the file "path" starting at offset "offset".
9558 This command implements the pwrite(2) system call, and like that system
9560 call it may not write the full data requested. The return value is the
9561 number of bytes that were actually written to the file. This could
9562 even be 0, although short writes are unlikely for regular files in
9563 ordinary circumstances.
9564 See also "guestfs_pread", "guestfs_pwrite_device".
9566 On error this function returns -1.
9568 Because of the message protocol, there is a transfer limit of somewhere
9570 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9571 (Added in 1.3.14)
9573 guestfs_pwrite_device
9575 int
9576 guestfs_pwrite_device (guestfs_h *g,
9577 const char *device,
9578 const char *content,
9579 size_t content_size,
9580 int64_t offset);
9581 This command writes to part of a device. It writes the data buffer
9583 "content" to "device" starting at offset "offset".
9584 This command implements the pwrite(2) system call, and like that system
9586 call it may not write the full data requested (although short writes to
9587 disk devices and partitions are probably impossible with standard Linux
9588 kernels).
9589 See also "guestfs_pwrite".
9591 On error this function returns -1.
9593 Because of the message protocol, there is a transfer limit of somewhere
9595 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9596 (Added in 1.5.20)
9598 guestfs_read_file
9600 char *
9601 guestfs_read_file (guestfs_h *g,
9602 const char *path,
9603 size_t *size_r);
9604 This calls returns the contents of the file "path" as a buffer.
9606 Unlike "guestfs_cat", this function can correctly handle files that
9608 contain embedded ASCII NUL characters.
9609 This function returns a buffer, or NULL on error. The size of the
9611 returned buffer is written to *size_r. The caller must free the
9612 returned buffer after use.
9613 (Added in 1.0.63)
9615 guestfs_read_lines
9617 char **
9618 guestfs_read_lines (guestfs_h *g,
9619 const char *path);
9620 Return the contents of the file named "path".
9622 The file contents are returned as a list of lines. Trailing "LF" and
9624 "CRLF" character sequences are not returned.
9625 Note that this function cannot correctly handle binary files
9627 (specifically, files containing "\0" character which is treated as end
9628 of string). For those you need to use the "guestfs_read_file" function
9629 and split the buffer into lines yourself.
9630 This function returns a NULL-terminated array of strings (like
9632 environ(3)), or NULL if there was an error. The caller must free the
9633 strings and the array after use.
9634 (Added in 0.7)
9636 guestfs_readdir
9638 struct guestfs_dirent_list *
9639 guestfs_readdir (guestfs_h *g,
9640 const char *dir);
9641 This returns the list of directory entries in directory "dir".
9643 All entries in the directory are returned, including "." and "..". The
9645 entries are not sorted, but returned in the same order as the
9646 underlying filesystem.
9647 Also this call returns basic file type information about each file.
9649 The "ftyp" field will contain one of the following characters:
9650 'b' Block special
9652 'c' Char special
9654 'd' Directory
9656 'f' FIFO (named pipe)
9658 'l' Symbolic link
9660 'r' Regular file
9662 's' Socket
9664 'u' Unknown file type
9666 '?' The readdir(3) call returned a "d_type" field with an unexpected
9668 value
9669 This function is primarily intended for use by programs. To get a
9671 simple list of names, use "guestfs_ls". To get a printable directory
9672 for human consumption, use "guestfs_ll".
9673 This function returns a "struct guestfs_dirent_list *", or NULL if
9675 there was an error. The caller must call "guestfs_free_dirent_list"
9676 after use.
9677 Because of the message protocol, there is a transfer limit of somewhere
9679 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9680 (Added in 1.0.55)
9682 guestfs_readlink
9684 char *
9685 guestfs_readlink (guestfs_h *g,
9686 const char *path);
9687 This command reads the target of a symbolic link.
9689 This function returns a string, or NULL on error. The caller must free
9691 the returned string after use.
9692 (Added in 1.0.66)
9694 guestfs_readlinklist
9696 char **
9697 guestfs_readlinklist (guestfs_h *g,
9698 const char *path,
9699 char *const *names);
9700 This call allows you to do a "readlink" operation on multiple files,
9702 where all files are in the directory "path". "names" is the list of
9703 files from this directory.
9704 On return you get a list of strings, with a one-to-one correspondence
9706 to the "names" list. Each string is the value of the symbolic link.
9707 If the readlink(2) operation fails on any name, then the corresponding
9709 result string is the empty string "". However the whole operation is
9710 completed even if there were readlink(2) errors, and so you can call
9711 this function with names where you don't know if they are symbolic
9712 links already (albeit slightly less efficient).
9713 This call is intended for programs that want to efficiently list a
9715 directory contents without making many round-trips.
9716 This function returns a NULL-terminated array of strings (like
9718 environ(3)), or NULL if there was an error. The caller must free the
9719 strings and the array after use.
9720 (Added in 1.0.77)
9722 guestfs_realpath
9724 char *
9725 guestfs_realpath (guestfs_h *g,
9726 const char *path);
9727 Return the canonicalized absolute pathname of "path". The returned
9729 path has no ".", ".." or symbolic link path elements.
9730 This function returns a string, or NULL on error. The caller must free
9732 the returned string after use.
9733 (Added in 1.0.66)
9735 guestfs_remove_drive
9737 int
9738 guestfs_remove_drive (guestfs_h *g,
9739 const char *label);
9740 This function is conceptually the opposite of "guestfs_add_drive_opts".
9742 It removes the drive that was previously added with label "label".
9743 Note that in order to remove drives, you have to add them with labels
9745 (see the optional "label" argument to "guestfs_add_drive_opts"). If
9746 you didn't use a label, then they cannot be removed.
9747 You can call this function before or after launching the handle. If
9749 called after launch, if the attach-method supports it, we try to hot
9750 unplug the drive: see "HOTPLUGGING" in guestfs(3). The disk must not
9751 be in use (eg. mounted) when you do this. We try to detect if the disk
9752 is in use and stop you from doing this.
9753 This function returns 0 on success or -1 on error.
9755 (Added in 1.19.49)
9757 guestfs_removexattr
9759 int
9760 guestfs_removexattr (guestfs_h *g,
9761 const char *xattr,
9762 const char *path);
9763 This call removes the extended attribute named "xattr" of the file
9765 "path".
9766 See also: "guestfs_lremovexattr", attr(5).
9768 This function returns 0 on success or -1 on error.
9770 (Added in 1.0.59)
9772 guestfs_rename
9774 int
9775 guestfs_rename (guestfs_h *g,
9776 const char *oldpath,
9777 const char *newpath);
9778 Rename a file to a new place on the same filesystem. This is the same
9780 as the Linux rename(2) system call. In most cases you are better to
9781 use "guestfs_mv" instead.
9782 This function returns 0 on success or -1 on error.
9784 guestfs_resize2fs
9786 int
9787 guestfs_resize2fs (guestfs_h *g,
9788 const char *device);
9789 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
9791 underlying device.
9792 See also "RESIZE2FS ERRORS" in guestfs(3).
9794 This function returns 0 on success or -1 on error.
9796 (Added in 1.0.27)
9798 guestfs_resize2fs_M
9800 int
9801 guestfs_resize2fs_M (guestfs_h *g,
9802 const char *device);
9803 This command is the same as "guestfs_resize2fs", but the filesystem is
9805 resized to its minimum size. This works like the -M option to the
9806 "resize2fs" command.
9807 To get the resulting size of the filesystem you should call
9809 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
9810 These two numbers, multiplied together, give the resulting size of the
9811 minimal filesystem in bytes.
9812 See also "RESIZE2FS ERRORS" in guestfs(3).
9814 This function returns 0 on success or -1 on error.
9816 (Added in 1.9.4)
9818 guestfs_resize2fs_size
9820 int
9821 guestfs_resize2fs_size (guestfs_h *g,
9822 const char *device,
9823 int64_t size);
9824 This command is the same as "guestfs_resize2fs" except that it allows
9826 you to specify the new size (in bytes) explicitly.
9827 See also "RESIZE2FS ERRORS" in guestfs(3).
9829 This function returns 0 on success or -1 on error.
9831 (Added in 1.3.14)
9833 guestfs_rm
9835 int
9836 guestfs_rm (guestfs_h *g,
9837 const char *path);
9838 Remove the single file "path".
9840 This function returns 0 on success or -1 on error.
9842 (Added in 0.8)
9844 guestfs_rm_f
9846 int
9847 guestfs_rm_f (guestfs_h *g,
9848 const char *path);
9849 Remove the file "path".
9851 If the file doesn't exist, that error is ignored. (Other errors, eg.
9853 I/O errors or bad paths, are not ignored)
9854 This call cannot remove directories. Use "guestfs_rmdir" to remove an
9856 empty directory, or "guestfs_rm_rf" to remove directories recursively.
9857 This function returns 0 on success or -1 on error.
9859 (Added in 1.19.42)
9861 guestfs_rm_rf
9863 int
9864 guestfs_rm_rf (guestfs_h *g,
9865 const char *path);
9866 Remove the file or directory "path", recursively removing the contents
9868 if its a directory. This is like the "rm -rf" shell command.
9869 This function returns 0 on success or -1 on error.
9871 (Added in 0.8)
9873 guestfs_rmdir
9875 int
9876 guestfs_rmdir (guestfs_h *g,
9877 const char *path);
9878 Remove the single directory "path".
9880 This function returns 0 on success or -1 on error.
9882 (Added in 0.8)
9884 guestfs_rmmountpoint
9886 int
9887 guestfs_rmmountpoint (guestfs_h *g,
9888 const char *exemptpath);
9889 This calls removes a mountpoint that was previously created with
9891 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
9892 This function returns 0 on success or -1 on error.
9894 (Added in 1.0.62)
9896 guestfs_rsync
9898 int
9899 guestfs_rsync (guestfs_h *g,
9900 const char *src,
9901 const char *dest,
9902 ...);
9903 You may supply a list of optional arguments to this call. Use zero or
9905 more of the following pairs of parameters, and terminate the list with
9906 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9907 GUESTFS_RSYNC_ARCHIVE, int archive,
9909 GUESTFS_RSYNC_DELETEDEST, int deletedest,
9910 This call may be used to copy or synchronize two directories under the
9912 same libguestfs handle. This uses the rsync(1) program which uses a
9913 fast algorithm that avoids copying files unnecessarily.
9914 "src" and "dest" are the source and destination directories. Files are
9916 copied from "src" to "dest".
9917 The optional arguments are:
9919 "archive"
9921 Turns on archive mode. This is the same as passing the --archive
9922 flag to "rsync".
9923 "deletedest"
9925 Delete files at the destination that do not exist at the source.
9926 This function returns 0 on success or -1 on error.
9928 (Added in 1.19.29)
9930 guestfs_rsync_va
9932 int
9933 guestfs_rsync_va (guestfs_h *g,
9934 const char *src,
9935 const char *dest,
9936 va_list args);
9937 This is the "va_list variant" of "guestfs_rsync".
9939 See "CALLS WITH OPTIONAL ARGUMENTS".
9941 guestfs_rsync_argv
9943 int
9944 guestfs_rsync_argv (guestfs_h *g,
9945 const char *src,
9946 const char *dest,
9947 const struct guestfs_rsync_argv *optargs);
9948 This is the "argv variant" of "guestfs_rsync".
9950 See "CALLS WITH OPTIONAL ARGUMENTS".
9952 guestfs_rsync_in
9954 int
9955 guestfs_rsync_in (guestfs_h *g,
9956 const char *remote,
9957 const char *dest,
9958 ...);
9959 You may supply a list of optional arguments to this call. Use zero or
9961 more of the following pairs of parameters, and terminate the list with
9962 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9963 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
9965 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
9966 This call may be used to copy or synchronize the filesystem on the host
9968 or on a remote computer with the filesystem within libguestfs. This
9969 uses the rsync(1) program which uses a fast algorithm that avoids
9970 copying files unnecessarily.
9971 This call only works if the network is enabled. See
9973 "guestfs_set_network" or the --network option to various tools like
9974 guestfish(1).
9975 Files are copied from the remote server and directory specified by
9977 "remote" to the destination directory "dest".
9978 The format of the remote server string is defined by rsync(1). Note
9980 that there is no way to supply a password or passphrase so the target
9981 must be set up not to require one.
9982 The optional arguments are the same as those of "guestfs_rsync".
9984 This function returns 0 on success or -1 on error.
9986 (Added in 1.19.29)
9988 guestfs_rsync_in_va
9990 int
9991 guestfs_rsync_in_va (guestfs_h *g,
9992 const char *remote,
9993 const char *dest,
9994 va_list args);
9995 This is the "va_list variant" of "guestfs_rsync_in".
9997 See "CALLS WITH OPTIONAL ARGUMENTS".
9999 guestfs_rsync_in_argv
10001 int
10002 guestfs_rsync_in_argv (guestfs_h *g,
10003 const char *remote,
10004 const char *dest,
10005 const struct guestfs_rsync_in_argv *optargs);
10006 This is the "argv variant" of "guestfs_rsync_in".
10008 See "CALLS WITH OPTIONAL ARGUMENTS".
10010 guestfs_rsync_out
10012 int
10013 guestfs_rsync_out (guestfs_h *g,
10014 const char *src,
10015 const char *remote,
10016 ...);
10017 You may supply a list of optional arguments to this call. Use zero or
10019 more of the following pairs of parameters, and terminate the list with
10020 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10021 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
10023 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
10024 This call may be used to copy or synchronize the filesystem within
10026 libguestfs with a filesystem on the host or on a remote computer. This
10027 uses the rsync(1) program which uses a fast algorithm that avoids
10028 copying files unnecessarily.
10029 This call only works if the network is enabled. See
10031 "guestfs_set_network" or the --network option to various tools like
10032 guestfish(1).
10033 Files are copied from the source directory "src" to the remote server
10035 and directory specified by "remote".
10036 The format of the remote server string is defined by rsync(1). Note
10038 that there is no way to supply a password or passphrase so the target
10039 must be set up not to require one.
10040 The optional arguments are the same as those of "guestfs_rsync".
10042 Globbing does not happen on the "src" parameter. In programs which use
10044 the API directly you have to expand wildcards yourself (see
10045 "guestfs_glob_expand"). In guestfish you can use the "glob" command
10046 (see "glob" in guestfish(1)), for example:
10047 ><fs> glob rsync-out /* rsync://remote/
10049 This function returns 0 on success or -1 on error.
10051 (Added in 1.19.29)
10053 guestfs_rsync_out_va
10055 int
10056 guestfs_rsync_out_va (guestfs_h *g,
10057 const char *src,
10058 const char *remote,
10059 va_list args);
10060 This is the "va_list variant" of "guestfs_rsync_out".
10062 See "CALLS WITH OPTIONAL ARGUMENTS".
10064 guestfs_rsync_out_argv
10066 int
10067 guestfs_rsync_out_argv (guestfs_h *g,
10068 const char *src,
10069 const char *remote,
10070 const struct guestfs_rsync_out_argv *optargs);
10071 This is the "argv variant" of "guestfs_rsync_out".
10073 See "CALLS WITH OPTIONAL ARGUMENTS".
10075 guestfs_scrub_device
10077 int
10078 guestfs_scrub_device (guestfs_h *g,
10079 const char *device);
10080 This command writes patterns over "device" to make data retrieval more
10082 difficult.
10083 It is an interface to the scrub(1) program. See that manual page for
10085 more details.
10086 This function returns 0 on success or -1 on error.
10088 (Added in 1.0.52)
10090 guestfs_scrub_file
10092 int
10093 guestfs_scrub_file (guestfs_h *g,
10094 const char *file);
10095 This command writes patterns over a file to make data retrieval more
10097 difficult.
10098 The file is removed after scrubbing.
10100 It is an interface to the scrub(1) program. See that manual page for
10102 more details.
10103 This function returns 0 on success or -1 on error.
10105 (Added in 1.0.52)
10107 guestfs_scrub_freespace
10109 int
10110 guestfs_scrub_freespace (guestfs_h *g,
10111 const char *dir);
10112 This command creates the directory "dir" and then fills it with files
10114 until the filesystem is full, and scrubs the files as for
10115 "guestfs_scrub_file", and deletes them. The intention is to scrub any
10116 free space on the partition containing "dir".
10117 It is an interface to the scrub(1) program. See that manual page for
10119 more details.
10120 This function returns 0 on success or -1 on error.
10122 (Added in 1.0.52)
10124 guestfs_set_append
10126 int
10127 guestfs_set_append (guestfs_h *g,
10128 const char *append);
10129 This function is used to add additional options to the libguestfs
10131 appliance kernel command line.
10132 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
10134 environment variable.
10135 Setting "append" to "NULL" means no additional options are passed
10137 (libguestfs always adds a few of its own).
10138 This function returns 0 on success or -1 on error.
10140 (Added in 1.0.26)
10142 guestfs_set_attach_method
10144 int
10145 guestfs_set_attach_method (guestfs_h *g,
10146 const char *attachmethod);
10147 Set the method that libguestfs uses to connect to the back end guestfsd
10149 daemon.
10150 See "ATTACH METHOD" in guestfs(3).
10152 This function returns 0 on success or -1 on error.
10154 (Added in 1.9.8)
10156 guestfs_set_autosync
10158 int
10159 guestfs_set_autosync (guestfs_h *g,
10160 int autosync);
10161 If "autosync" is true, this enables autosync. Libguestfs will make a
10163 best effort attempt to make filesystems consistent and synchronized
10164 when the handle is closed (also if the program exits without closing
10165 handles).
10166 This is enabled by default (since libguestfs 1.5.24, previously it was
10168 disabled by default).
10169 This function returns 0 on success or -1 on error.
10171 (Added in 0.3)
10173 guestfs_set_cachedir
10175 int
10176 guestfs_set_cachedir (guestfs_h *g,
10177 const char *cachedir);
10178 Set the directory used by the handle to store the appliance cache, when
10180 using a supermin appliance. The appliance is cached and shared between
10181 all handles which have the same effective user ID.
10182 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
10184 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
10185 default. Else if "TMPDIR" is set, then that is the default. Else
10186 "/var/tmp" is the default.
10187 This function returns 0 on success or -1 on error.
10189 (Added in 1.19.58)
10191 guestfs_set_direct
10193 int
10194 guestfs_set_direct (guestfs_h *g,
10195 int direct);
10196 If the direct appliance mode flag is enabled, then stdin and stdout are
10198 passed directly through to the appliance once it is launched.
10199 One consequence of this is that log messages aren't caught by the
10201 library and handled by "guestfs_set_log_message_callback", but go
10202 straight to stdout.
10203 You probably don't want to use this unless you know what you are doing.
10205 The default is disabled.
10207 This function returns 0 on success or -1 on error.
10209 (Added in 1.0.72)
10211 guestfs_set_e2attrs
10213 int
10214 guestfs_set_e2attrs (guestfs_h *g,
10215 const char *file,
10216 const char *attrs,
10217 ...);
10218 You may supply a list of optional arguments to this call. Use zero or
10220 more of the following pairs of parameters, and terminate the list with
10221 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10222 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
10224 This sets or clears the file attributes "attrs" associated with the
10226 inode "file".
10227 "attrs" is a string of characters representing file attributes. See
10229 "guestfs_get_e2attrs" for a list of possible attributes. Not all
10230 attributes can be changed.
10231 If optional boolean "clear" is not present or false, then the "attrs"
10233 listed are set in the inode.
10234 If "clear" is true, then the "attrs" listed are cleared in the inode.
10236 In both cases, other attributes not present in the "attrs" string are
10238 left unchanged.
10239 These attributes are only present when the file is located on an
10241 ext2/3/4 filesystem. Using this call on other filesystem types will
10242 result in an error.
10243 This function returns 0 on success or -1 on error.
10245 (Added in 1.17.31)
10247 guestfs_set_e2attrs_va
10249 int
10250 guestfs_set_e2attrs_va (guestfs_h *g,
10251 const char *file,
10252 const char *attrs,
10253 va_list args);
10254 This is the "va_list variant" of "guestfs_set_e2attrs".
10256 See "CALLS WITH OPTIONAL ARGUMENTS".
10258 guestfs_set_e2attrs_argv
10260 int
10261 guestfs_set_e2attrs_argv (guestfs_h *g,
10262 const char *file,
10263 const char *attrs,
10264 const struct guestfs_set_e2attrs_argv *optargs);
10265 This is the "argv variant" of "guestfs_set_e2attrs".
10267 See "CALLS WITH OPTIONAL ARGUMENTS".
10269 guestfs_set_e2generation
10271 int
10272 guestfs_set_e2generation (guestfs_h *g,
10273 const char *file,
10274 int64_t generation);
10275 This sets the ext2 file generation of a file.
10277 See "guestfs_get_e2generation".
10279 This function returns 0 on success or -1 on error.
10281 (Added in 1.17.31)
10283 guestfs_set_e2label
10285 int
10286 guestfs_set_e2label (guestfs_h *g,
10287 const char *device,
10288 const char *label);
10289 This function is deprecated. In new code, use the "guestfs_set_label"
10291 call instead.
10292 Deprecated functions will not be removed from the API, but the fact
10294 that they are deprecated indicates that there are problems with correct
10295 use of these functions.
10296 This sets the ext2/3/4 filesystem label of the filesystem on "device"
10298 to "label". Filesystem labels are limited to 16 characters.
10299 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
10301 return the existing label on a filesystem.
10302 This function returns 0 on success or -1 on error.
10304 (Added in 1.0.15)
10306 guestfs_set_e2uuid
10308 int
10309 guestfs_set_e2uuid (guestfs_h *g,
10310 const char *device,
10311 const char *uuid);
10312 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
10314 "uuid". The format of the UUID and alternatives such as "clear",
10315 "random" and "time" are described in the tune2fs(8) manpage.
10316 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2uuid" to
10318 return the existing UUID of a filesystem.
10319 This function returns 0 on success or -1 on error.
10321 (Added in 1.0.15)
10323 guestfs_set_label
10325 int
10326 guestfs_set_label (guestfs_h *g,
10327 const char *device,
10328 const char *label);
10329 Set the filesystem label on "device" to "label".
10331 Only some filesystem types support labels, and libguestfs supports
10333 setting labels on only a subset of these.
10334 ext2, ext3, ext4
10336 Labels are limited to 16 bytes.
10337 NTFS
10339 Labels are limited to 128 unicode characters.
10340 XFS The label is limited to 12 bytes. The filesystem must not be
10342 mounted when trying to set the label.
10343 btrfs
10345 The label is limited to 255 bytes and some characters are not
10346 allowed. Setting the label on a btrfs subvolume will set the label
10347 on its parent filesystem. The filesystem must not be mounted when
10348 trying to set the label.
10349 To read the label on a filesystem, call "guestfs_vfs_label".
10351 This function returns 0 on success or -1 on error.
10353 (Added in 1.17.9)
10355 guestfs_set_libvirt_requested_credential
10357 int
10358 guestfs_set_libvirt_requested_credential (guestfs_h *g,
10359 int index,
10360 const char *cred,
10361 size_t cred_size);
10362 After requesting the "index"'th credential from the user, call this
10364 function to pass the answer back to libvirt.
10365 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
10367 example code.
10368 This function returns 0 on success or -1 on error.
10370 (Added in 1.19.52)
10372 guestfs_set_libvirt_supported_credentials
10374 int
10375 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
10376 char *const *creds);
10377 Call this function before setting an event handler for
10379 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
10380 that the program knows how to process.
10381 The "creds" list must be a non-empty list of strings. Possible strings
10383 are:
10384 "username"
10386 "authname"
10387 "language"
10388 "cnonce"
10389 "passphrase"
10390 "echoprompt"
10391 "noechoprompt"
10392 "realm"
10393 "external"
10394 See libvirt documentation for the meaning of these credential types.
10396 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
10398 example code.
10399 This function returns 0 on success or -1 on error.
10401 (Added in 1.19.52)
10403 guestfs_set_memsize
10405 int
10406 guestfs_set_memsize (guestfs_h *g,
10407 int memsize);
10408 This sets the memory size in megabytes allocated to the qemu
10410 subprocess. This only has any effect if called before
10411 "guestfs_launch".
10412 You can also change this by setting the environment variable
10414 "LIBGUESTFS_MEMSIZE" before the handle is created.
10415 For more information on the architecture of libguestfs, see guestfs(3).
10417 This function returns 0 on success or -1 on error.
10419 (Added in 1.0.55)
10421 guestfs_set_network
10423 int
10424 guestfs_set_network (guestfs_h *g,
10425 int network);
10426 If "network" is true, then the network is enabled in the libguestfs
10428 appliance. The default is false.
10429 This affects whether commands are able to access the network (see
10431 "RUNNING COMMANDS" in guestfs(3)).
10432 You must call this before calling "guestfs_launch", otherwise it has no
10434 effect.
10435 This function returns 0 on success or -1 on error.
10437 (Added in 1.5.4)
10439 guestfs_set_path
10441 int
10442 guestfs_set_path (guestfs_h *g,
10443 const char *searchpath);
10444 Set the path that libguestfs searches for kernel and initrd.img.
10446 The default is "$libdir/guestfs" unless overridden by setting
10448 "LIBGUESTFS_PATH" environment variable.
10449 Setting "path" to "NULL" restores the default path.
10451 This function returns 0 on success or -1 on error.
10453 (Added in 0.3)
10455 guestfs_set_pgroup
10457 int
10458 guestfs_set_pgroup (guestfs_h *g,
10459 int pgroup);
10460 If "pgroup" is true, child processes are placed into their own process
10462 group.
10463 The practical upshot of this is that signals like "SIGINT" (from users
10465 pressing "^C") won't be received by the child process.
10466 The default for this flag is false, because usually you want "^C" to
10468 kill the subprocess. Guestfish sets this flag to true when used
10469 interactively, so that "^C" can cancel long-running commands gracefully
10470 (see "guestfs_user_cancel").
10471 This function returns 0 on success or -1 on error.
10473 (Added in 1.11.18)
10475 guestfs_set_qemu
10477 int
10478 guestfs_set_qemu (guestfs_h *g,
10479 const char *qemu);
10480 Set the qemu binary that we will use.
10482 The default is chosen when the library was compiled by the configure
10484 script.
10485 You can also override this by setting the "LIBGUESTFS_QEMU" environment
10487 variable.
10488 Setting "qemu" to "NULL" restores the default qemu binary.
10490 Note that you should call this function as early as possible after
10492 creating the handle. This is because some pre-launch operations depend
10493 on testing qemu features (by running "qemu -help"). If the qemu binary
10494 changes, we don't retest features, and so you might see inconsistent
10495 results. Using the environment variable "LIBGUESTFS_QEMU" is safest of
10496 all since that picks the qemu binary at the same time as the handle is
10497 created.
10498 This function returns 0 on success or -1 on error.
10500 (Added in 1.0.6)
10502 guestfs_set_recovery_proc
10504 int
10505 guestfs_set_recovery_proc (guestfs_h *g,
10506 int recoveryproc);
10507 If this is called with the parameter "false" then "guestfs_launch" does
10509 not create a recovery process. The purpose of the recovery process is
10510 to stop runaway qemu processes in the case where the main program
10511 aborts abruptly.
10512 This only has any effect if called before "guestfs_launch", and the
10514 default is true.
10515 About the only time when you would want to disable this is if the main
10517 process will fork itself into the background ("daemonize" itself). In
10518 this case the recovery process thinks that the main program has
10519 disappeared and so kills qemu, which is not very helpful.
10520 This function returns 0 on success or -1 on error.
10522 (Added in 1.0.77)
10524 guestfs_set_selinux
10526 int
10527 guestfs_set_selinux (guestfs_h *g,
10528 int selinux);
10529 This sets the selinux flag that is passed to the appliance at boot
10531 time. The default is "selinux=0" (disabled).
10532 Note that if SELinux is enabled, it is always in Permissive mode
10534 ("enforcing=0").
10535 For more information on the architecture of libguestfs, see guestfs(3).
10537 This function returns 0 on success or -1 on error.
10539 (Added in 1.0.67)
10541 guestfs_set_smp
10543 int
10544 guestfs_set_smp (guestfs_h *g,
10545 int smp);
10546 Change the number of virtual CPUs assigned to the appliance. The
10548 default is 1. Increasing this may improve performance, though often it
10549 has no effect.
10550 This function must be called before "guestfs_launch".
10552 This function returns 0 on success or -1 on error.
10554 (Added in 1.13.15)
10556 guestfs_set_tmpdir
10558 int
10559 guestfs_set_tmpdir (guestfs_h *g,
10560 const char *tmpdir);
10561 Set the directory used by the handle to store temporary files.
10563 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
10565 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
10566 Else if "TMPDIR" is set, then that is the default. Else "/tmp" is the
10567 default.
10568 This function returns 0 on success or -1 on error.
10570 (Added in 1.19.58)
10572 guestfs_set_trace
10574 int
10575 guestfs_set_trace (guestfs_h *g,
10576 int trace);
10577 If the command trace flag is set to 1, then libguestfs calls,
10579 parameters and return values are traced.
10580 If you want to trace C API calls into libguestfs (and other libraries)
10582 then possibly a better way is to use the external ltrace(1) command.
10583 Command traces are disabled unless the environment variable
10585 "LIBGUESTFS_TRACE" is defined and set to 1.
10586 Trace messages are normally sent to "stderr", unless you register a
10588 callback to send them somewhere else (see
10589 "guestfs_set_event_callback").
10590 This function returns 0 on success or -1 on error.
10592 (Added in 1.0.69)
10594 guestfs_set_verbose
10596 int
10597 guestfs_set_verbose (guestfs_h *g,
10598 int verbose);
10599 If "verbose" is true, this turns on verbose messages.
10601 Verbose messages are disabled unless the environment variable
10603 "LIBGUESTFS_DEBUG" is defined and set to 1.
10604 Verbose messages are normally sent to "stderr", unless you register a
10606 callback to send them somewhere else (see
10607 "guestfs_set_event_callback").
10608 This function returns 0 on success or -1 on error.
10610 (Added in 0.3)
10612 guestfs_setcon
10614 int
10615 guestfs_setcon (guestfs_h *g,
10616 const char *context);
10617 This sets the SELinux security context of the daemon to the string
10619 "context".
10620 See the documentation about SELINUX in guestfs(3).
10622 This function returns 0 on success or -1 on error.
10624 (Added in 1.0.67)
10626 guestfs_setxattr
10628 int
10629 guestfs_setxattr (guestfs_h *g,
10630 const char *xattr,
10631 const char *val,
10632 int vallen,
10633 const char *path);
10634 This call sets the extended attribute named "xattr" of the file "path"
10636 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
10637 data.
10638 See also: "guestfs_lsetxattr", attr(5).
10640 This function returns 0 on success or -1 on error.
10642 (Added in 1.0.59)
10644 guestfs_sfdisk
10646 int
10647 guestfs_sfdisk (guestfs_h *g,
10648 const char *device,
10649 int cyls,
10650 int heads,
10651 int sectors,
10652 char *const *lines);
10653 This function is deprecated. In new code, use the "guestfs_part_add"
10655 call instead.
10656 Deprecated functions will not be removed from the API, but the fact
10658 that they are deprecated indicates that there are problems with correct
10659 use of these functions.
10660 This is a direct interface to the sfdisk(8) program for creating
10662 partitions on block devices.
10663 "device" should be a block device, for example "/dev/sda".
10665 "cyls", "heads" and "sectors" are the number of cylinders, heads and
10667 sectors on the device, which are passed directly to sfdisk as the -C,
10668 -H and -S parameters. If you pass 0 for any of these, then the
10669 corresponding parameter is omitted. Usually for 'large' disks, you can
10670 just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or
10671 rather, the kernel) cannot work out the right geometry and you will
10672 need to tell it.
10673 "lines" is a list of lines that we feed to "sfdisk". For more
10675 information refer to the sfdisk(8) manpage.
10676 To create a single partition occupying the whole disk, you would pass
10678 "lines" as a single element list, when the single element being the
10679 string "," (comma).
10680 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
10682 This function returns 0 on success or -1 on error.
10684 (Added in 0.8)
10686 guestfs_sfdiskM
10688 int
10689 guestfs_sfdiskM (guestfs_h *g,
10690 const char *device,
10691 char *const *lines);
10692 This function is deprecated. In new code, use the "guestfs_part_add"
10694 call instead.
10695 Deprecated functions will not be removed from the API, but the fact
10697 that they are deprecated indicates that there are problems with correct
10698 use of these functions.
10699 This is a simplified interface to the "guestfs_sfdisk" command, where
10701 partition sizes are specified in megabytes only (rounded to the nearest
10702 cylinder) and you don't need to specify the cyls, heads and sectors
10703 parameters which were rarely if ever used anyway.
10704 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
10706 "guestfs_part_disk"
10707 This function returns 0 on success or -1 on error.
10709 (Added in 1.0.55)
10711 guestfs_sfdisk_N
10713 int
10714 guestfs_sfdisk_N (guestfs_h *g,
10715 const char *device,
10716 int partnum,
10717 int cyls,
10718 int heads,
10719 int sectors,
10720 const char *line);
10721 This function is deprecated. In new code, use the "guestfs_part_add"
10723 call instead.
10724 Deprecated functions will not be removed from the API, but the fact
10726 that they are deprecated indicates that there are problems with correct
10727 use of these functions.
10728 This runs sfdisk(8) option to modify just the single partition "n"
10730 (note: "n" counts from 1).
10731 For other parameters, see "guestfs_sfdisk". You should usually pass 0
10733 for the cyls/heads/sectors parameters.
10734 See also: "guestfs_part_add"
10736 This function returns 0 on success or -1 on error.
10738 (Added in 1.0.26)
10740 guestfs_sfdisk_disk_geometry
10742 char *
10743 guestfs_sfdisk_disk_geometry (guestfs_h *g,
10744 const char *device);
10745 This displays the disk geometry of "device" read from the partition
10747 table. Especially in the case where the underlying block device has
10748 been resized, this can be different from the kernel's idea of the
10749 geometry (see "guestfs_sfdisk_kernel_geometry").
10750 The result is in human-readable format, and not designed to be parsed.
10752 This function returns a string, or NULL on error. The caller must free
10754 the returned string after use.
10755 (Added in 1.0.26)
10757 guestfs_sfdisk_kernel_geometry
10759 char *
10760 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
10761 const char *device);
10762 This displays the kernel's idea of the geometry of "device".
10764 The result is in human-readable format, and not designed to be parsed.
10766 This function returns a string, or NULL on error. The caller must free
10768 the returned string after use.
10769 (Added in 1.0.26)
10771 guestfs_sfdisk_l
10773 char *
10774 guestfs_sfdisk_l (guestfs_h *g,
10775 const char *device);
10776 This function is deprecated. In new code, use the "guestfs_part_list"
10778 call instead.
10779 Deprecated functions will not be removed from the API, but the fact
10781 that they are deprecated indicates that there are problems with correct
10782 use of these functions.
10783 This displays the partition table on "device", in the human-readable
10785 output of the sfdisk(8) command. It is not intended to be parsed.
10786 See also: "guestfs_part_list"
10788 This function returns a string, or NULL on error. The caller must free
10790 the returned string after use.
10791 (Added in 1.0.26)
10793 guestfs_sh
10795 char *
10796 guestfs_sh (guestfs_h *g,
10797 const char *command);
10798 This call runs a command from the guest filesystem via the guest's
10800 "/bin/sh".
10801 This is like "guestfs_command", but passes the command to:
10803 /bin/sh -c "command"
10805 Depending on the guest's shell, this usually results in wildcards being
10807 expanded, shell expressions being interpolated and so on.
10808 All the provisos about "guestfs_command" apply to this call.
10810 This function returns a string, or NULL on error. The caller must free
10812 the returned string after use.
10813 (Added in 1.0.50)
10815 guestfs_sh_lines
10817 char **
10818 guestfs_sh_lines (guestfs_h *g,
10819 const char *command);
10820 This is the same as "guestfs_sh", but splits the result into a list of
10822 lines.
10823 See also: "guestfs_command_lines"
10825 This function returns a NULL-terminated array of strings (like
10827 environ(3)), or NULL if there was an error. The caller must free the
10828 strings and the array after use.
10829 (Added in 1.0.50)
10831 guestfs_shutdown
10833 int
10834 guestfs_shutdown (guestfs_h *g);
10835 This is the opposite of "guestfs_launch". It performs an orderly
10837 shutdown of the backend process(es). If the autosync flag is set
10838 (which is the default) then the disk image is synchronized.
10839 If the subprocess exits with an error then this function will return an
10841 error, which should not be ignored (it may indicate that the disk image
10842 could not be written out properly).
10843 It is safe to call this multiple times. Extra calls are ignored.
10845 This call does not close or free up the handle. You still need to call
10847 "guestfs_close" afterwards.
10848 "guestfs_close" will call this if you don't do it explicitly, but note
10850 that any errors are ignored in that case.
10851 This function returns 0 on success or -1 on error.
10853 (Added in 1.19.16)
10855 guestfs_sleep
10857 int
10858 guestfs_sleep (guestfs_h *g,
10859 int secs);
10860 Sleep for "secs" seconds.
10862 This function returns 0 on success or -1 on error.
10864 (Added in 1.0.41)
10866 guestfs_stat
10868 struct guestfs_stat *
10869 guestfs_stat (guestfs_h *g,
10870 const char *path);
10871 Returns file information for the given "path".
10873 This is the same as the stat(2) system call.
10875 This function returns a "struct guestfs_stat *", or NULL if there was
10877 an error. The caller must call "guestfs_free_stat" after use.
10878 (Added in 0.9.2)
10880 guestfs_statvfs
10882 struct guestfs_statvfs *
10883 guestfs_statvfs (guestfs_h *g,
10884 const char *path);
10885 Returns file system statistics for any mounted file system. "path"
10887 should be a file or directory in the mounted file system (typically it
10888 is the mount point itself, but it doesn't need to be).
10889 This is the same as the statvfs(2) system call.
10891 This function returns a "struct guestfs_statvfs *", or NULL if there
10893 was an error. The caller must call "guestfs_free_statvfs" after use.
10894 (Added in 0.9.2)
10896 guestfs_strings
10898 char **
10899 guestfs_strings (guestfs_h *g,
10900 const char *path);
10901 This runs the strings(1) command on a file and returns the list of
10903 printable strings found.
10904 This function returns a NULL-terminated array of strings (like
10906 environ(3)), or NULL if there was an error. The caller must free the
10907 strings and the array after use.
10908 Because of the message protocol, there is a transfer limit of somewhere
10910 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10911 (Added in 1.0.22)
10913 guestfs_strings_e
10915 char **
10916 guestfs_strings_e (guestfs_h *g,
10917 const char *encoding,
10918 const char *path);
10919 This is like the "guestfs_strings" command, but allows you to specify
10921 the encoding of strings that are looked for in the source file "path".
10922 Allowed encodings are:
10924 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
10926 parts of ISO-8859-X (this is what "guestfs_strings" uses).
10927 S Single 8-bit-byte characters.
10929 b 16-bit big endian strings such as those encoded in UTF-16BE or
10931 UCS-2BE.
10932 l (lower case letter L)
10934 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
10935 for examining binaries in Windows guests.
10936 B 32-bit big endian such as UCS-4BE.
10938 L 32-bit little endian such as UCS-4LE.
10940 The returned strings are transcoded to UTF-8.
10942 This function returns a NULL-terminated array of strings (like
10944 environ(3)), or NULL if there was an error. The caller must free the
10945 strings and the array after use.
10946 Because of the message protocol, there is a transfer limit of somewhere
10948 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10949 (Added in 1.0.22)
10951 guestfs_swapoff_device
10953 int
10954 guestfs_swapoff_device (guestfs_h *g,
10955 const char *device);
10956 This command disables the libguestfs appliance swap device or partition
10958 named "device". See "guestfs_swapon_device".
10959 This function returns 0 on success or -1 on error.
10961 (Added in 1.0.66)
10963 guestfs_swapoff_file
10965 int
10966 guestfs_swapoff_file (guestfs_h *g,
10967 const char *file);
10968 This command disables the libguestfs appliance swap on file.
10970 This function returns 0 on success or -1 on error.
10972 (Added in 1.0.66)
10974 guestfs_swapoff_label
10976 int
10977 guestfs_swapoff_label (guestfs_h *g,
10978 const char *label);
10979 This command disables the libguestfs appliance swap on labeled swap
10981 partition.
10982 This function returns 0 on success or -1 on error.
10984 (Added in 1.0.66)
10986 guestfs_swapoff_uuid
10988 int
10989 guestfs_swapoff_uuid (guestfs_h *g,
10990 const char *uuid);
10991 This command disables the libguestfs appliance swap partition with the
10993 given UUID.
10994 This function returns 0 on success or -1 on error.
10996 (Added in 1.0.66)
10998 guestfs_swapon_device
11000 int
11001 guestfs_swapon_device (guestfs_h *g,
11002 const char *device);
11003 This command enables the libguestfs appliance to use the swap device or
11005 partition named "device". The increased memory is made available for
11006 all commands, for example those run using "guestfs_command" or
11007 "guestfs_sh".
11008 Note that you should not swap to existing guest swap partitions unless
11010 you know what you are doing. They may contain hibernation information,
11011 or other information that the guest doesn't want you to trash. You
11012 also risk leaking information about the host to the guest this way.
11013 Instead, attach a new host device to the guest and swap on that.
11014 This function returns 0 on success or -1 on error.
11016 (Added in 1.0.66)
11018 guestfs_swapon_file
11020 int
11021 guestfs_swapon_file (guestfs_h *g,
11022 const char *file);
11023 This command enables swap to a file. See "guestfs_swapon_device" for
11025 other notes.
11026 This function returns 0 on success or -1 on error.
11028 (Added in 1.0.66)
11030 guestfs_swapon_label
11032 int
11033 guestfs_swapon_label (guestfs_h *g,
11034 const char *label);
11035 This command enables swap to a labeled swap partition. See
11037 "guestfs_swapon_device" for other notes.
11038 This function returns 0 on success or -1 on error.
11040 (Added in 1.0.66)
11042 guestfs_swapon_uuid
11044 int
11045 guestfs_swapon_uuid (guestfs_h *g,
11046 const char *uuid);
11047 This command enables swap to a swap partition with the given UUID. See
11049 "guestfs_swapon_device" for other notes.
11050 This function returns 0 on success or -1 on error.
11052 (Added in 1.0.66)
11054 guestfs_sync
11056 int
11057 guestfs_sync (guestfs_h *g);
11058 This syncs the disk, so that any writes are flushed through to the
11060 underlying disk image.
11061 You should always call this if you have modified a disk image, before
11063 closing the handle.
11064 This function returns 0 on success or -1 on error.
11066 (Added in 0.3)
11068 guestfs_tail
11070 char **
11071 guestfs_tail (guestfs_h *g,
11072 const char *path);
11073 This command returns up to the last 10 lines of a file as a list of
11075 strings.
11076 This function returns a NULL-terminated array of strings (like
11078 environ(3)), or NULL if there was an error. The caller must free the
11079 strings and the array after use.
11080 Because of the message protocol, there is a transfer limit of somewhere
11082 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
11083 (Added in 1.0.54)
11085 guestfs_tail_n
11087 char **
11088 guestfs_tail_n (guestfs_h *g,
11089 int nrlines,
11090 const char *path);
11091 If the parameter "nrlines" is a positive number, this returns the last
11093 "nrlines" lines of the file "path".
11094 If the parameter "nrlines" is a negative number, this returns lines
11096 from the file "path", starting with the "-nrlines"th line.
11097 If the parameter "nrlines" is zero, this returns an empty list.
11099 This function returns a NULL-terminated array of strings (like
11101 environ(3)), or NULL if there was an error. The caller must free the
11102 strings and the array after use.
11103 Because of the message protocol, there is a transfer limit of somewhere
11105 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
11106 (Added in 1.0.54)
11108 guestfs_tar_in
11110 int
11111 guestfs_tar_in (guestfs_h *g,
11112 const char *tarfile,
11113 const char *directory);
11114 This function is provided for backwards compatibility with earlier
11116 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
11117 optional arguments.
11118 (Added in 1.0.3)
11120 guestfs_tar_in_opts
11122 int
11123 guestfs_tar_in_opts (guestfs_h *g,
11124 const char *tarfile,
11125 const char *directory,
11126 ...);
11127 You may supply a list of optional arguments to this call. Use zero or
11129 more of the following pairs of parameters, and terminate the list with
11130 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11131 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
11133 This command uploads and unpacks local file "tarfile" into "directory".
11135 The optional "compress" flag controls compression. If not given, then
11137 the input should be an uncompressed tar file. Otherwise one of the
11138 following strings may be given to select the compression type of the
11139 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
11140 all builds of libguestfs will support all of these compression types).
11141 This function returns 0 on success or -1 on error.
11143 (Added in 1.19.30)
11145 guestfs_tar_in_opts_va
11147 int
11148 guestfs_tar_in_opts_va (guestfs_h *g,
11149 const char *tarfile,
11150 const char *directory,
11151 va_list args);
11152 This is the "va_list variant" of "guestfs_tar_in_opts".
11154 See "CALLS WITH OPTIONAL ARGUMENTS".
11156 guestfs_tar_in_opts_argv
11158 int
11159 guestfs_tar_in_opts_argv (guestfs_h *g,
11160 const char *tarfile,
11161 const char *directory,
11162 const struct guestfs_tar_in_opts_argv *optargs);
11163 This is the "argv variant" of "guestfs_tar_in_opts".
11165 See "CALLS WITH OPTIONAL ARGUMENTS".
11167 guestfs_tar_out
11169 int
11170 guestfs_tar_out (guestfs_h *g,
11171 const char *directory,
11172 const char *tarfile);
11173 This function is provided for backwards compatibility with earlier
11175 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
11176 optional arguments.
11177 (Added in 1.0.3)
11179 guestfs_tar_out_opts
11181 int
11182 guestfs_tar_out_opts (guestfs_h *g,
11183 const char *directory,
11184 const char *tarfile,
11185 ...);
11186 You may supply a list of optional arguments to this call. Use zero or
11188 more of the following pairs of parameters, and terminate the list with
11189 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11190 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
11192 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
11193 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
11194 This command packs the contents of "directory" and downloads it to
11196 local file "tarfile".
11197 The optional "compress" flag controls compression. If not given, then
11199 the output will be an uncompressed tar file. Otherwise one of the
11200 following strings may be given to select the compression type of the
11201 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
11202 all builds of libguestfs will support all of these compression types).
11203 The other optional arguments are:
11205 "excludes"
11207 A list of wildcards. Files are excluded if they match any of the
11208 wildcards.
11209 "numericowner"
11211 If set to true, the output tar file will contain UID/GID numbers
11212 instead of user/group names.
11213 This function returns 0 on success or -1 on error.
11215 (Added in 1.19.30)
11217 guestfs_tar_out_opts_va
11219 int
11220 guestfs_tar_out_opts_va (guestfs_h *g,
11221 const char *directory,
11222 const char *tarfile,
11223 va_list args);
11224 This is the "va_list variant" of "guestfs_tar_out_opts".
11226 See "CALLS WITH OPTIONAL ARGUMENTS".
11228 guestfs_tar_out_opts_argv
11230 int
11231 guestfs_tar_out_opts_argv (guestfs_h *g,
11232 const char *directory,
11233 const char *tarfile,
11234 const struct guestfs_tar_out_opts_argv *optargs);
11235 This is the "argv variant" of "guestfs_tar_out_opts".
11237 See "CALLS WITH OPTIONAL ARGUMENTS".
11239 guestfs_tgz_in
11241 int
11242 guestfs_tgz_in (guestfs_h *g,
11243 const char *tarball,
11244 const char *directory);
11245 This function is deprecated. In new code, use the "guestfs_tar_in"
11247 call instead.
11248 Deprecated functions will not be removed from the API, but the fact
11250 that they are deprecated indicates that there are problems with correct
11251 use of these functions.
11252 This command uploads and unpacks local file "tarball" (a gzip
11254 compressed tar file) into "directory".
11255 This function returns 0 on success or -1 on error.
11257 (Added in 1.0.3)
11259 guestfs_tgz_out
11261 int
11262 guestfs_tgz_out (guestfs_h *g,
11263 const char *directory,
11264 const char *tarball);
11265 This function is deprecated. In new code, use the "guestfs_tar_out"
11267 call instead.
11268 Deprecated functions will not be removed from the API, but the fact
11270 that they are deprecated indicates that there are problems with correct
11271 use of these functions.
11272 This command packs the contents of "directory" and downloads it to
11274 local file "tarball".
11275 This function returns 0 on success or -1 on error.
11277 (Added in 1.0.3)
11279 guestfs_touch
11281 int
11282 guestfs_touch (guestfs_h *g,
11283 const char *path);
11284 Touch acts like the touch(1) command. It can be used to update the
11286 timestamps on a file, or, if the file does not exist, to create a new
11287 zero-length file.
11288 This command only works on regular files, and will fail on other file
11290 types such as directories, symbolic links, block special etc.
11291 This function returns 0 on success or -1 on error.
11293 (Added in 0.3)
11295 guestfs_truncate
11297 int
11298 guestfs_truncate (guestfs_h *g,
11299 const char *path);
11300 This command truncates "path" to a zero-length file. The file must
11302 exist already.
11303 This function returns 0 on success or -1 on error.
11305 (Added in 1.0.77)
11307 guestfs_truncate_size
11309 int
11310 guestfs_truncate_size (guestfs_h *g,
11311 const char *path,
11312 int64_t size);
11313 This command truncates "path" to size "size" bytes. The file must
11315 exist already.
11316 If the current file size is less than "size" then the file is extended
11318 to the required size with zero bytes. This creates a sparse file (ie.
11319 disk blocks are not allocated for the file until you write to it). To
11320 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
11321 This function returns 0 on success or -1 on error.
11323 (Added in 1.0.77)
11325 guestfs_tune2fs
11327 int
11328 guestfs_tune2fs (guestfs_h *g,
11329 const char *device,
11330 ...);
11331 You may supply a list of optional arguments to this call. Use zero or
11333 more of the following pairs of parameters, and terminate the list with
11334 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11335 GUESTFS_TUNE2FS_FORCE, int force,
11337 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
11338 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
11339 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
11340 GUESTFS_TUNE2FS_GROUP, int64_t group,
11341 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
11342 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
11343 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
11344 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
11345 GUESTFS_TUNE2FS_USER, int64_t user,
11346 This call allows you to adjust various filesystem parameters of an
11348 ext2/ext3/ext4 filesystem called "device".
11349 The optional parameters are:
11351 "force"
11353 Force tune2fs to complete the operation even in the face of errors.
11354 This is the same as the tune2fs "-f" option.
11355 "maxmountcount"
11357 Set the number of mounts after which the filesystem is checked by
11358 e2fsck(8). If this is 0 then the number of mounts is disregarded.
11359 This is the same as the tune2fs "-c" option.
11360 "mountcount"
11362 Set the number of times the filesystem has been mounted. This is
11363 the same as the tune2fs "-C" option.
11364 "errorbehavior"
11366 Change the behavior of the kernel code when errors are detected.
11367 Possible values currently are: "continue", "remount-ro", "panic".
11368 In practice these options don't really make any difference,
11369 particularly for write errors.
11370 This is the same as the tune2fs "-e" option.
11372 "group"
11374 Set the group which can use reserved filesystem blocks. This is
11375 the same as the tune2fs "-g" option except that it can only be
11376 specified as a number.
11377 "intervalbetweenchecks"
11379 Adjust the maximal time between two filesystem checks (in seconds).
11380 If the option is passed as 0 then time-dependent checking is
11381 disabled.
11382 This is the same as the tune2fs "-i" option.
11384 "reservedblockspercentage"
11386 Set the percentage of the filesystem which may only be allocated by
11387 privileged processes. This is the same as the tune2fs "-m" option.
11388 "lastmounteddirectory"
11390 Set the last mounted directory. This is the same as the tune2fs
11391 "-M" option.
11392 "reservedblockscount" Set the number of reserved filesystem blocks.
11394 This is the same as the tune2fs "-r" option.
11395 "user"
11396 Set the user who can use the reserved filesystem blocks. This is
11397 the same as the tune2fs "-u" option except that it can only be
11398 specified as a number.
11399 To get the current values of filesystem parameters, see
11401 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
11402 tune2fs(8) man page.
11403 This function returns 0 on success or -1 on error.
11405 (Added in 1.15.4)
11407 guestfs_tune2fs_va
11409 int
11410 guestfs_tune2fs_va (guestfs_h *g,
11411 const char *device,
11412 va_list args);
11413 This is the "va_list variant" of "guestfs_tune2fs".
11415 See "CALLS WITH OPTIONAL ARGUMENTS".
11417 guestfs_tune2fs_argv
11419 int
11420 guestfs_tune2fs_argv (guestfs_h *g,
11421 const char *device,
11422 const struct guestfs_tune2fs_argv *optargs);
11423 This is the "argv variant" of "guestfs_tune2fs".
11425 See "CALLS WITH OPTIONAL ARGUMENTS".
11427 guestfs_tune2fs_l
11429 char **
11430 guestfs_tune2fs_l (guestfs_h *g,
11431 const char *device);
11432 This returns the contents of the ext2, ext3 or ext4 filesystem
11434 superblock on "device".
11435 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
11437 for more details. The list of fields returned isn't clearly defined,
11438 and depends on both the version of "tune2fs" that libguestfs was built
11439 against, and the filesystem itself.
11440 This function returns a NULL-terminated array of strings, or NULL if
11442 there was an error. The array of strings will always have length
11443 "2n+1", where "n" keys and values alternate, followed by the trailing
11444 NULL entry. The caller must free the strings and the array after use.
11445 (Added in 0.9.2)
11447 guestfs_txz_in
11449 int
11450 guestfs_txz_in (guestfs_h *g,
11451 const char *tarball,
11452 const char *directory);
11453 This function is deprecated. In new code, use the "guestfs_tar_in"
11455 call instead.
11456 Deprecated functions will not be removed from the API, but the fact
11458 that they are deprecated indicates that there are problems with correct
11459 use of these functions.
11460 This command uploads and unpacks local file "tarball" (an xz compressed
11462 tar file) into "directory".
11463 This function returns 0 on success or -1 on error.
11465 (Added in 1.3.2)
11467 guestfs_txz_out
11469 int
11470 guestfs_txz_out (guestfs_h *g,
11471 const char *directory,
11472 const char *tarball);
11473 This function is deprecated. In new code, use the "guestfs_tar_out"
11475 call instead.
11476 Deprecated functions will not be removed from the API, but the fact
11478 that they are deprecated indicates that there are problems with correct
11479 use of these functions.
11480 This command packs the contents of "directory" and downloads it to
11482 local file "tarball" (as an xz compressed tar archive).
11483 This function returns 0 on success or -1 on error.
11485 (Added in 1.3.2)
11487 guestfs_umask
11489 int
11490 guestfs_umask (guestfs_h *g,
11491 int mask);
11492 This function sets the mask used for creating new files and device
11494 nodes to "mask & 0777".
11495 Typical umask values would be 022 which creates new files with
11497 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
11498 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
11499 The default umask is 022. This is important because it means that
11501 directories and device nodes will be created with 0644 or 0755 mode
11502 even if you specify 0777.
11503 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
11505 "guestfs_mkdir".
11506 This call returns the previous umask.
11508 On error this function returns -1.
11510 (Added in 1.0.55)
11512 guestfs_umount
11514 int
11515 guestfs_umount (guestfs_h *g,
11516 const char *pathordevice);
11517 This function is provided for backwards compatibility with earlier
11519 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
11520 optional arguments.
11521 (Added in 0.8)
11523 guestfs_umount_opts
11525 int
11526 guestfs_umount_opts (guestfs_h *g,
11527 const char *pathordevice,
11528 ...);
11529 You may supply a list of optional arguments to this call. Use zero or
11531 more of the following pairs of parameters, and terminate the list with
11532 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11533 GUESTFS_UMOUNT_OPTS_FORCE, int force,
11535 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
11536 This unmounts the given filesystem. The filesystem may be specified
11538 either by its mountpoint (path) or the device which contains the
11539 filesystem.
11540 This function returns 0 on success or -1 on error.
11542 (Added in 1.19.25)
11544 guestfs_umount_opts_va
11546 int
11547 guestfs_umount_opts_va (guestfs_h *g,
11548 const char *pathordevice,
11549 va_list args);
11550 This is the "va_list variant" of "guestfs_umount_opts".
11552 See "CALLS WITH OPTIONAL ARGUMENTS".
11554 guestfs_umount_opts_argv
11556 int
11557 guestfs_umount_opts_argv (guestfs_h *g,
11558 const char *pathordevice,
11559 const struct guestfs_umount_opts_argv *optargs);
11560 This is the "argv variant" of "guestfs_umount_opts".
11562 See "CALLS WITH OPTIONAL ARGUMENTS".
11564 guestfs_umount_all
11566 int
11567 guestfs_umount_all (guestfs_h *g);
11568 This unmounts all mounted filesystems.
11570 Some internal mounts are not unmounted by this call.
11572 This function returns 0 on success or -1 on error.
11574 (Added in 0.8)
11576 guestfs_umount_local
11578 int
11579 guestfs_umount_local (guestfs_h *g,
11580 ...);
11581 You may supply a list of optional arguments to this call. Use zero or
11583 more of the following pairs of parameters, and terminate the list with
11584 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11585 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
11587 If libguestfs is exporting the filesystem on a local mountpoint, then
11589 this unmounts it.
11590 See "MOUNT LOCAL" in guestfs(3) for full documentation.
11592 This function returns 0 on success or -1 on error.
11594 (Added in 1.17.22)
11596 guestfs_umount_local_va
11598 int
11599 guestfs_umount_local_va (guestfs_h *g,
11600 va_list args);
11601 This is the "va_list variant" of "guestfs_umount_local".
11603 See "CALLS WITH OPTIONAL ARGUMENTS".
11605 guestfs_umount_local_argv
11607 int
11608 guestfs_umount_local_argv (guestfs_h *g,
11609 const struct guestfs_umount_local_argv *optargs);
11610 This is the "argv variant" of "guestfs_umount_local".
11612 See "CALLS WITH OPTIONAL ARGUMENTS".
11614 guestfs_upload
11616 int
11617 guestfs_upload (guestfs_h *g,
11618 const char *filename,
11619 const char *remotefilename);
11620 Upload local file "filename" to "remotefilename" on the filesystem.
11622 "filename" can also be a named pipe.
11624 See also "guestfs_download".
11626 This function returns 0 on success or -1 on error.
11628 This long-running command can generate progress notification messages
11630 so that the caller can display a progress bar or indicator. To receive
11631 these messages, the caller must register a progress event callback.
11632 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
11633 (Added in 1.0.2)
11635 guestfs_upload_offset
11637 int
11638 guestfs_upload_offset (guestfs_h *g,
11639 const char *filename,
11640 const char *remotefilename,
11641 int64_t offset);
11642 Upload local file "filename" to "remotefilename" on the filesystem.
11644 "remotefilename" is overwritten starting at the byte "offset"
11646 specified. The intention is to overwrite parts of existing files or
11647 devices, although if a non-existent file is specified then it is
11648 created with a "hole" before "offset". The size of the data written is
11649 implicit in the size of the source "filename".
11650 Note that there is no limit on the amount of data that can be uploaded
11652 with this call, unlike with "guestfs_pwrite", and this call always
11653 writes the full amount unless an error occurs.
11654 See also "guestfs_upload", "guestfs_pwrite".
11656 This function returns 0 on success or -1 on error.
11658 This long-running command can generate progress notification messages
11660 so that the caller can display a progress bar or indicator. To receive
11661 these messages, the caller must register a progress event callback.
11662 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
11663 (Added in 1.5.17)
11665 guestfs_user_cancel
11667 int
11668 guestfs_user_cancel (guestfs_h *g);
11669 This function cancels the current upload or download operation.
11671 Unlike most other libguestfs calls, this function is signal safe and
11673 thread safe. You can call it from a signal handler or from another
11674 thread, without needing to do any locking.
11675 The transfer that was in progress (if there is one) will stop shortly
11677 afterwards, and will return an error. The errno (see
11678 "guestfs_last_errno") is set to "EINTR", so you can test for this to
11679 find out if the operation was cancelled or failed because of another
11680 error.
11681 No cleanup is performed: for example, if a file was being uploaded then
11683 after cancellation there may be a partially uploaded file. It is the
11684 caller's responsibility to clean up if necessary.
11685 There are two common places that you might call "guestfs_user_cancel":
11687 In an interactive text-based program, you might call it from a "SIGINT"
11689 signal handler so that pressing "^C" cancels the current operation.
11690 (You also need to call "guestfs_set_pgroup" so that child processes
11691 don't receive the "^C" signal).
11692 In a graphical program, when the main thread is displaying a progress
11694 bar with a cancel button, wire up the cancel button to call this
11695 function.
11696 This function returns 0 on success or -1 on error.
11698 (Added in 1.11.18)
11700 guestfs_utimens
11702 int
11703 guestfs_utimens (guestfs_h *g,
11704 const char *path,
11705 int64_t atsecs,
11706 int64_t atnsecs,
11707 int64_t mtsecs,
11708 int64_t mtnsecs);
11709 This command sets the timestamps of a file with nanosecond precision.
11711 "atsecs, atnsecs" are the last access time (atime) in secs and
11713 nanoseconds from the epoch.
11714 "mtsecs, mtnsecs" are the last modification time (mtime) in secs and
11716 nanoseconds from the epoch.
11717 If the *nsecs field contains the special value "-1" then the
11719 corresponding timestamp is set to the current time. (The *secs field
11720 is ignored in this case).
11721 If the *nsecs field contains the special value "-2" then the
11723 corresponding timestamp is left unchanged. (The *secs field is ignored
11724 in this case).
11725 This function returns 0 on success or -1 on error.
11727 (Added in 1.0.77)
11729 guestfs_utsname
11731 struct guestfs_utsname *
11732 guestfs_utsname (guestfs_h *g);
11733 This returns the kernel version of the appliance, where this is
11735 available. This information is only useful for debugging. Nothing in
11736 the returned structure is defined by the API.
11737 This function returns a "struct guestfs_utsname *", or NULL if there
11739 was an error. The caller must call "guestfs_free_utsname" after use.
11740 (Added in 1.19.27)
11742 guestfs_version
11744 struct guestfs_version *
11745 guestfs_version (guestfs_h *g);
11746 Return the libguestfs version number that the program is linked
11748 against.
11749 Note that because of dynamic linking this is not necessarily the
11751 version of libguestfs that you compiled against. You can compile the
11752 program, and then at runtime dynamically link against a completely
11753 different "libguestfs.so" library.
11754 This call was added in version 1.0.58. In previous versions of
11756 libguestfs there was no way to get the version number. From C code you
11757 can use dynamic linker functions to find out if this symbol exists (if
11758 it doesn't, then it's an earlier version).
11759 The call returns a structure with four elements. The first three
11761 ("major", "minor" and "release") are numbers and correspond to the
11762 usual version triplet. The fourth element ("extra") is a string and is
11763 normally empty, but may be used for distro-specific information.
11764 To construct the original version string:
11766 "$major.$minor.$release$extra"
11767 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
11769 Note: Don't use this call to test for availability of features. In
11771 enterprise distributions we backport features from later versions into
11772 earlier versions, making this an unreliable way to test for features.
11773 Use "guestfs_available" instead.
11774 This function returns a "struct guestfs_version *", or NULL if there
11776 was an error. The caller must call "guestfs_free_version" after use.
11777 (Added in 1.0.58)
11779 guestfs_vfs_label
11781 char *
11782 guestfs_vfs_label (guestfs_h *g,
11783 const char *device);
11784 This returns the filesystem label of the filesystem on "device".
11786 If the filesystem is unlabeled, this returns the empty string.
11788 To find a filesystem from the label, use "guestfs_findfs_label".
11790 This function returns a string, or NULL on error. The caller must free
11792 the returned string after use.
11793 (Added in 1.3.18)
11795 guestfs_vfs_type
11797 char *
11798 guestfs_vfs_type (guestfs_h *g,
11799 const char *device);
11800 This command gets the filesystem type corresponding to the filesystem
11802 on "device".
11803 For most filesystems, the result is the name of the Linux VFS module
11805 which would be used to mount this filesystem if you mounted it without
11806 specifying the filesystem type. For example a string such as "ext3" or
11807 "ntfs".
11808 This function returns a string, or NULL on error. The caller must free
11810 the returned string after use.
11811 (Added in 1.0.75)
11813 guestfs_vfs_uuid
11815 char *
11816 guestfs_vfs_uuid (guestfs_h *g,
11817 const char *device);
11818 This returns the filesystem UUID of the filesystem on "device".
11820 If the filesystem does not have a UUID, this returns the empty string.
11822 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
11824 This function returns a string, or NULL on error. The caller must free
11826 the returned string after use.
11827 (Added in 1.3.18)
11829 guestfs_vg_activate
11831 int
11832 guestfs_vg_activate (guestfs_h *g,
11833 int activate,
11834 char *const *volgroups);
11835 This command activates or (if "activate" is false) deactivates all
11837 logical volumes in the listed volume groups "volgroups".
11838 This command is the same as running "vgchange -a y|n volgroups..."
11840 Note that if "volgroups" is an empty list then all volume groups are
11842 activated or deactivated.
11843 This function returns 0 on success or -1 on error.
11845 (Added in 1.0.26)
11847 guestfs_vg_activate_all
11849 int
11850 guestfs_vg_activate_all (guestfs_h *g,
11851 int activate);
11852 This command activates or (if "activate" is false) deactivates all
11854 logical volumes in all volume groups.
11855 This command is the same as running "vgchange -a y|n"
11857 This function returns 0 on success or -1 on error.
11859 (Added in 1.0.26)
11861 guestfs_vgchange_uuid
11863 int
11864 guestfs_vgchange_uuid (guestfs_h *g,
11865 const char *vg);
11866 Generate a new random UUID for the volume group "vg".
11868 This function returns 0 on success or -1 on error.
11870 (Added in 1.19.26)
11872 guestfs_vgchange_uuid_all
11874 int
11875 guestfs_vgchange_uuid_all (guestfs_h *g);
11876 Generate new random UUIDs for all volume groups.
11878 This function returns 0 on success or -1 on error.
11880 (Added in 1.19.26)
11882 guestfs_vgcreate
11884 int
11885 guestfs_vgcreate (guestfs_h *g,
11886 const char *volgroup,
11887 char *const *physvols);
11888 This creates an LVM volume group called "volgroup" from the non-empty
11890 list of physical volumes "physvols".
11891 This function returns 0 on success or -1 on error.
11893 (Added in 0.8)
11895 guestfs_vglvuuids
11897 char **
11898 guestfs_vglvuuids (guestfs_h *g,
11899 const char *vgname);
11900 Given a VG called "vgname", this returns the UUIDs of all the logical
11902 volumes created in this volume group.
11903 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
11905 associate logical volumes and volume groups.
11906 See also "guestfs_vgpvuuids".
11908 This function returns a NULL-terminated array of strings (like
11910 environ(3)), or NULL if there was an error. The caller must free the
11911 strings and the array after use.
11912 (Added in 1.0.87)
11914 guestfs_vgmeta
11916 char *
11917 guestfs_vgmeta (guestfs_h *g,
11918 const char *vgname,
11919 size_t *size_r);
11920 "vgname" is an LVM volume group. This command examines the volume
11922 group and returns its metadata.
11923 Note that the metadata is an internal structure used by LVM, subject to
11925 change at any time, and is provided for information only.
11926 This function returns a buffer, or NULL on error. The size of the
11928 returned buffer is written to *size_r. The caller must free the
11929 returned buffer after use.
11930 (Added in 1.17.20)
11932 guestfs_vgpvuuids
11934 char **
11935 guestfs_vgpvuuids (guestfs_h *g,
11936 const char *vgname);
11937 Given a VG called "vgname", this returns the UUIDs of all the physical
11939 volumes that this volume group resides on.
11940 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
11942 associate physical volumes and volume groups.
11943 See also "guestfs_vglvuuids".
11945 This function returns a NULL-terminated array of strings (like
11947 environ(3)), or NULL if there was an error. The caller must free the
11948 strings and the array after use.
11949 (Added in 1.0.87)
11951 guestfs_vgremove
11953 int
11954 guestfs_vgremove (guestfs_h *g,
11955 const char *vgname);
11956 Remove an LVM volume group "vgname", (for example "VG").
11958 This also forcibly removes all logical volumes in the volume group (if
11960 any).
11961 This function returns 0 on success or -1 on error.
11963 (Added in 1.0.13)
11965 guestfs_vgrename
11967 int
11968 guestfs_vgrename (guestfs_h *g,
11969 const char *volgroup,
11970 const char *newvolgroup);
11971 Rename a volume group "volgroup" with the new name "newvolgroup".
11973 This function returns 0 on success or -1 on error.
11975 (Added in 1.0.83)
11977 guestfs_vgs
11979 char **
11980 guestfs_vgs (guestfs_h *g);
11981 List all the volumes groups detected. This is the equivalent of the
11983 vgs(8) command.
11984 This returns a list of just the volume group names that were detected
11986 (eg. "VolGroup00").
11987 See also "guestfs_vgs_full".
11989 This function returns a NULL-terminated array of strings (like
11991 environ(3)), or NULL if there was an error. The caller must free the
11992 strings and the array after use.
11993 (Added in 0.4)
11995 guestfs_vgs_full
11997 struct guestfs_lvm_vg_list *
11998 guestfs_vgs_full (guestfs_h *g);
11999 List all the volumes groups detected. This is the equivalent of the
12001 vgs(8) command. The "full" version includes all fields.
12002 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
12004 there was an error. The caller must call "guestfs_free_lvm_vg_list"
12005 after use.
12006 (Added in 0.4)
12008 guestfs_vgscan
12010 int
12011 guestfs_vgscan (guestfs_h *g);
12012 This rescans all block devices and rebuilds the list of LVM physical
12014 volumes, volume groups and logical volumes.
12015 This function returns 0 on success or -1 on error.
12017 (Added in 1.3.2)
12019 guestfs_vguuid
12021 char *
12022 guestfs_vguuid (guestfs_h *g,
12023 const char *vgname);
12024 This command returns the UUID of the LVM VG named "vgname".
12026 This function returns a string, or NULL on error. The caller must free
12028 the returned string after use.
12029 (Added in 1.0.87)
12031 guestfs_wait_ready
12033 int
12034 guestfs_wait_ready (guestfs_h *g);
12035 This function is deprecated. In new code, use the "guestfs_launch"
12037 call instead.
12038 Deprecated functions will not be removed from the API, but the fact
12040 that they are deprecated indicates that there are problems with correct
12041 use of these functions.
12042 This function is a no op.
12044 In versions of the API < 1.0.71 you had to call this function just
12046 after calling "guestfs_launch" to wait for the launch to complete.
12047 However this is no longer necessary because "guestfs_launch" now does
12048 the waiting.
12049 If you see any calls to this function in code then you can just remove
12051 them, unless you want to retain compatibility with older versions of
12052 the API.
12053 This function returns 0 on success or -1 on error.
12055 (Added in 0.3)
12057 guestfs_wc_c
12059 int
12060 guestfs_wc_c (guestfs_h *g,
12061 const char *path);
12062 This command counts the characters in a file, using the "wc -c"
12064 external command.
12065 On error this function returns -1.
12067 (Added in 1.0.54)
12069 guestfs_wc_l
12071 int
12072 guestfs_wc_l (guestfs_h *g,
12073 const char *path);
12074 This command counts the lines in a file, using the "wc -l" external
12076 command.
12077 On error this function returns -1.
12079 (Added in 1.0.54)
12081 guestfs_wc_w
12083 int
12084 guestfs_wc_w (guestfs_h *g,
12085 const char *path);
12086 This command counts the words in a file, using the "wc -w" external
12088 command.
12089 On error this function returns -1.
12091 (Added in 1.0.54)
12093 guestfs_wipefs
12095 int
12096 guestfs_wipefs (guestfs_h *g,
12097 const char *device);
12098 This command erases filesystem or RAID signatures from the specified
12100 "device" to make the filesystem invisible to libblkid.
12101 This does not erase the filesystem itself nor any other data from the
12103 "device".
12104 Compare with "guestfs_zero" which zeroes the first few blocks of a
12106 device.
12107 This function returns 0 on success or -1 on error.
12109 (Added in 1.17.6)
12111 guestfs_write
12113 int
12114 guestfs_write (guestfs_h *g,
12115 const char *path,
12116 const char *content,
12117 size_t content_size);
12118 This call creates a file called "path". The content of the file is the
12120 string "content" (which can contain any 8 bit data).
12121 See also "guestfs_write_append".
12123 This function returns 0 on success or -1 on error.
12125 (Added in 1.3.14)
12127 guestfs_write_append
12129 int
12130 guestfs_write_append (guestfs_h *g,
12131 const char *path,
12132 const char *content,
12133 size_t content_size);
12134 This call appends "content" to the end of file "path". If "path" does
12136 not exist, then a new file is created.
12137 See also "guestfs_write".
12139 This function returns 0 on success or -1 on error.
12141 (Added in 1.11.18)
12143 guestfs_write_file
12145 int
12146 guestfs_write_file (guestfs_h *g,
12147 const char *path,
12148 const char *content,
12149 int size);
12150 This function is deprecated. In new code, use the "guestfs_write" call
12152 instead.
12153 Deprecated functions will not be removed from the API, but the fact
12155 that they are deprecated indicates that there are problems with correct
12156 use of these functions.
12157 This call creates a file called "path". The contents of the file is
12159 the string "content" (which can contain any 8 bit data), with length
12160 "size".
12161 As a special case, if "size" is 0 then the length is calculated using
12163 "strlen" (so in this case the content cannot contain embedded ASCII
12164 NULs).
12165 NB. Owing to a bug, writing content containing ASCII NUL characters
12167 does not work, even if the length is specified.
12168 This function returns 0 on success or -1 on error.
12170 Because of the message protocol, there is a transfer limit of somewhere
12172 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
12173 (Added in 0.8)
12175 guestfs_xfs_admin
12177 int
12178 guestfs_xfs_admin (guestfs_h *g,
12179 const char *device,
12180 ...);
12181 You may supply a list of optional arguments to this call. Use zero or
12183 more of the following pairs of parameters, and terminate the list with
12184 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12185 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
12187 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
12188 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
12189 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
12190 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
12191 GUESTFS_XFS_ADMIN_LABEL, const char *label,
12192 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
12193 Change the parameters of the XFS filesystem on "device".
12195 Devices that are mounted cannot be modified. Administrators must
12197 unmount filesystems before this call can modify parameters.
12198 Some of the parameters of a mounted filesystem can be examined and
12200 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
12201 This function returns 0 on success or -1 on error.
12203 (Added in 1.19.33)
12205 guestfs_xfs_admin_va
12207 int
12208 guestfs_xfs_admin_va (guestfs_h *g,
12209 const char *device,
12210 va_list args);
12211 This is the "va_list variant" of "guestfs_xfs_admin".
12213 See "CALLS WITH OPTIONAL ARGUMENTS".
12215 guestfs_xfs_admin_argv
12217 int
12218 guestfs_xfs_admin_argv (guestfs_h *g,
12219 const char *device,
12220 const struct guestfs_xfs_admin_argv *optargs);
12221 This is the "argv variant" of "guestfs_xfs_admin".
12223 See "CALLS WITH OPTIONAL ARGUMENTS".
12225 guestfs_xfs_growfs
12227 int
12228 guestfs_xfs_growfs (guestfs_h *g,
12229 const char *path,
12230 ...);
12231 You may supply a list of optional arguments to this call. Use zero or
12233 more of the following pairs of parameters, and terminate the list with
12234 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12235 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
12237 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
12238 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
12239 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
12240 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
12241 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
12242 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
12243 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
12244 Grow the XFS filesystem mounted at "path".
12246 The returned struct contains geometry information. Missing fields are
12248 returned as "-1" (for numeric fields) or empty string.
12249 This function returns 0 on success or -1 on error.
12251 (Added in 1.19.28)
12253 guestfs_xfs_growfs_va
12255 int
12256 guestfs_xfs_growfs_va (guestfs_h *g,
12257 const char *path,
12258 va_list args);
12259 This is the "va_list variant" of "guestfs_xfs_growfs".
12261 See "CALLS WITH OPTIONAL ARGUMENTS".
12263 guestfs_xfs_growfs_argv
12265 int
12266 guestfs_xfs_growfs_argv (guestfs_h *g,
12267 const char *path,
12268 const struct guestfs_xfs_growfs_argv *optargs);
12269 This is the "argv variant" of "guestfs_xfs_growfs".
12271 See "CALLS WITH OPTIONAL ARGUMENTS".
12273 guestfs_xfs_info
12275 struct guestfs_xfsinfo *
12276 guestfs_xfs_info (guestfs_h *g,
12277 const char *pathordevice);
12278 "pathordevice" is a mounted XFS filesystem or a device containing an
12280 XFS filesystem. This command returns the geometry of the filesystem.
12281 The returned struct contains geometry information. Missing fields are
12283 returned as "-1" (for numeric fields) or empty string.
12284 This function returns a "struct guestfs_xfsinfo *", or NULL if there
12286 was an error. The caller must call "guestfs_free_xfsinfo" after use.
12287 (Added in 1.19.21)
12289 guestfs_xfs_repair
12291 int
12292 guestfs_xfs_repair (guestfs_h *g,
12293 const char *device,
12294 ...);
12295 You may supply a list of optional arguments to this call. Use zero or
12297 more of the following pairs of parameters, and terminate the list with
12298 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12299 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
12301 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
12302 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
12303 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
12304 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
12305 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
12306 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
12307 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
12308 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
12309 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
12310 Repair corrupt or damaged XFS filesystem on "device".
12312 The filesystem is specified using the "device" argument which should be
12314 the device name of the disk partition or volume containing the
12315 filesystem. If given the name of a block device, "xfs_repair" will
12316 attempt to find the raw device associated with the specified block
12317 device and will use the raw device instead.
12318 Regardless, the filesystem to be repaired must be unmounted, otherwise,
12320 the resulting filesystem may be inconsistent or corrupt.
12321 The returned status indicates whether filesystem corruption was
12323 detected (returns 1) or was not detected (returns 0).
12324 On error this function returns -1.
12326 (Added in 1.19.36)
12328 guestfs_xfs_repair_va
12330 int
12331 guestfs_xfs_repair_va (guestfs_h *g,
12332 const char *device,
12333 va_list args);
12334 This is the "va_list variant" of "guestfs_xfs_repair".
12336 See "CALLS WITH OPTIONAL ARGUMENTS".
12338 guestfs_xfs_repair_argv
12340 int
12341 guestfs_xfs_repair_argv (guestfs_h *g,
12342 const char *device,
12343 const struct guestfs_xfs_repair_argv *optargs);
12344 This is the "argv variant" of "guestfs_xfs_repair".
12346 See "CALLS WITH OPTIONAL ARGUMENTS".
12348 guestfs_zegrep
12350 char **
12351 guestfs_zegrep (guestfs_h *g,
12352 const char *regex,
12353 const char *path);
12354 This function is deprecated. In new code, use the "guestfs_grep" call
12356 instead.
12357 Deprecated functions will not be removed from the API, but the fact
12359 that they are deprecated indicates that there are problems with correct
12360 use of these functions.
12361 This calls the external "zegrep" program and returns the matching
12363 lines.
12364 This function returns a NULL-terminated array of strings (like
12366 environ(3)), or NULL if there was an error. The caller must free the
12367 strings and the array after use.
12368 Because of the message protocol, there is a transfer limit of somewhere
12370 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
12371 (Added in 1.0.66)
12373 guestfs_zegrepi
12375 char **
12376 guestfs_zegrepi (guestfs_h *g,
12377 const char *regex,
12378 const char *path);
12379 This function is deprecated. In new code, use the "guestfs_grep" call
12381 instead.
12382 Deprecated functions will not be removed from the API, but the fact
12384 that they are deprecated indicates that there are problems with correct
12385 use of these functions.
12386 This calls the external "zegrep -i" program and returns the matching
12388 lines.
12389 This function returns a NULL-terminated array of strings (like
12391 environ(3)), or NULL if there was an error. The caller must free the
12392 strings and the array after use.
12393 Because of the message protocol, there is a transfer limit of somewhere
12395 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
12396 (Added in 1.0.66)
12398 guestfs_zero
12400 int
12401 guestfs_zero (guestfs_h *g,
12402 const char *device);
12403 This command writes zeroes over the first few blocks of "device".
12405 How many blocks are zeroed isn't specified (but it's not enough to
12407 securely wipe the device). It should be sufficient to remove any
12408 partition tables, filesystem superblocks and so on.
12409 If blocks are already zero, then this command avoids writing zeroes.
12411 This prevents the underlying device from becoming non-sparse or growing
12412 unnecessarily.
12413 See also: "guestfs_zero_device", "guestfs_scrub_device",
12415 "guestfs_is_zero_device"
12416 This function returns 0 on success or -1 on error.
12418 This long-running command can generate progress notification messages
12420 so that the caller can display a progress bar or indicator. To receive
12421 these messages, the caller must register a progress event callback.
12422 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
12423 (Added in 1.0.16)
12425 guestfs_zero_device
12427 int
12428 guestfs_zero_device (guestfs_h *g,
12429 const char *device);
12430 This command writes zeroes over the entire "device". Compare with
12432 "guestfs_zero" which just zeroes the first few blocks of a device.
12433 If blocks are already zero, then this command avoids writing zeroes.
12435 This prevents the underlying device from becoming non-sparse or growing
12436 unnecessarily.
12437 This function returns 0 on success or -1 on error.
12439 This long-running command can generate progress notification messages
12441 so that the caller can display a progress bar or indicator. To receive
12442 these messages, the caller must register a progress event callback.
12443 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
12444 (Added in 1.3.1)
12446 guestfs_zero_free_space
12448 int
12449 guestfs_zero_free_space (guestfs_h *g,
12450 const char *directory);
12451 Zero the free space in the filesystem mounted on "directory". The
12453 filesystem must be mounted read-write.
12454 The filesystem contents are not affected, but any free space in the
12456 filesystem is freed.
12457 Free space is not "trimmed". You may want to call "guestfs_fstrim"
12459 either as an alternative to this, or after calling this, depending on
12460 your requirements.
12461 This function returns 0 on success or -1 on error.
12463 This long-running command can generate progress notification messages
12465 so that the caller can display a progress bar or indicator. To receive
12466 these messages, the caller must register a progress event callback.
12467 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
12468 (Added in 1.17.18)
12470 guestfs_zerofree
12472 int
12473 guestfs_zerofree (guestfs_h *g,
12474 const char *device);
12475 This runs the zerofree program on "device". This program claims to
12477 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
12478 it possible to compress the filesystem more effectively.
12479 You should not run this program if the filesystem is mounted.
12481 It is possible that using this program can damage the filesystem or
12483 data on the filesystem.
12484 This function returns 0 on success or -1 on error.
12486 (Added in 1.0.26)
12488 guestfs_zfgrep
12490 char **
12491 guestfs_zfgrep (guestfs_h *g,
12492 const char *pattern,
12493 const char *path);
12494 This function is deprecated. In new code, use the "guestfs_grep" call
12496 instead.
12497 Deprecated functions will not be removed from the API, but the fact
12499 that they are deprecated indicates that there are problems with correct
12500 use of these functions.
12501 This calls the external "zfgrep" program and returns the matching
12503 lines.
12504 This function returns a NULL-terminated array of strings (like
12506 environ(3)), or NULL if there was an error. The caller must free the
12507 strings and the array after use.
12508 Because of the message protocol, there is a transfer limit of somewhere
12510 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
12511 (Added in 1.0.66)
12513 guestfs_zfgrepi
12515 char **
12516 guestfs_zfgrepi (guestfs_h *g,
12517 const char *pattern,
12518 const char *path);
12519 This function is deprecated. In new code, use the "guestfs_grep" call
12521 instead.
12522 Deprecated functions will not be removed from the API, but the fact
12524 that they are deprecated indicates that there are problems with correct
12525 use of these functions.
12526 This calls the external "zfgrep -i" program and returns the matching
12528 lines.
12529 This function returns a NULL-terminated array of strings (like
12531 environ(3)), or NULL if there was an error. The caller must free the
12532 strings and the array after use.
12533 Because of the message protocol, there is a transfer limit of somewhere
12535 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
12536 (Added in 1.0.66)
12538 guestfs_zfile
12540 char *
12541 guestfs_zfile (guestfs_h *g,
12542 const char *meth,
12543 const char *path);
12544 This function is deprecated. In new code, use the "guestfs_file" call
12546 instead.
12547 Deprecated functions will not be removed from the API, but the fact
12549 that they are deprecated indicates that there are problems with correct
12550 use of these functions.
12551 This command runs "file" after first decompressing "path" using
12553 "method".
12554 "method" must be one of "gzip", "compress" or "bzip2".
12556 Since 1.0.63, use "guestfs_file" instead which can now process
12558 compressed files.
12559 This function returns a string, or NULL on error. The caller must free
12561 the returned string after use.
12562 (Added in 1.0.59)
12564 guestfs_zgrep
12566 char **
12567 guestfs_zgrep (guestfs_h *g,
12568 const char *regex,
12569 const char *path);
12570 This function is deprecated. In new code, use the "guestfs_grep" call
12572 instead.
12573 Deprecated functions will not be removed from the API, but the fact
12575 that they are deprecated indicates that there are problems with correct
12576 use of these functions.
12577 This calls the external "zgrep" program and returns the matching lines.
12579 This function returns a NULL-terminated array of strings (like
12581 environ(3)), or NULL if there was an error. The caller must free the
12582 strings and the array after use.
12583 Because of the message protocol, there is a transfer limit of somewhere
12585 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
12586 (Added in 1.0.66)
12588 guestfs_zgrepi
12590 char **
12591 guestfs_zgrepi (guestfs_h *g,
12592 const char *regex,
12593 const char *path);
12594 This function is deprecated. In new code, use the "guestfs_grep" call
12596 instead.
12597 Deprecated functions will not be removed from the API, but the fact
12599 that they are deprecated indicates that there are problems with correct
12600 use of these functions.
12601 This calls the external "zgrep -i" program and returns the matching
12603 lines.
12604 This function returns a NULL-terminated array of strings (like
12606 environ(3)), or NULL if there was an error. The caller must free the
12607 strings and the array after use.
12608 Because of the message protocol, there is a transfer limit of somewhere
12610 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
12611 (Added in 1.0.66)
12613
12615 guestfs_int_bool
12616 struct guestfs_int_bool {
12617 int32_t i;
12618 int32_t b;
12619 };
12620 struct guestfs_int_bool_list {
12622 uint32_t len; /* Number of elements in list. */
12623 struct guestfs_int_bool *val; /* Elements. */
12624 };
12625 void guestfs_free_int_bool (struct guestfs_free_int_bool *);
12627 void guestfs_free_int_bool_list (struct guestfs_free_int_bool_list *);
12628 guestfs_lvm_pv
12630 struct guestfs_lvm_pv {
12631 char *pv_name;
12632 /* The next field is NOT nul-terminated, be careful when printing it: */
12633 char pv_uuid[32];
12634 char *pv_fmt;
12635 uint64_t pv_size;
12636 uint64_t dev_size;
12637 uint64_t pv_free;
12638 uint64_t pv_used;
12639 char *pv_attr;
12640 int64_t pv_pe_count;
12641 int64_t pv_pe_alloc_count;
12642 char *pv_tags;
12643 uint64_t pe_start;
12644 int64_t pv_mda_count;
12645 uint64_t pv_mda_free;
12646 };
12647 struct guestfs_lvm_pv_list {
12649 uint32_t len; /* Number of elements in list. */
12650 struct guestfs_lvm_pv *val; /* Elements. */
12651 };
12652 void guestfs_free_lvm_pv (struct guestfs_free_lvm_pv *);
12654 void guestfs_free_lvm_pv_list (struct guestfs_free_lvm_pv_list *);
12655 guestfs_lvm_vg
12657 struct guestfs_lvm_vg {
12658 char *vg_name;
12659 /* The next field is NOT nul-terminated, be careful when printing it: */
12660 char vg_uuid[32];
12661 char *vg_fmt;
12662 char *vg_attr;
12663 uint64_t vg_size;
12664 uint64_t vg_free;
12665 char *vg_sysid;
12666 uint64_t vg_extent_size;
12667 int64_t vg_extent_count;
12668 int64_t vg_free_count;
12669 int64_t max_lv;
12670 int64_t max_pv;
12671 int64_t pv_count;
12672 int64_t lv_count;
12673 int64_t snap_count;
12674 int64_t vg_seqno;
12675 char *vg_tags;
12676 int64_t vg_mda_count;
12677 uint64_t vg_mda_free;
12678 };
12679 struct guestfs_lvm_vg_list {
12681 uint32_t len; /* Number of elements in list. */
12682 struct guestfs_lvm_vg *val; /* Elements. */
12683 };
12684 void guestfs_free_lvm_vg (struct guestfs_free_lvm_vg *);
12686 void guestfs_free_lvm_vg_list (struct guestfs_free_lvm_vg_list *);
12687 guestfs_lvm_lv
12689 struct guestfs_lvm_lv {
12690 char *lv_name;
12691 /* The next field is NOT nul-terminated, be careful when printing it: */
12692 char lv_uuid[32];
12693 char *lv_attr;
12694 int64_t lv_major;
12695 int64_t lv_minor;
12696 int64_t lv_kernel_major;
12697 int64_t lv_kernel_minor;
12698 uint64_t lv_size;
12699 int64_t seg_count;
12700 char *origin;
12701 /* The next field is [0..100] or -1 meaning 'not present': */
12702 float snap_percent;
12703 /* The next field is [0..100] or -1 meaning 'not present': */
12704 float copy_percent;
12705 char *move_pv;
12706 char *lv_tags;
12707 char *mirror_log;
12708 char *modules;
12709 };
12710 struct guestfs_lvm_lv_list {
12712 uint32_t len; /* Number of elements in list. */
12713 struct guestfs_lvm_lv *val; /* Elements. */
12714 };
12715 void guestfs_free_lvm_lv (struct guestfs_free_lvm_lv *);
12717 void guestfs_free_lvm_lv_list (struct guestfs_free_lvm_lv_list *);
12718 guestfs_stat
12720 struct guestfs_stat {
12721 int64_t dev;
12722 int64_t ino;
12723 int64_t mode;
12724 int64_t nlink;
12725 int64_t uid;
12726 int64_t gid;
12727 int64_t rdev;
12728 int64_t size;
12729 int64_t blksize;
12730 int64_t blocks;
12731 int64_t atime;
12732 int64_t mtime;
12733 int64_t ctime;
12734 };
12735 struct guestfs_stat_list {
12737 uint32_t len; /* Number of elements in list. */
12738 struct guestfs_stat *val; /* Elements. */
12739 };
12740 void guestfs_free_stat (struct guestfs_free_stat *);
12742 void guestfs_free_stat_list (struct guestfs_free_stat_list *);
12743 guestfs_statvfs
12745 struct guestfs_statvfs {
12746 int64_t bsize;
12747 int64_t frsize;
12748 int64_t blocks;
12749 int64_t bfree;
12750 int64_t bavail;
12751 int64_t files;
12752 int64_t ffree;
12753 int64_t favail;
12754 int64_t fsid;
12755 int64_t flag;
12756 int64_t namemax;
12757 };
12758 struct guestfs_statvfs_list {
12760 uint32_t len; /* Number of elements in list. */
12761 struct guestfs_statvfs *val; /* Elements. */
12762 };
12763 void guestfs_free_statvfs (struct guestfs_free_statvfs *);
12765 void guestfs_free_statvfs_list (struct guestfs_free_statvfs_list *);
12766 guestfs_dirent
12768 struct guestfs_dirent {
12769 int64_t ino;
12770 char ftyp;
12771 char *name;
12772 };
12773 struct guestfs_dirent_list {
12775 uint32_t len; /* Number of elements in list. */
12776 struct guestfs_dirent *val; /* Elements. */
12777 };
12778 void guestfs_free_dirent (struct guestfs_free_dirent *);
12780 void guestfs_free_dirent_list (struct guestfs_free_dirent_list *);
12781 guestfs_version
12783 struct guestfs_version {
12784 int64_t major;
12785 int64_t minor;
12786 int64_t release;
12787 char *extra;
12788 };
12789 struct guestfs_version_list {
12791 uint32_t len; /* Number of elements in list. */
12792 struct guestfs_version *val; /* Elements. */
12793 };
12794 void guestfs_free_version (struct guestfs_free_version *);
12796 void guestfs_free_version_list (struct guestfs_free_version_list *);
12797 guestfs_xattr
12799 struct guestfs_xattr {
12800 char *attrname;
12801 /* The next two fields describe a byte array. */
12802 uint32_t attrval_len;
12803 char *attrval;
12804 };
12805 struct guestfs_xattr_list {
12807 uint32_t len; /* Number of elements in list. */
12808 struct guestfs_xattr *val; /* Elements. */
12809 };
12810 void guestfs_free_xattr (struct guestfs_free_xattr *);
12812 void guestfs_free_xattr_list (struct guestfs_free_xattr_list *);
12813 guestfs_inotify_event
12815 struct guestfs_inotify_event {
12816 int64_t in_wd;
12817 uint32_t in_mask;
12818 uint32_t in_cookie;
12819 char *in_name;
12820 };
12821 struct guestfs_inotify_event_list {
12823 uint32_t len; /* Number of elements in list. */
12824 struct guestfs_inotify_event *val; /* Elements. */
12825 };
12826 void guestfs_free_inotify_event (struct guestfs_free_inotify_event *);
12828 void guestfs_free_inotify_event_list (struct guestfs_free_inotify_event_list *);
12829 guestfs_partition
12831 struct guestfs_partition {
12832 int32_t part_num;
12833 uint64_t part_start;
12834 uint64_t part_end;
12835 uint64_t part_size;
12836 };
12837 struct guestfs_partition_list {
12839 uint32_t len; /* Number of elements in list. */
12840 struct guestfs_partition *val; /* Elements. */
12841 };
12842 void guestfs_free_partition (struct guestfs_free_partition *);
12844 void guestfs_free_partition_list (struct guestfs_free_partition_list *);
12845 guestfs_application
12847 struct guestfs_application {
12848 char *app_name;
12849 char *app_display_name;
12850 int32_t app_epoch;
12851 char *app_version;
12852 char *app_release;
12853 char *app_install_path;
12854 char *app_trans_path;
12855 char *app_publisher;
12856 char *app_url;
12857 char *app_source_package;
12858 char *app_summary;
12859 char *app_description;
12860 };
12861 struct guestfs_application_list {
12863 uint32_t len; /* Number of elements in list. */
12864 struct guestfs_application *val; /* Elements. */
12865 };
12866 void guestfs_free_application (struct guestfs_free_application *);
12868 void guestfs_free_application_list (struct guestfs_free_application_list *);
12869 guestfs_application2
12871 struct guestfs_application2 {
12872 char *app2_name;
12873 char *app2_display_name;
12874 int32_t app2_epoch;
12875 char *app2_version;
12876 char *app2_release;
12877 char *app2_arch;
12878 char *app2_install_path;
12879 char *app2_trans_path;
12880 char *app2_publisher;
12881 char *app2_url;
12882 char *app2_source_package;
12883 char *app2_summary;
12884 char *app2_description;
12885 char *app2_spare1;
12886 char *app2_spare2;
12887 char *app2_spare3;
12888 char *app2_spare4;
12889 };
12890 struct guestfs_application2_list {
12892 uint32_t len; /* Number of elements in list. */
12893 struct guestfs_application2 *val; /* Elements. */
12894 };
12895 void guestfs_free_application2 (struct guestfs_free_application2 *);
12897 void guestfs_free_application2_list (struct guestfs_free_application2_list *);
12898 guestfs_isoinfo
12900 struct guestfs_isoinfo {
12901 char *iso_system_id;
12902 char *iso_volume_id;
12903 uint32_t iso_volume_space_size;
12904 uint32_t iso_volume_set_size;
12905 uint32_t iso_volume_sequence_number;
12906 uint32_t iso_logical_block_size;
12907 char *iso_volume_set_id;
12908 char *iso_publisher_id;
12909 char *iso_data_preparer_id;
12910 char *iso_application_id;
12911 char *iso_copyright_file_id;
12912 char *iso_abstract_file_id;
12913 char *iso_bibliographic_file_id;
12914 int64_t iso_volume_creation_t;
12915 int64_t iso_volume_modification_t;
12916 int64_t iso_volume_expiration_t;
12917 int64_t iso_volume_effective_t;
12918 };
12919 struct guestfs_isoinfo_list {
12921 uint32_t len; /* Number of elements in list. */
12922 struct guestfs_isoinfo *val; /* Elements. */
12923 };
12924 void guestfs_free_isoinfo (struct guestfs_free_isoinfo *);
12926 void guestfs_free_isoinfo_list (struct guestfs_free_isoinfo_list *);
12927 guestfs_mdstat
12929 struct guestfs_mdstat {
12930 char *mdstat_device;
12931 int32_t mdstat_index;
12932 char *mdstat_flags;
12933 };
12934 struct guestfs_mdstat_list {
12936 uint32_t len; /* Number of elements in list. */
12937 struct guestfs_mdstat *val; /* Elements. */
12938 };
12939 void guestfs_free_mdstat (struct guestfs_free_mdstat *);
12941 void guestfs_free_mdstat_list (struct guestfs_free_mdstat_list *);
12942 guestfs_btrfssubvolume
12944 struct guestfs_btrfssubvolume {
12945 uint64_t btrfssubvolume_id;
12946 uint64_t btrfssubvolume_top_level_id;
12947 char *btrfssubvolume_path;
12948 };
12949 struct guestfs_btrfssubvolume_list {
12951 uint32_t len; /* Number of elements in list. */
12952 struct guestfs_btrfssubvolume *val; /* Elements. */
12953 };
12954 void guestfs_free_btrfssubvolume (struct guestfs_free_btrfssubvolume *);
12956 void guestfs_free_btrfssubvolume_list (struct guestfs_free_btrfssubvolume_list *);
12957 guestfs_xfsinfo
12959 struct guestfs_xfsinfo {
12960 char *xfs_mntpoint;
12961 uint32_t xfs_inodesize;
12962 uint32_t xfs_agcount;
12963 uint32_t xfs_agsize;
12964 uint32_t xfs_sectsize;
12965 uint32_t xfs_attr;
12966 uint32_t xfs_blocksize;
12967 uint64_t xfs_datablocks;
12968 uint32_t xfs_imaxpct;
12969 uint32_t xfs_sunit;
12970 uint32_t xfs_swidth;
12971 uint32_t xfs_dirversion;
12972 uint32_t xfs_dirblocksize;
12973 uint32_t xfs_cimode;
12974 char *xfs_logname;
12975 uint32_t xfs_logblocksize;
12976 uint32_t xfs_logblocks;
12977 uint32_t xfs_logversion;
12978 uint32_t xfs_logsectsize;
12979 uint32_t xfs_logsunit;
12980 uint32_t xfs_lazycount;
12981 char *xfs_rtname;
12982 uint32_t xfs_rtextsize;
12983 uint64_t xfs_rtblocks;
12984 uint64_t xfs_rtextents;
12985 };
12986 struct guestfs_xfsinfo_list {
12988 uint32_t len; /* Number of elements in list. */
12989 struct guestfs_xfsinfo *val; /* Elements. */
12990 };
12991 void guestfs_free_xfsinfo (struct guestfs_free_xfsinfo *);
12993 void guestfs_free_xfsinfo_list (struct guestfs_free_xfsinfo_list *);
12994 guestfs_utsname
12996 struct guestfs_utsname {
12997 char *uts_sysname;
12998 char *uts_release;
12999 char *uts_version;
13000 char *uts_machine;
13001 };
13002 struct guestfs_utsname_list {
13004 uint32_t len; /* Number of elements in list. */
13005 struct guestfs_utsname *val; /* Elements. */
13006 };
13007 void guestfs_free_utsname (struct guestfs_free_utsname *);
13009 void guestfs_free_utsname_list (struct guestfs_free_utsname_list *);
13010 guestfs_hivex_node
13012 struct guestfs_hivex_node {
13013 int64_t hivex_node_h;
13014 };
13015 struct guestfs_hivex_node_list {
13017 uint32_t len; /* Number of elements in list. */
13018 struct guestfs_hivex_node *val; /* Elements. */
13019 };
13020 void guestfs_free_hivex_node (struct guestfs_free_hivex_node *);
13022 void guestfs_free_hivex_node_list (struct guestfs_free_hivex_node_list *);
13023 guestfs_hivex_value
13025 struct guestfs_hivex_value {
13026 int64_t hivex_value_h;
13027 };
13028 struct guestfs_hivex_value_list {
13030 uint32_t len; /* Number of elements in list. */
13031 struct guestfs_hivex_value *val; /* Elements. */
13032 };
13033 void guestfs_free_hivex_value (struct guestfs_free_hivex_value *);
13035 void guestfs_free_hivex_value_list (struct guestfs_free_hivex_value_list *);
13036
13038 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
13039 Using "guestfs_available" you can test availability of the following
13040 groups of functions. This test queries the appliance to see if the
13041 appliance you are currently using supports the functionality.
13042 acl The following functions: "guestfs_acl_delete_def_file"
13044 "guestfs_acl_get_file" "guestfs_acl_set_file"
13045 augeas
13047 The following functions: "guestfs_aug_clear" "guestfs_aug_close"
13048 "guestfs_aug_defnode" "guestfs_aug_defvar" "guestfs_aug_get"
13049 "guestfs_aug_init" "guestfs_aug_insert" "guestfs_aug_load"
13050 "guestfs_aug_ls" "guestfs_aug_match" "guestfs_aug_mv"
13051 "guestfs_aug_rm" "guestfs_aug_save" "guestfs_aug_set"
13052 btrfs
13054 The following functions: "guestfs_btrfs_device_add"
13055 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
13056 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_sync"
13057 "guestfs_btrfs_fsck" "guestfs_btrfs_set_seeding"
13058 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
13059 "guestfs_btrfs_subvolume_list"
13060 "guestfs_btrfs_subvolume_set_default"
13061 "guestfs_btrfs_subvolume_snapshot" "guestfs_mkfs_btrfs"
13062 fstrim
13064 The following functions: "guestfs_fstrim"
13065 gdisk
13067 The following functions: "guestfs_part_get_gpt_type"
13068 "guestfs_part_set_gpt_type"
13069 grub
13071 The following functions: "guestfs_grub_install"
13072 hivex
13074 The following functions: "guestfs_hivex_close"
13075 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
13076 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
13077 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
13078 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
13079 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
13080 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
13081 "guestfs_hivex_value_type" "guestfs_hivex_value_value"
13082 inotify
13084 The following functions: "guestfs_inotify_add_watch"
13085 "guestfs_inotify_close" "guestfs_inotify_files"
13086 "guestfs_inotify_init" "guestfs_inotify_read"
13087 "guestfs_inotify_rm_watch"
13088 ldm The following functions: "guestfs_ldmtool_create_all"
13090 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
13091 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
13092 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
13093 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
13094 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
13095 "guestfs_list_ldm_volumes"
13096 linuxcaps
13098 The following functions: "guestfs_cap_get_file"
13099 "guestfs_cap_set_file"
13100 linuxfsuuid
13102 The following functions: "guestfs_mke2fs_JU"
13103 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
13104 "guestfs_swapon_uuid"
13105 linuxmodules
13107 The following functions: "guestfs_modprobe"
13108 linuxxattrs
13110 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
13111 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
13112 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
13113 "guestfs_removexattr" "guestfs_setxattr"
13114 luks
13116 The following functions: "guestfs_luks_add_key"
13117 "guestfs_luks_close" "guestfs_luks_format"
13118 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
13119 "guestfs_luks_open" "guestfs_luks_open_ro"
13120 lvm2
13122 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
13123 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
13124 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
13125 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
13126 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
13127 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
13128 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
13129 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
13130 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
13131 "guestfs_vgs" "guestfs_vgs_full"
13132 mdadm
13134 The following functions: "guestfs_md_create" "guestfs_md_detail"
13135 "guestfs_md_stat" "guestfs_md_stop"
13136 mknod
13138 The following functions: "guestfs_mkfifo" "guestfs_mknod"
13139 "guestfs_mknod_b" "guestfs_mknod_c"
13140 ntfs3g
13142 The following functions: "guestfs_ntfs_3g_probe"
13143 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
13144 ntfsprogs
13146 The following functions: "guestfs_ntfsresize"
13147 "guestfs_ntfsresize_size"
13148 realpath
13150 The following functions: "guestfs_realpath"
13151 rsync
13153 The following functions: "guestfs_rsync" "guestfs_rsync_in"
13154 "guestfs_rsync_out"
13155 scrub
13157 The following functions: "guestfs_scrub_device"
13158 "guestfs_scrub_file" "guestfs_scrub_freespace"
13159 selinux
13161 The following functions: "guestfs_getcon" "guestfs_setcon"
13162 wipefs
13164 The following functions: "guestfs_wipefs"
13165 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
13167 "guestfs_xfs_info" "guestfs_xfs_repair"
13168 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
13170 zerofree
13172 The following functions: "guestfs_zerofree"
13173 FILESYSTEM AVAILABLE
13175 The "guestfs_filesystem_available" call tests whether a filesystem type
13176 is supported by the appliance kernel.
13177 This is mainly useful as a negative test. If this returns true, it
13179 doesn't mean that a particular filesystem can be mounted, since
13180 filesystems can fail for other reasons such as it being a later version
13181 of the filesystem, or having incompatible features.
13182 GUESTFISH supported COMMAND
13184 In guestfish(3) there is a handy interactive command "supported" which
13185 prints out the available groups and whether they are supported by this
13186 build of libguestfs. Note however that you have to do "run" first.
13187 SINGLE CALLS AT COMPILE TIME
13189 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
13190 function, such as:
13191 #define GUESTFS_HAVE_DD 1
13193 if "guestfs_dd" is available.
13195 Before version 1.5.8, if you needed to test whether a single libguestfs
13197 function is available at compile time, we recommended using build tools
13198 such as autoconf or cmake. For example in autotools you could use:
13199 AC_CHECK_LIB([guestfs],[guestfs_create])
13201 AC_CHECK_FUNCS([guestfs_dd])
13202 which would result in "HAVE_GUESTFS_DD" being either defined or not
13204 defined in your program.
13205 SINGLE CALLS AT RUN TIME
13207 Testing at compile time doesn't guarantee that a function really exists
13208 in the library. The reason is that you might be dynamically linked
13209 against a previous libguestfs.so (dynamic library) which doesn't have
13210 the call. This situation unfortunately results in a segmentation
13211 fault, which is a shortcoming of the C dynamic linking system itself.
13212 You can use dlopen(3) to test if a function is available at run time,
13214 as in this example program (note that you still need the compile time
13215 check as well):
13216 #include <stdio.h>
13218 #include <stdlib.h>
13219 #include <unistd.h>
13220 #include <dlfcn.h>
13221 #include <guestfs.h>
13222 main ()
13224 {
13225 #ifdef GUESTFS_HAVE_DD
13226 void *dl;
13227 int has_function;
13228 /* Test if the function guestfs_dd is really available. */
13230 dl = dlopen (NULL, RTLD_LAZY);
13231 if (!dl) {
13232 fprintf (stderr, "dlopen: %s\n", dlerror ());
13233 exit (EXIT_FAILURE);
13234 }
13235 has_function = dlsym (dl, "guestfs_dd") != NULL;
13236 dlclose (dl);
13237 if (!has_function)
13239 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
13240 else {
13241 printf ("this libguestfs.so has guestfs_dd function\n");
13242 /* Now it's safe to call
13243 guestfs_dd (g, "foo", "bar");
13244 */
13245 }
13246 #else
13247 printf ("guestfs_dd function was not found at compile time\n");
13248 #endif
13249 }
13250 You may think the above is an awful lot of hassle, and it is. There
13252 are other ways outside of the C linking system to ensure that this kind
13253 of incompatibility never arises, such as using package versioning:
13254 Requires: libguestfs >= 1.0.80
13256
13258 A recent feature of the API is the introduction of calls which take
13259 optional arguments. In C these are declared 3 ways. The main way is
13260 as a call which takes variable arguments (ie. "..."), as in this
13261 example:
13262 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
13264 Call this with a list of optional arguments, terminated by "-1". So to
13266 call with no optional arguments specified:
13267 guestfs_add_drive_opts (g, filename, -1);
13269 With a single optional argument:
13271 guestfs_add_drive_opts (g, filename,
13273 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
13274 -1);
13275 With two:
13277 guestfs_add_drive_opts (g, filename,
13279 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
13280 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
13281 -1);
13282 and so forth. Don't forget the terminating "-1" otherwise Bad Things
13284 will happen!
13285 USING va_list FOR OPTIONAL ARGUMENTS
13287 The second variant has the same name with the suffix "_va", which works
13288 the same way but takes a "va_list". See the C manual for details. For
13289 the example function, this is declared:
13290 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
13292 va_list args);
13293 CONSTRUCTING OPTIONAL ARGUMENTS
13295 The third variant is useful where you need to construct these calls.
13296 You pass in a structure where you fill in the optional fields. The
13297 structure has a bitmask as the first element which you must set to
13298 indicate which fields you have filled in. For our example function the
13299 structure and call are declared:
13300 struct guestfs_add_drive_opts_argv {
13302 uint64_t bitmask;
13303 int readonly;
13304 const char *format;
13305 /* ... */
13306 };
13307 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
13308 const struct guestfs_add_drive_opts_argv *optargs);
13309 You could call it like this:
13311 struct guestfs_add_drive_opts_argv optargs = {
13313 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
13314 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
13315 .readonly = 1,
13316 .format = "qcow2"
13317 };
13318 guestfs_add_drive_opts_argv (g, filename, &optargs);
13320 Notes:
13322 · The "_BITMASK" suffix on each option name when specifying the
13324 bitmask.
13325 · You do not need to fill in all fields of the structure.
13327 · There must be a one-to-one correspondence between fields of the
13329 structure that are filled in, and bits set in the bitmask.
13330 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
13332 In other languages, optional arguments are expressed in the way that is
13333 natural for that language. We refer you to the language-specific
13334 documentation for more details on that.
13335 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
13337
13339 SETTING CALLBACKS TO HANDLE EVENTS
13340 Note: This section documents the generic event mechanism introduced in
13341 libguestfs 1.10, which you should use in new code if possible. The old
13342 functions "guestfs_set_log_message_callback",
13343 "guestfs_set_subprocess_quit_callback",
13344 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
13345 "guestfs_set_progress_callback" are no longer documented in this manual
13346 page. Because of the ABI guarantee, the old functions continue to
13347 work.
13348 Handles generate events when certain things happen, such as log
13350 messages being generated, progress messages during long-running
13351 operations, or the handle being closed. The API calls described below
13352 let you register a callback to be called when events happen. You can
13353 register multiple callbacks (for the same, different or overlapping
13354 sets of events), and individually remove callbacks. If callbacks are
13355 not removed, then they remain in force until the handle is closed.
13356 In the current implementation, events are only generated synchronously:
13358 that means that events (and hence callbacks) can only happen while you
13359 are in the middle of making another libguestfs call. The callback is
13360 called in the same thread.
13361 Events may contain a payload, usually nothing (void), an array of 64
13363 bit unsigned integers, or a message buffer. Payloads are discussed
13364 later on.
13365 CLASSES OF EVENTS
13367 GUESTFS_EVENT_CLOSE (payload type: void)
13368 The callback function will be called while the handle is being
13369 closed (synchronously from "guestfs_close").
13370 Note that libguestfs installs an atexit(3) handler to try to clean
13372 up handles that are open when the program exits. This means that
13373 this callback might be called indirectly from exit(3), which can
13374 cause unexpected problems in higher-level languages (eg. if your
13375 HLL interpreter has already been cleaned up by the time this is
13376 called, and if your callback then jumps into some HLL function).
13377 If no callback is registered: the handle is closed without any
13379 callback being invoked.
13380 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
13382 The callback function will be called when the child process quits,
13383 either asynchronously or if killed by "guestfs_kill_subprocess".
13384 (This corresponds to a transition from any state to the CONFIG
13385 state).
13386 If no callback is registered: the event is ignored.
13388 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
13390 The callback function will be called when the child process becomes
13391 ready first time after it has been launched. (This corresponds to
13392 a transition from LAUNCHING to the READY state).
13393 If no callback is registered: the event is ignored.
13395 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
13397 Some long-running operations can generate progress messages. If
13398 this callback is registered, then it will be called each time a
13399 progress message is generated (usually two seconds after the
13400 operation started, and three times per second thereafter until it
13401 completes, although the frequency may change in future versions).
13402 The callback receives in the payload four unsigned 64 bit numbers
13404 which are (in order): "proc_nr", "serial", "position", "total".
13405 The units of "total" are not defined, although for some operations
13407 "total" may relate in some way to the amount of data to be
13408 transferred (eg. in bytes or megabytes), and "position" may be the
13409 portion which has been transferred.
13410 The only defined and stable parts of the API are:
13412 · The callback can display to the user some type of progress bar
13414 or indicator which shows the ratio of "position":"total".
13415 · 0 <= "position" <= "total"
13417 · If any progress notification is sent during a call, then a
13419 final progress notification is always sent when "position" =
13420 "total" (unless the call fails with an error).
13421 This is to simplify caller code, so callers can easily set the
13423 progress indicator to "100%" at the end of the operation,
13424 without requiring special code to detect this case.
13425 · For some calls we are unable to estimate the progress of the
13427 call, but we can still generate progress messages to indicate
13428 activity. This is known as "pulse mode", and is directly
13429 supported by certain progress bar implementations (eg.
13430 GtkProgressBar).
13431 For these calls, zero or more progress messages are generated
13433 with "position = 0" and "total = 1", followed by a final
13434 message with "position = total = 1".
13435 As noted above, if the call fails with an error then the final
13437 message may not be generated.
13438 The callback also receives the procedure number ("proc_nr") and
13440 serial number ("serial") of the call. These are only useful for
13441 debugging protocol issues, and the callback can normally ignore
13442 them. The callback may want to print these numbers in error
13443 messages or debugging messages.
13444 If no callback is registered: progress messages are discarded.
13446 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
13448 The callback function is called whenever a log message is generated
13449 by qemu, the appliance kernel, guestfsd (daemon), or utility
13450 programs.
13451 If the verbose flag ("guestfs_set_verbose") is set before launch
13453 ("guestfs_launch") then additional debug messages are generated.
13454 If no callback is registered: the messages are discarded unless the
13456 verbose flag is set in which case they are sent to stderr. You can
13457 override the printing of verbose messages to stderr by setting up a
13458 callback.
13459 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
13461 The callback function is called whenever a log message is generated
13462 by the library part of libguestfs.
13463 If the verbose flag ("guestfs_set_verbose") is set then additional
13465 debug messages are generated.
13466 If no callback is registered: the messages are discarded unless the
13468 verbose flag is set in which case they are sent to stderr. You can
13469 override the printing of verbose messages to stderr by setting up a
13470 callback.
13471 GUESTFS_EVENT_TRACE (payload type: message buffer)
13473 The callback function is called whenever a trace message is
13474 generated. This only applies if the trace flag
13475 ("guestfs_set_trace") is set.
13476 If no callback is registered: the messages are sent to stderr. You
13478 can override the printing of trace messages to stderr by setting up
13479 a callback.
13480 GUESTFS_EVENT_ENTER (payload type: function name)
13482 The callback function is called whenever a libguestfs function is
13483 entered.
13484 The payload is a string which contains the name of the function
13486 that we are entering (not including "guestfs_" prefix).
13487 Note that libguestfs functions can call themselves, so you may see
13489 many events from a single call. A few libguestfs functions do not
13490 generate this event.
13491 If no callback is registered: the event is ignored.
13493 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
13495 For any API function that opens a libvirt connection, this event
13496 may be generated to indicate that libvirt demands authentication
13497 information. See "LIBVIRT AUTHENTICATION" below.
13498 If no callback is registered: "virConnectAuthPtrDefault" is used
13500 (suitable for command-line programs only).
13501 EVENT API
13503 guestfs_set_event_callback
13504 int guestfs_set_event_callback (guestfs_h *g,
13506 guestfs_event_callback cb,
13507 uint64_t event_bitmask,
13508 int flags,
13509 void *opaque);
13510 This function registers a callback ("cb") for all event classes in the
13512 "event_bitmask".
13513 For example, to register for all log message events, you could call
13515 this function with the bitmask
13516 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY". To register a single
13517 callback for all possible classes of events, use "GUESTFS_EVENT_ALL".
13518 "flags" should always be passed as 0.
13520 "opaque" is an opaque pointer which is passed to the callback. You can
13522 use it for any purpose.
13523 The return value is the event handle (an integer) which you can use to
13525 delete the callback (see below).
13526 If there is an error, this function returns "-1", and sets the error in
13528 the handle in the usual way (see "guestfs_last_error" etc.)
13529 Callbacks remain in effect until they are deleted, or until the handle
13531 is closed.
13532 In the case where multiple callbacks are registered for a particular
13534 event class, all of the callbacks are called. The order in which
13535 multiple callbacks are called is not defined.
13536 guestfs_delete_event_callback
13538 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
13540 Delete a callback that was previously registered. "event_handle"
13542 should be the integer that was returned by a previous call to
13543 "guestfs_set_event_callback" on the same handle.
13544 guestfs_event_callback
13546 typedef void (*guestfs_event_callback) (
13548 guestfs_h *g,
13549 void *opaque,
13550 uint64_t event,
13551 int event_handle,
13552 int flags,
13553 const char *buf, size_t buf_len,
13554 const uint64_t *array, size_t array_len);
13555 This is the type of the event callback function that you have to
13557 provide.
13558 The basic parameters are: the handle ("g"), the opaque user pointer
13560 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
13561 handle, and "flags" which in the current API you should ignore.
13562 The remaining parameters contain the event payload (if any). Each
13564 event may contain a payload, which usually relates to the event class,
13565 but for future proofing your code should be written to handle any
13566 payload for any event class.
13567 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
13569 there is no message buffer). Note that this message buffer can contain
13570 arbitrary 8 bit data, including NUL bytes.
13571 "array" and "array_len" is an array of 64 bit unsigned integers. At
13573 the moment this is only used for progress messages.
13574 EXAMPLE: CAPTURING LOG MESSAGES
13576 A working program demonstrating this can be found in
13577 "examples/debug-logging.c" in the source of libguestfs.
13578 One motivation for the generic event API was to allow GUI programs to
13580 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
13581 unconditionally to "stderr".
13582 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
13584 "GUESTFS_EVENT_APPLIANCE" and "GUESTFS_EVENT_TRACE". (Note that error
13585 messages are not events; you must capture error messages separately).
13586 Programs have to set up a callback to capture the classes of events of
13588 interest:
13589 int eh =
13591 guestfs_set_event_callback
13592 (g, message_callback,
13593 GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_APPLIANCE|
13594 GUESTFS_EVENT_TRACE,
13595 0, NULL) == -1)
13596 if (eh == -1) {
13597 // handle error in the usual way
13598 }
13599 The callback can then direct messages to the appropriate place. In
13601 this example, messages are directed to syslog:
13602 static void
13604 message_callback (
13605 guestfs_h *g,
13606 void *opaque,
13607 uint64_t event,
13608 int event_handle,
13609 int flags,
13610 const char *buf, size_t buf_len,
13611 const uint64_t *array, size_t array_len)
13612 {
13613 const int priority = LOG_USER|LOG_INFO;
13614 if (buf_len > 0)
13615 syslog (priority, "event 0x%lx: %s", event, buf);
13616 }
13617 LIBVIRT AUTHENTICATION
13619 Some libguestfs API calls can open libvirt connections. Currently the
13620 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
13621 attach-method has been selected. Libvirt connections may require
13622 authentication, for example if they need to access a remote server or
13623 to access root services from non-root. Libvirt authentication happens
13624 via a callback mechanism, see
13625 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
13626 You may provide libvirt authentication data by registering a callback
13628 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
13629 If no such event is registered, then libguestfs uses a libvirt function
13631 that provides command-line prompts ("virConnectAuthPtrDefault"). This
13632 is only suitable for command-line libguestfs programs.
13633 To provide authentication, first call
13635 "guestfs_set_libvirt_supported_credentials" with the list of
13636 credentials your program knows how to provide. Second, register a
13637 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
13638 will be called when libvirt is requesting authentication information.
13639 In the event handler, call "guestfs_get_libvirt_requested_credentials"
13641 to get a list of the credentials that libvirt is asking for. You then
13642 need to ask (eg. the user) for each credential, and call
13643 "guestfs_set_libvirt_requested_credential" with the answer. Note that
13644 for each credential, additional information may be available via the
13645 calls "guestfs_get_libvirt_requested_credential_prompt",
13646 "guestfs_get_libvirt_requested_credential_challenge" or
13647 "guestfs_get_libvirt_requested_credential_defresult".
13648 The example program below should make this clearer.
13650 There is also a more substantial working example program supplied with
13652 the libguestfs sources, called "libvirt-auth.c".
13653 main ()
13655 {
13656 guestfs_h *g;
13657 char *creds[] = { "authname", "passphrase", NULL };
13658 int r, eh;
13659 g = guestfs_create ();
13661 if (!g) exit (EXIT_FAILURE);
13662 /* Tell libvirt what credentials the program supports. */
13664 r = guestfs_set_libvirt_supported_credentials (g, creds);
13665 if (r == -1)
13666 exit (EXIT_FAILURE);
13667 /* Set up the event handler. */
13669 eh = guestfs_set_event_callback (
13670 g, do_auth,
13671 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
13672 if (eh == -1)
13673 exit (EXIT_FAILURE);
13674 /* An example of a call that may ask for credentials. */
13676 r = guestfs_add_domain (
13677 g, "dom",
13678 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
13679 -1);
13680 if (r == -1)
13681 exit (EXIT_FAILURE);
13682 exit (EXIT_SUCCESS);
13684 }
13685 static void
13687 do_auth (guestfs_h *g,
13688 void *opaque,
13689 uint64_t event,
13690 int event_handle,
13691 int flags,
13692 const char *buf, size_t buf_len,
13693 const uint64_t *array, size_t array_len)
13694 {
13695 char **creds;
13696 size_t i;
13697 char *prompt;
13698 char *reply;
13699 size_t replylen;
13700 int r;
13701 // buf will be the libvirt URI. buf_len may be ignored.
13703 printf ("Authentication required for libvirt conn '%s'\n",
13704 buf);
13705 // Ask libguestfs what credentials libvirt is demanding.
13707 creds = guestfs_get_libvirt_requested_credentials (g);
13708 if (creds == NULL)
13709 exit (EXIT_FAILURE);
13710 // Now ask the user for answers.
13712 for (i = 0; creds[i] != NULL; ++i)
13713 {
13714 if (strcmp (creds[i], "authname") == 0 ||
13715 strcmp (creds[i], "passphrase") == 0)
13716 {
13717 prompt =
13718 guestfs_get_libvirt_requested_credential_prompt (g, i);
13719 if (prompt && strcmp (prompt, "") != 0)
13720 printf ("%s: ", prompt);
13721 free (prompt);
13722 // Some code here to ask for the credential.
13724 // ...
13725 // Put the reply in 'reply', length 'replylen' (bytes).
13726 r = guestfs_set_libvirt_requested_credential (g, i,
13728 reply, replylen);
13729 if (r == -1)
13730 exit (EXIT_FAILURE);
13731 }
13732 free (creds[i]);
13734 }
13735 free (creds);
13737 }
13738
13740 Some operations can be cancelled by the caller while they are in
13741 progress. Currently only operations that involve uploading or
13742 downloading data can be cancelled (technically: operations that have
13743 "FileIn" or "FileOut" parameters in the generator).
13744 To cancel the transfer, call "guestfs_user_cancel". For more
13746 information, read the description of "guestfs_user_cancel".
13747
13749 You can attach named pieces of private data to the libguestfs handle,
13750 fetch them by name, and walk over them, for the lifetime of the handle.
13751 This is called the private data area and is only available from the C
13752 API.
13753 To attach a named piece of data, use the following call:
13755 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
13757 "key" is the name to associate with this data, and "data" is an
13759 arbitrary pointer (which can be "NULL"). Any previous item with the
13760 same key is overwritten.
13761 You can use any "key" string you want, but avoid keys beginning with an
13763 underscore character (libguestfs uses those for its own internal
13764 purposes, such as implementing language bindings). It is recommended
13765 that you prefix the key with some unique string to avoid collisions
13766 with other users.
13767 To retrieve the pointer, use:
13769 void *guestfs_get_private (guestfs_h *g, const char *key);
13771 This function returns "NULL" if either no data is found associated with
13773 "key", or if the user previously set the "key"'s "data" pointer to
13774 "NULL".
13775 Libguestfs does not try to look at or interpret the "data" pointer in
13777 any way. As far as libguestfs is concerned, it need not be a valid
13778 pointer at all. In particular, libguestfs does not try to free the
13779 data when the handle is closed. If the data must be freed, then the
13780 caller must either free it before calling "guestfs_close" or must set
13781 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
13782 To walk over all entries, use these two functions:
13784 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
13786 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
13788 "guestfs_first_private" returns the first key, pointer pair ("first"
13790 does not have any particular meaning -- keys are not returned in any
13791 defined order). A pointer to the key is returned in *key_rtn and the
13792 corresponding data pointer is returned from the function. "NULL" is
13793 returned if there are no keys stored in the handle.
13794 "guestfs_next_private" returns the next key, pointer pair. The return
13796 value of this function is "NULL" if there are no further entries to
13797 return.
13798 Notes about walking over entries:
13800 · You must not call "guestfs_set_private" while walking over the
13802 entries.
13803 · The handle maintains an internal iterator which is reset when you
13805 call "guestfs_first_private". This internal iterator is
13806 invalidated when you call "guestfs_set_private".
13807 · If you have set the data pointer associated with a key to "NULL",
13809 ie:
13810 guestfs_set_private (g, key, NULL);
13812 then that "key" is not returned when walking.
13814 · *key_rtn is only valid until the next call to
13816 "guestfs_first_private", "guestfs_next_private" or
13817 "guestfs_set_private".
13818 The following example code shows how to print all keys and data
13820 pointers that are associated with the handle "g":
13821 const char *key;
13823 void *data = guestfs_first_private (g, &key);
13824 while (data != NULL)
13825 {
13826 printf ("key = %s, data = %p\n", key, data);
13827 data = guestfs_next_private (g, &key);
13828 }
13829 More commonly you are only interested in keys that begin with an
13831 application-specific prefix "foo_". Modify the loop like so:
13832 const char *key;
13834 void *data = guestfs_first_private (g, &key);
13835 while (data != NULL)
13836 {
13837 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
13838 printf ("key = %s, data = %p\n", key, data);
13839 data = guestfs_next_private (g, &key);
13840 }
13841 If you need to modify keys while walking, then you have to jump back to
13843 the beginning of the loop. For example, to delete all keys prefixed
13844 with "foo_":
13845 const char *key;
13847 void *data;
13848 again:
13849 data = guestfs_first_private (g, &key);
13850 while (data != NULL)
13851 {
13852 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
13853 {
13854 guestfs_set_private (g, key, NULL);
13855 /* note that 'key' pointer is now invalid, and so is
13856 the internal iterator */
13857 goto again;
13858 }
13859 data = guestfs_next_private (g, &key);
13860 }
13861 Note that the above loop is guaranteed to terminate because the keys
13863 are being deleted, but other manipulations of keys within the loop
13864 might not terminate unless you also maintain an indication of which
13865 keys have been visited.
13866
13868 The libguestfs C library can be probed using systemtap or DTrace. This
13869 is true of any library, not just libguestfs. However libguestfs also
13870 contains static markers to help in probing internal operations.
13871 You can list all the static markers by doing:
13873 stap -l 'process("/usr/lib*/libguestfs.so.0")
13875 .provider("guestfs").mark("*")'
13876 Note: These static markers are not part of the stable API and may
13878 change in future versions.
13879 SYSTEMTAP SCRIPT EXAMPLE
13881 This script contains examples of displaying both the static markers and
13882 some ordinary C entry points:
13883 global last;
13885 function display_time () {
13887 now = gettimeofday_us ();
13888 delta = 0;
13889 if (last > 0)
13890 delta = now - last;
13891 last = now;
13892 printf ("%d (+%d):", now, delta);
13894 }
13895 probe begin {
13897 last = 0;
13898 printf ("ready\n");
13899 }
13900 /* Display all calls to static markers. */
13902 probe process("/usr/lib*/libguestfs.so.0")
13903 .provider("guestfs").mark("*") ? {
13904 display_time();
13905 printf ("\t%s %s\n", $$name, $$parms);
13906 }
13907 /* Display all calls to guestfs_mkfs* functions. */
13909 probe process("/usr/lib*/libguestfs.so.0")
13910 .function("guestfs_mkfs*") ? {
13911 display_time();
13912 printf ("\t%s %s\n", probefunc(), $$parms);
13913 }
13914 The script above can be saved to "test.stap" and run using the stap(1)
13916 program. Note that you either have to be root, or you have to add
13917 yourself to several special stap groups. Consult the systemtap
13918 documentation for more information.
13919 # stap /tmp/test.stap
13921 ready
13922 In another terminal, run a guestfish command such as this:
13924 guestfish -N fs
13926 In the first terminal, stap trace output similar to this is shown:
13928 1318248056692655 (+0): launch_start
13930 1318248056692850 (+195): launch_build_appliance_start
13931 1318248056818285 (+125435): launch_build_appliance_end
13932 1318248056838059 (+19774): launch_run_qemu
13933 1318248061071167 (+4233108): launch_end
13934 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
13935
13937 Internally, libguestfs is implemented by running an appliance (a
13938 special type of small virtual machine) using qemu(1). Qemu runs as a
13939 child process of the main program.
13940 ___________________
13942 / \
13943 | main program |
13944 | |
13945 | | child process / appliance
13946 | | __________________________
13947 | | / qemu \
13948 +-------------------+ RPC | +-----------------+ |
13949 | libguestfs <--------------------> guestfsd | |
13950 | | | +-----------------+ |
13951 \___________________/ | | Linux kernel | |
13952 | +--^--------------+ |
13953 \_________|________________/
13954 |
13955 _______v______
13956 / \
13957 | Device or |
13958 | disk image |
13959 \______________/
13960 The library, linked to the main program, creates the child process and
13962 hence the appliance in the "guestfs_launch" function.
13963 Inside the appliance is a Linux kernel and a complete stack of
13965 userspace tools (such as LVM and ext2 programs) and a small controlling
13966 daemon called "guestfsd". The library talks to "guestfsd" using remote
13967 procedure calls (RPC). There is a mostly one-to-one correspondence
13968 between libguestfs API calls and RPC calls to the daemon. Lastly the
13969 disk image(s) are attached to the qemu process which translates device
13970 access by the appliance's Linux kernel into accesses to the image.
13971 A common misunderstanding is that the appliance "is" the virtual
13973 machine. Although the disk image you are attached to might also be
13974 used by some virtual machine, libguestfs doesn't know or care about
13975 this. (But you will care if both libguestfs's qemu process and your
13976 virtual machine are trying to update the disk image at the same time,
13977 since these usually results in massive disk corruption).
13978
13980 libguestfs uses a state machine to model the child process:
13981 |
13983 guestfs_create / guestfs_create_flags
13984 |
13985 |
13986 ____V_____
13987 / \
13988 | CONFIG |
13989 \__________/
13990 ^ ^ \
13991 | \ \ guestfs_launch
13992 | _\__V______
13993 | / \
13994 | | LAUNCHING |
13995 | \___________/
13996 | /
13997 | guestfs_launch
13998 | /
13999 __|____V
14000 / \
14001 | READY |
14002 \________/
14003 The normal transitions are (1) CONFIG (when the handle is created, but
14005 there is no child process), (2) LAUNCHING (when the child process is
14006 booting up), (3) READY meaning the appliance is up, actions can be
14007 issued to, and carried out by, the child process.
14008 The guest may be killed by "guestfs_kill_subprocess", or may die
14010 asynchronously at any time (eg. due to some internal error), and that
14011 causes the state to transition back to CONFIG.
14012 Configuration commands for qemu such as "guestfs_set_path" can only be
14014 issued when in the CONFIG state.
14015 The API offers one call that goes from CONFIG through LAUNCHING to
14017 READY. "guestfs_launch" blocks until the child process is READY to
14018 accept commands (or until some failure or timeout). "guestfs_launch"
14019 internally moves the state from CONFIG to LAUNCHING while it is
14020 running.
14021 API actions such as "guestfs_mount" can only be issued when in the
14023 READY state. These API calls block waiting for the command to be
14024 carried out. There are no non-blocking versions, and no way to issue
14025 more than one command per handle at the same time.
14026 Finally, the child process sends asynchronous messages back to the main
14028 program, such as kernel log messages. You can register a callback to
14029 receive these messages.
14030
14032 APPLIANCE BOOT PROCESS
14033 This process has evolved and continues to evolve. The description here
14034 corresponds only to the current version of libguestfs and is provided
14035 for information only.
14036 In order to follow the stages involved below, enable libguestfs
14038 debugging (set the environment variable "LIBGUESTFS_DEBUG=1").
14039 Create the appliance
14041 "supermin-helper" is invoked to create the kernel, a small initrd
14042 and the appliance.
14043 The appliance is cached in "/var/tmp/.guestfs-<UID>" (or in another
14045 directory if "LIBGUESTFS_CACHEDIR" or "TMPDIR" are set).
14046 For a complete description of how the appliance is created and
14048 cached, read the supermin(8) and supermin-helper(8) man pages.
14049 Start qemu and boot the kernel
14051 qemu is invoked to boot the kernel.
14052 Run the initrd
14054 "supermin-helper" builds a small initrd. The initrd is not the
14055 appliance. The purpose of the initrd is to load enough kernel
14056 modules in order that the appliance itself can be mounted and
14057 started.
14058 The initrd is a cpio archive called
14060 "/var/tmp/.guestfs-<UID>/initrd".
14061 When the initrd has started you will see messages showing that
14063 kernel modules are being loaded, similar to this:
14064 supermin: ext2 mini initrd starting up
14066 supermin: mounting /sys
14067 supermin: internal insmod libcrc32c.ko
14068 supermin: internal insmod crc32c-intel.ko
14069 Find and mount the appliance device
14071 The appliance is a sparse file containing an ext2 filesystem which
14072 contains a familiar (although reduced in size) Linux operating
14073 system. It would normally be called
14074 "/var/tmp/.guestfs-<UID>/root".
14075 The regular disks being inspected by libguestfs are the first
14077 devices exposed by qemu (eg. as "/dev/vda").
14078 The last disk added to qemu is the appliance itself (eg. "/dev/vdb"
14080 if there was only one regular disk).
14081 Thus the final job of the initrd is to locate the appliance disk,
14083 mount it, and switch root into the appliance, and run "/init" from
14084 the appliance.
14085 If this works successfully you will see messages such as:
14087 supermin: picked /sys/block/vdb/dev as root device
14089 supermin: creating /dev/root as block special 252:16
14090 supermin: mounting new root on /root
14091 supermin: chroot
14092 Starting /init script ...
14093 Note that "Starting /init script ..." indicates that the
14095 appliance's init script is now running.
14096 Initialize the appliance
14098 The appliance itself now initializes itself. This involves
14099 starting certain processes like "udev", possibly printing some
14100 debug information, and finally running the daemon ("guestfsd").
14101 The daemon
14103 Finally the daemon ("guestfsd") runs inside the appliance. If it
14104 runs you should see:
14105 verbose daemon enabled
14107 The daemon expects to see a named virtio-serial port exposed by
14109 qemu and connected on the other end to the library.
14110 The daemon connects to this port (and hence to the library) and
14112 sends a four byte message "GUESTFS_LAUNCH_FLAG", which initiates
14113 the communication protocol (see below).
14114 COMMUNICATION PROTOCOL
14116 Don't rely on using this protocol directly. This section documents how
14117 it currently works, but it may change at any time.
14118 The protocol used to talk between the library and the daemon running
14120 inside the qemu virtual machine is a simple RPC mechanism built on top
14121 of XDR (RFC 1014, RFC 1832, RFC 4506).
14122 The detailed format of structures is in "src/guestfs_protocol.x" (note:
14124 this file is automatically generated).
14125 There are two broad cases, ordinary functions that don't have any
14127 "FileIn" and "FileOut" parameters, which are handled with very simple
14128 request/reply messages. Then there are functions that have any
14129 "FileIn" or "FileOut" parameters, which use the same request and reply
14130 messages, but they may also be followed by files sent using a chunked
14131 encoding.
14132 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)
14134 For ordinary functions, the request message is:
14136 total length (header + arguments,
14138 but not including the length word itself)
14139 struct guestfs_message_header (encoded as XDR)
14140 struct guestfs_<foo>_args (encoded as XDR)
14141 The total length field allows the daemon to allocate a fixed size
14143 buffer into which it slurps the rest of the message. As a result, the
14144 total length is limited to "GUESTFS_MESSAGE_MAX" bytes (currently 4MB),
14145 which means the effective size of any request is limited to somewhere
14146 under this size.
14147 Note also that many functions don't take any arguments, in which case
14149 the "guestfs_foo_args" is completely omitted.
14150 The header contains the procedure number ("guestfs_proc") which is how
14152 the receiver knows what type of args structure to expect, or none at
14153 all.
14154 For functions that take optional arguments, the optional arguments are
14156 encoded in the "guestfs_foo_args" structure in the same way as ordinary
14157 arguments. A bitmask in the header indicates which optional arguments
14158 are meaningful. The bitmask is also checked to see if it contains bits
14159 set which the daemon does not know about (eg. if more optional
14160 arguments were added in a later version of the library), and this
14161 causes the call to be rejected.
14162 The reply message for ordinary functions is:
14164 total length (header + ret,
14166 but not including the length word itself)
14167 struct guestfs_message_header (encoded as XDR)
14168 struct guestfs_<foo>_ret (encoded as XDR)
14169 As above the "guestfs_foo_ret" structure may be completely omitted for
14171 functions that return no formal return values.
14172 As above the total length of the reply is limited to
14174 "GUESTFS_MESSAGE_MAX".
14175 In the case of an error, a flag is set in the header, and the reply
14177 message is slightly changed:
14178 total length (header + error,
14180 but not including the length word itself)
14181 struct guestfs_message_header (encoded as XDR)
14182 struct guestfs_message_error (encoded as XDR)
14183 The "guestfs_message_error" structure contains the error message as a
14185 string.
14186 FUNCTIONS THAT HAVE FILEIN PARAMETERS
14188 A "FileIn" parameter indicates that we transfer a file into the guest.
14190 The normal request message is sent (see above). However this is
14191 followed by a sequence of file chunks.
14192 total length (header + arguments,
14194 but not including the length word itself,
14195 and not including the chunks)
14196 struct guestfs_message_header (encoded as XDR)
14197 struct guestfs_<foo>_args (encoded as XDR)
14198 sequence of chunks for FileIn param #0
14199 sequence of chunks for FileIn param #1 etc.
14200 The "sequence of chunks" is:
14202 length of chunk (not including length word itself)
14204 struct guestfs_chunk (encoded as XDR)
14205 length of chunk
14206 struct guestfs_chunk (encoded as XDR)
14207 ...
14208 length of chunk
14209 struct guestfs_chunk (with data.data_len == 0)
14210 The final chunk has the "data_len" field set to zero. Additionally a
14212 flag is set in the final chunk to indicate either successful completion
14213 or early cancellation.
14214 At time of writing there are no functions that have more than one
14216 FileIn parameter. However this is (theoretically) supported, by
14217 sending the sequence of chunks for each FileIn parameter one after
14218 another (from left to right).
14219 Both the library (sender) and the daemon (receiver) may cancel the
14221 transfer. The library does this by sending a chunk with a special flag
14222 set to indicate cancellation. When the daemon sees this, it cancels
14223 the whole RPC, does not send any reply, and goes back to reading the
14224 next request.
14225 The daemon may also cancel. It does this by writing a special word
14227 "GUESTFS_CANCEL_FLAG" to the socket. The library listens for this
14228 during the transfer, and if it gets it, it will cancel the transfer (it
14229 sends a cancel chunk). The special word is chosen so that even if
14230 cancellation happens right at the end of the transfer (after the
14231 library has finished writing and has started listening for the reply),
14232 the "spurious" cancel flag will not be confused with the reply message.
14233 This protocol allows the transfer of arbitrary sized files (no 32 bit
14235 limit), and also files where the size is not known in advance (eg. from
14236 pipes or sockets). However the chunks are rather small
14237 ("GUESTFS_MAX_CHUNK_SIZE"), so that neither the library nor the daemon
14238 need to keep much in memory.
14239 FUNCTIONS THAT HAVE FILEOUT PARAMETERS
14241 The protocol for FileOut parameters is exactly the same as for FileIn
14243 parameters, but with the roles of daemon and library reversed.
14244 total length (header + ret,
14246 but not including the length word itself,
14247 and not including the chunks)
14248 struct guestfs_message_header (encoded as XDR)
14249 struct guestfs_<foo>_ret (encoded as XDR)
14250 sequence of chunks for FileOut param #0
14251 sequence of chunks for FileOut param #1 etc.
14252 INITIAL MESSAGE
14254 When the daemon launches it sends an initial word
14256 ("GUESTFS_LAUNCH_FLAG") which indicates that the guest and daemon is
14257 alive. This is what "guestfs_launch" waits for.
14258 PROGRESS NOTIFICATION MESSAGES
14260 The daemon may send progress notification messages at any time. These
14262 are distinguished by the normal length word being replaced by
14263 "GUESTFS_PROGRESS_FLAG", followed by a fixed size progress message.
14264 The library turns them into progress callbacks (see
14266 "GUESTFS_EVENT_PROGRESS") if there is a callback registered, or
14267 discards them if not.
14268 The daemon self-limits the frequency of progress messages it sends (see
14270 "daemon/proto.c:notify_progress"). Not all calls generate progress
14271 messages.
14272
14274 Since April 2010, libguestfs has started to make separate development
14275 and stable releases, along with corresponding branches in our git
14276 repository. These separate releases can be identified by version
14277 number:
14278 even numbers for stable: 1.2.x, 1.4.x, ...
14280 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
14281 |
14282 v
14283 1 . 3 . 5
14284 ^ ^
14285 | |
14286 | `-------- sub-version
14287 |
14288 `------ always '1' because we don't change the ABI
14289 Thus "1.3.5" is the 5th update to the development branch "1.3".
14291 As time passes we cherry pick fixes from the development branch and
14293 backport those into the stable branch, the effect being that the stable
14294 branch should get more stable and less buggy over time. So the stable
14295 releases are ideal for people who don't need new features but would
14296 just like the software to work.
14297 Our criteria for backporting changes are:
14299 · Documentation changes which don't affect any code are backported
14301 unless the documentation refers to a future feature which is not in
14302 stable.
14303 · Bug fixes which are not controversial, fix obvious problems, and
14305 have been well tested are backported.
14306 · Simple rearrangements of code which shouldn't affect how it works
14308 get backported. This is so that the code in the two branches
14309 doesn't get too far out of step, allowing us to backport future
14310 fixes more easily.
14311 · We don't backport new features, new APIs, new tools etc, except in
14313 one exceptional case: the new feature is required in order to
14314 implement an important bug fix.
14315 A new stable branch starts when we think the new features in
14317 development are substantial and compelling enough over the current
14318 stable branch to warrant it. When that happens we create new stable
14319 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
14320 oh release won't necessarily be so stable at this point, but by
14321 backporting fixes from development, that branch will stabilize over
14322 time.
14323
14325 This section is for hackers who want to extend libguestfs itself.
14326 OVERVIEW OF THE SOURCE CODE
14328 Libguestfs source is located in the github repository
14329 https://github.com/libguestfs/libguestfs
14330 Large amounts of boilerplate code in libguestfs (RPC, bindings,
14332 documentation) are generated. This means that many source files will
14333 appear to be missing from a straightforward git checkout. You have to
14334 run the generator ("./autogen.sh && make -C generator") in order to
14335 create those files.
14336 Libguestfs uses an autotools-based build system, with the main files
14338 being "configure.ac" and "Makefile.am". The "generator" subdirectory
14339 contains the generator, plus files describing the API. The "src"
14340 subdirectory contains source for the library. The "appliance" and
14341 "daemon" subdirectories contain the source for the code that builds the
14342 appliance, and the code that runs in the appliance respectively. Other
14343 directories are covered in the section "SOURCE CODE SUBDIRECTORIES"
14344 below.
14345 Apart from the fact that all API entry points go via some generated
14347 code, the library is straightforward. (In fact, even the generated
14348 code is designed to be readable, and should be read as ordinary code).
14349 Some actions run entirely in the library, and are written as C
14350 functions in files under "src". Others are forwarded to the daemon
14351 where (after some generated RPC marshalling) they appear as C functions
14352 in files under "daemon".
14353 To build from source, first read the "README" file.
14355 "local*" FILES
14357 Files in the top source directory that begin with the prefix "local*"
14358 are ignored by git. These files can contain local configuration or
14359 scripts that you need to build libguestfs.
14360 By convention, I have a file called "localconfigure" which is a simple
14362 wrapper around "autogen.sh" containing local configure customizations
14363 that I need:
14364 . localenv
14366 ./autogen.sh \
14367 --with-default-attach-method=libvirt \
14368 --enable-gcc-warnings \
14369 --enable-gtk-doc \
14370 -C \
14371 "$@"
14372 So I can use this to build libguestfs:
14374 ./localconfigure && make
14376 If there is a file in the top build directory called "localenv", then
14378 it will be sourced by "make". This file can contain any local
14379 environment variables needed, eg. for skipping tests:
14380 # Use an alternate python binary.
14382 export PYTHON=python3
14383 # Skip this test, it is broken.
14384 export SKIP_TEST_BTRFS_FSCK=1
14385 Note that "localenv" is included by the top Makefile (so it's a
14387 Makefile fragment). But if it is also sourced by your "localconfigure"
14388 script then it is used as a shell script.
14389 ADDING A NEW API ACTION
14391 Because large amounts of boilerplate code in libguestfs are generated,
14392 this makes it easy to extend the libguestfs API.
14393 To add a new API action there are two changes:
14395 1. You need to add a description of the call (name, parameters, return
14397 type, tests, documentation) to "generator/actions.ml".
14398 There are two sorts of API action, depending on whether the call
14400 goes through to the daemon in the appliance, or is serviced
14401 entirely by the library (see "ARCHITECTURE" above). "guestfs_sync"
14402 is an example of the former, since the sync is done in the
14403 appliance. "guestfs_set_trace" is an example of the latter, since
14404 a trace flag is maintained in the handle and all tracing is done on
14405 the library side.
14406 Most new actions are of the first type, and get added to the
14408 "daemon_functions" list. Each function has a unique procedure
14409 number used in the RPC protocol which is assigned to that action
14410 when we publish libguestfs and cannot be reused. Take the latest
14411 procedure number and increment it.
14412 For library-only actions of the second type, add to the
14414 "non_daemon_functions" list. Since these functions are serviced by
14415 the library and do not travel over the RPC mechanism to the daemon,
14416 these functions do not need a procedure number, and so the
14417 procedure number is set to "-1".
14418 2. Implement the action (in C):
14420 For daemon actions, implement the function "do_<name>" in the
14422 "daemon/" directory.
14423 For library actions, implement the function "guestfs__<name>"
14425 (note: double underscore) in the "src/" directory.
14426 In either case, use another function as an example of what to do.
14428 After making these changes, use "make" to compile.
14430 Note that you don't need to implement the RPC, language bindings,
14432 manual pages or anything else. It's all automatically generated from
14433 the OCaml description.
14434 ADDING TESTS FOR AN API ACTION
14436 You can supply zero or as many tests as you want per API call. The
14437 tests can either be added as part of the API description
14438 ("generator/actions.ml"), or in some rarer cases you may want to drop a
14439 script into "tests/*/". Note that adding a script to "tests/*/" is
14440 slower, so if possible use the first method.
14441 The following describes the test environment used when you add an API
14443 test in "actions.ml".
14444 The test environment has 4 block devices:
14446 "/dev/sda" 500MB
14448 General block device for testing.
14449 "/dev/sdb" 50MB
14451 "/dev/sdb1" is an ext2 filesystem used for testing filesystem write
14452 operations.
14453 "/dev/sdc" 10MB
14455 Used in a few tests where two block devices are needed.
14456 "/dev/sdd"
14458 ISO with fixed content (see "images/test.iso").
14459 To be able to run the tests in a reasonable amount of time, the
14461 libguestfs appliance and block devices are reused between tests. So
14462 don't try testing "guestfs_kill_subprocess" :-x
14463 Each test starts with an initial scenario, selected using one of the
14465 "Init*" expressions, described in "generator/types.ml". These
14466 initialize the disks mentioned above in a particular way as documented
14467 in "types.ml". You should not assume anything about the previous
14468 contents of other disks that are not initialized.
14469 You can add a prerequisite clause to any individual test. This is a
14471 run-time check, which, if it fails, causes the test to be skipped.
14472 Useful if testing a command which might not work on all variations of
14473 libguestfs builds. A test that has prerequisite of "Always" means to
14474 run unconditionally.
14475 In addition, packagers can skip individual tests by setting environment
14477 variables before running "make check".
14478 SKIP_TEST_<CMD>_<NUM>=1
14480 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command".
14482 or:
14484 SKIP_TEST_<CMD>=1
14486 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" tests.
14488 Packagers can run only certain tests by setting for example:
14490 TEST_ONLY="vfs_type zerofree"
14492 See "tests/c-api/tests.c" for more details of how these environment
14494 variables work.
14495 DEBUGGING NEW API ACTIONS
14497 Test new actions work before submitting them.
14498 You can use guestfish to try out new commands.
14500 Debugging the daemon is a problem because it runs inside a minimal
14502 environment. However you can fprintf messages in the daemon to stderr,
14503 and they will show up if you use "guestfish -v".
14504 FORMATTING CODE
14506 Our C source code generally adheres to some basic code-formatting
14507 conventions. The existing code base is not totally consistent on this
14508 front, but we do prefer that contributed code be formatted similarly.
14509 In short, use spaces-not-TABs for indentation, use 2 spaces for each
14510 indentation level, and other than that, follow the K&R style.
14511 If you use Emacs, add the following to one of one of your start-up
14513 files (e.g., ~/.emacs), to help ensure that you get indentation right:
14514 ;;; In libguestfs, indent with spaces everywhere (not TABs).
14516 ;;; Exceptions: Makefile and ChangeLog modes.
14517 (add-hook 'find-file-hook
14518 '(lambda () (if (and buffer-file-name
14519 (string-match "/libguestfs\\>"
14520 (buffer-file-name))
14521 (not (string-equal mode-name "Change Log"))
14522 (not (string-equal mode-name "Makefile")))
14523 (setq indent-tabs-mode nil))))
14524 ;;; When editing C sources in libguestfs, use this style.
14526 (defun libguestfs-c-mode ()
14527 "C mode with adjusted defaults for use with libguestfs."
14528 (interactive)
14529 (c-set-style "K&R")
14530 (setq c-indent-level 2)
14531 (setq c-basic-offset 2))
14532 (add-hook 'c-mode-hook
14533 '(lambda () (if (string-match "/libguestfs\\>"
14534 (buffer-file-name))
14535 (libguestfs-c-mode))))
14536 TESTING YOUR CHANGES
14538 Enable warnings when compiling (and fix any problems this finds):
14539 ./configure --enable-gcc-warnings
14541 Useful targets are:
14543 "make check"
14545 Runs the regular test suite.
14546 "make syntax-check -j1 -k"
14548 Checks for various syntax and style problems in the code.
14549 "make check-valgrind"
14551 Runs a subset of the test suite under valgrind.
14552 "make check-valgrind-local-guests"
14554 Runs a subset of the test suite under valgrind using locally
14555 installed libvirt guests (read-only).
14556 "make check-with-appliance"
14558 Runs all tests using default appliance back-end. This only has any
14559 effect if a non-default attach-method was selected using
14560 "./configure --with-default-attach-method=..."
14561 "make check-valgrind-with-appliance"
14563 Run a subset of the test suite under valgrind using the default
14564 appliance back-end.
14565 "make check-with-upstream-qemu"
14567 Runs all tests using a local qemu binary. It looks for the qemu
14568 binary in QEMUDIR (defaults to "$HOME/d/qemu"), but you can set
14569 this to another directory on the command line, eg:
14570 make check-with-upstream-qemu QEMUDIR=/usr/src/qemu
14572 "make check-with-upstream-libvirt"
14574 Runs all tests using a local libvirt. This only has any effect if
14575 the libvirt attach-method was selected using "./configure
14576 --with-default-attach-method=libvirt"
14577 It looks for libvirt in LIBVIRTDIR (defaults to "$HOME/d/libvirt"),
14579 but you can set this to another directory on the command line, eg:
14580 make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt
14582 "make check-slow"
14584 Runs some slow/long-running tests which are not run by default.
14585 "make extra-tests"
14587 Equivalent to running all "make check-*" rules (but not "make
14588 check").
14589 "make check-all"
14591 Equivalent to running all "make check*" rules.
14592 "make check-release"
14594 Runs a subset of "make check*" rules that are required to pass
14595 before a tarball can be released. Currently this is:
14596 · check
14598 · check-valgrind
14600 · check-direct
14602 · check-valgrind-direct
14604 · check-slow
14606 DAEMON CUSTOM PRINTF FORMATTERS
14608 In the daemon code we have created custom printf formatters %Q and %R,
14609 which are used to do shell quoting.
14610 %Q Simple shell quoted string. Any spaces or other shell characters
14612 are escaped for you.
14613 %R Same as %Q except the string is treated as a path which is prefixed
14615 by the sysroot.
14616 For example:
14618 asprintf (&cmd, "cat %R", path);
14620 would produce "cat /sysroot/some\ path\ with\ spaces"
14622 Note: Do not use these when you are passing parameters to the
14624 "command{,r,v,rv}()" functions. These parameters do NOT need to be
14625 quoted because they are not passed via the shell (instead, straight to
14626 exec). You probably want to use the "sysroot_path()" function however.
14627 SUBMITTING YOUR NEW API ACTIONS
14629 Submit patches to the mailing list:
14630 http://www.redhat.com/mailman/listinfo/libguestfs and CC to
14631 rjones@redhat.com.
14632 INTERNATIONALIZATION (I18N) SUPPORT
14634 We support i18n (gettext anyhow) in the library.
14635 However many messages come from the daemon, and we don't translate
14637 those at the moment. One reason is that the appliance generally has
14638 all locale files removed from it, because they take up a lot of space.
14639 So we'd have to readd some of those, as well as copying our PO files
14640 into the appliance.
14641 Debugging messages are never translated, since they are intended for
14643 the programmers.
14644 SOURCE CODE SUBDIRECTORIES
14646 "align"
14647 virt-alignment-scan(1) command and documentation.
14648 "appliance"
14650 The libguestfs appliance, build scripts and so on.
14651 "build-aux"
14653 Various build scripts used by autotools.
14654 "cat"
14656 The virt-cat(1), virt-filesystems(1) and virt-ls(1) commands and
14657 documentation.
14658 "contrib"
14660 Outside contributions, experimental parts.
14661 "daemon"
14663 The daemon that runs inside the libguestfs appliance and carries
14664 out actions.
14665 "df"
14667 virt-df(1) command and documentation.
14668 "edit"
14670 virt-edit(1) command and documentation.
14671 "examples"
14673 C API example code.
14674 "fish"
14676 guestfish(1), the command-line shell, and various shell scripts
14677 built on top such as virt-copy-in(1), virt-copy-out(1),
14678 virt-tar-in(1), virt-tar-out(1).
14679 "format"
14681 virt-format(1) command and documentation.
14682 "fuse"
14684 guestmount(1), FUSE (userspace filesystem) built on top of
14685 libguestfs.
14686 "generator"
14688 The crucially important generator, used to automatically generate
14689 large amounts of boilerplate C code for things like RPC and
14690 bindings.
14691 "gnulib"
14693 Gnulib is used as a portability library. A copy of gnulib is
14694 included under here.
14695 "html"
14697 Generated HTML manual pages.
14698 "inspector"
14700 virt-inspector(1), the virtual machine image inspector.
14701 "logo"
14703 Logo used on the website. The fish is called Arthur by the way.
14704 "m4"
14706 M4 macros used by autoconf.
14707 "po"
14709 Translations of simple gettext strings.
14710 "po-docs"
14712 The build infrastructure and PO files for translations of manpages
14713 and POD files. Eventually this will be combined with the "po"
14714 directory, but that is rather complicated.
14715 "rescue"
14717 virt-rescue(1) command and documentation.
14718 "resize"
14720 virt-resize(1) command and documentation.
14721 "sparsify"
14723 virt-sparsify(1) command and documentation.
14724 "src"
14726 Source code to the C library.
14727 "sysprep"
14729 virt-sysprep(1) command and documentation.
14730 "tests"
14732 Tests.
14733 "test-tool"
14735 Test tool for end users to test if their qemu/kernel combination
14736 will work with libguestfs.
14737 "tmp"
14739 Used for temporary files when running the tests (instead of "/tmp"
14740 etc). The reason is so that you can run multiple parallel tests of
14741 libguestfs without having one set of tests overwriting the
14742 appliance created by another.
14743 "tools"
14745 Command line tools written in Perl (virt-win-reg(1) and many
14746 others).
14747 "csharp"
14749 "erlang"
14750 "gobject"
14751 "haskell"
14752 "java"
14753 "lua"
14754 "ocaml"
14755 "php"
14756 "perl"
14757 "python"
14758 "ruby"
14759 Language bindings.
14760 MAKING A STABLE RELEASE
14762 When we make a stable release, there are several steps documented here.
14763 See "LIBGUESTFS VERSION NUMBERS" for general information about the
14764 stable branch policy.
14765 · Check "make && make check" works on at least Fedora, Debian and
14767 Ubuntu.
14768 · Finalize "guestfs-release-notes.pod"
14770 · Update ROADMAP.
14772 · Run "src/api-support/update-from-tarballs.sh".
14774 · Push and pull from Transifex.
14776 Run:
14778 tx push -s
14780 to push the latest POT files to Transifex. Then run:
14782 ./tx-pull.sh
14784 which is a wrapper to pull the latest translated "*.po" files.
14786 · Consider updating gnulib to latest upstream version.
14788 · Create new stable and development directories under
14790 http://libguestfs.org/download.
14791 · Edit "index.html.in" on website.
14793 · Create the branch in git:
14795 git tag -a 1.XX.0 -m "Version 1.XX.0 (stable)"
14797 git tag -a 1.YY.0 -m "Version 1.YY.0 (development)"
14798 git branch stable-1.XX
14799 git push origin tag 1.XX.0 1.YY.0 stable-1.XX
14800
14802 PROTOCOL LIMITS
14803 Internally libguestfs uses a message-based protocol to pass API calls
14804 and their responses to and from a small "appliance" (see "INTERNALS"
14805 for plenty more detail about this). The maximum message size used by
14806 the protocol is slightly less than 4 MB. For some API calls you may
14807 need to be aware of this limit. The API calls which may be affected
14808 are individually documented, with a link back to this section of the
14809 documentation.
14810 In libguestfs < 1.19.32, several calls had to encode either their
14812 entire argument list or their entire return value (or sometimes both)
14813 in a single protocol message, and this gave them an arbitrary
14814 limitation on how much data they could handle. For example,
14815 "guestfs_cat" could only download a file if it was less than around 4
14816 MB in size. In later versions of libguestfs, some of these limits have
14817 been removed. The APIs which were previously limited but are now
14818 unlimited (except perhaps by available memory) are listed below. To
14819 find out if a specific API is subject to protocol limits, check for the
14820 warning in the API documentation which links to this section, and
14821 remember to check the version of the documentation that matches the
14822 version of libguestfs you are using.
14823 "guestfs_cat", "guestfs_find", "guestfs_read_file",
14825 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
14826 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
14827 "guestfs_ls".
14828 See also "UPLOADING" and "DOWNLOADING" for further information about
14830 copying large amounts of data into or out of a filesystem.
14831 MAXIMUM NUMBER OF DISKS
14833 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
14834 may be added by calling "guestfs_max_disks". In earlier versions of
14835 libguestfs (ie. where this call is not available) you should assume the
14836 maximum is 25.
14837 The rest of this section covers implementation details, which could
14839 change in future.
14840 When using virtio-scsi disks (the default if available in qemu) the
14842 current limit is 255 disks. When using virtio-blk (the old default)
14843 the limit is around 27 disks, but may vary according to implementation
14844 details and whether the network is enabled.
14845 Virtio-scsi as used by libguestfs is configured to use one target per
14847 disk, and 256 targets are available.
14848 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
14850 31 slots, but some of these are used for other purposes.
14851 One virtual disk is used by libguestfs internally.
14853 Before libguestfs 1.19.7, disk names had to be a single character (eg.
14855 "/dev/sda" through "/dev/sdz"), and since one disk is reserved, that
14856 meant the limit was 25. This has been fixed in more recent versions.
14857 In libguestfs ≥ 1.20 it is possible to hot plug disks. See
14859 "HOTPLUGGING".
14860 MAXIMUM NUMBER OF PARTITIONS PER DISK
14862 Virtio limits the maximum number of partitions per disk to 15.
14863 This is because it reserves 4 bits for the minor device number (thus
14865 "/dev/vda", and "/dev/vda1" through "/dev/vda15").
14866 If you attach a disk with more than 15 partitions, the extra partitions
14868 are ignored by libguestfs.
14869 MAXIMUM SIZE OF A DISK
14871 Probably the limit is between 2**63-1 and 2**64-1 bytes.
14872 We have tested block devices up to 1 exabyte (2**60 or
14874 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
14875 host filesystem.
14876 Although libguestfs probably does not impose any limit, the underlying
14878 host storage will. If you store disk images on a host ext4 filesystem,
14879 then the maximum size will be limited by the maximum ext4 file size
14880 (currently 16 TB). If you store disk images as host logical volumes
14881 then you are limited by the maximum size of an LV.
14882 For the hugest disk image files, we recommend using XFS on the host for
14884 storage.
14885 MAXIMUM SIZE OF A PARTITION
14887 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
14888 numbers. Assuming a 512 byte sector size, this means that MBR cannot
14889 address a partition located beyond 2 TB on the disk.
14890 It is recommended that you use GPT partitions on disks which are larger
14892 than this size. GPT uses 64 bit sector numbers and so can address
14893 partitions which are theoretically larger than the largest disk we
14894 could support.
14895 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
14897 This depends on the filesystem type. libguestfs itself does not impose
14898 any known limit. Consult Wikipedia or the filesystem documentation to
14899 find out what these limits are.
14900 MAXIMUM UPLOAD AND DOWNLOAD
14902 The API functions "guestfs_upload", "guestfs_download",
14903 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
14904 uploads and downloads.
14905 INSPECTION LIMITS
14907 The inspection code has several arbitrary limits on things like the
14908 size of Windows Registry hive it will read, and the length of product
14909 name. These are intended to stop a malicious guest from consuming
14910 arbitrary amounts of memory and disk space on the host, and should not
14911 be reached in practice. See the source code for more information.
14912
14914 FEBOOTSTRAP_KERNEL
14915 FEBOOTSTRAP_MODULES
14916 When using supermin ≥ 4.1.0, these have been renamed
14917 "SUPERMIN_KERNEL" and "SUPERMIN_MODULES".
14918 LIBGUESTFS_APPEND
14920 Pass additional options to the guest kernel.
14921 LIBGUESTFS_ATTACH_METHOD
14923 Choose the default way to create the appliance. See
14924 "guestfs_set_attach_method" and "ATTACH METHOD".
14925 LIBGUESTFS_CACHEDIR
14927 The location where libguestfs will cache its appliance, when using
14928 a supermin appliance. The appliance is cached and shared between
14929 all handles which have the same effective user ID.
14930 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
14932 "TMPDIR" is not set, then "/var/tmp" is used.
14933 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
14935 LIBGUESTFS_DEBUG
14937 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
14938 same effect as calling "guestfs_set_verbose (g, 1)".
14939 LIBGUESTFS_MEMSIZE
14941 Set the memory allocated to the qemu process, in megabytes. For
14942 example:
14943 LIBGUESTFS_MEMSIZE=700
14945 LIBGUESTFS_PATH
14947 Set the path that libguestfs uses to search for a supermin
14948 appliance. See the discussion of paths in section "PATH" above.
14949 LIBGUESTFS_QEMU
14951 Set the default qemu binary that libguestfs uses. If not set, then
14952 the qemu which was found at compile time by the configure script is
14953 used.
14954 See also "QEMU WRAPPERS" above.
14956 LIBGUESTFS_TMPDIR
14958 The location where libguestfs will store temporary files used by
14959 each handle.
14960 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
14962 "TMPDIR" is not set, then "/tmp" is used.
14963 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
14965 LIBGUESTFS_TRACE
14967 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
14968 same effect as calling "guestfs_set_trace (g, 1)".
14969 PATH
14971 Libguestfs may run some external programs, and relies on $PATH
14972 being set to a reasonable value. If using the libvirt attach-
14973 method, libvirt will not work at all unless $PATH contains the path
14974 of qemu/KVM. Note that PHP by default removes $PATH from the
14975 environment which tends to break everything.
14976 SUPERMIN_KERNEL
14978 SUPERMIN_MODULES
14979 These two environment variables allow the kernel that libguestfs
14980 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
14981 set, then the most recent host kernel is chosen. For more
14982 information about kernel selection, see supermin-helper(8). This
14983 feature is only available in supermin / febootstrap ≥ 3.8.
14984 TMPDIR
14986 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
14987
14989 guestfs-examples(3), guestfs-erlang(3), guestfs-java(3),
14990 guestfs-lua(3), guestfs-ocaml(3), guestfs-perl(3), guestfs-python(3),
14991 guestfs-ruby(3), guestfish(1), guestmount(1), virt-alignment-scan(1),
14992 virt-cat(1), virt-copy-in(1), virt-copy-out(1), virt-df(1),
14993 virt-edit(1), virt-filesystems(1), virt-format(1), virt-inspector(1),
14994 virt-list-filesystems(1), virt-list-partitions(1), virt-ls(1),
14995 virt-make-fs(1), virt-rescue(1), virt-resize(1), virt-sparsify(1),
14996 virt-sysprep(1), virt-tar(1), virt-tar-in(1), virt-tar-out(1),
14997 virt-win-reg(1), guestfs-faq(1), guestfs-performance(1),
14998 guestfs-release-notes(1), guestfs-testing(1), libguestfs-test-tool(1),
14999 libguestfs-make-fixed-appliance(1), supermin(8), supermin-helper(8),
15000 qemu(1), hivex(3), stap(1), http://libguestfs.org/.
15001 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
15003 disktype(1).
15004
15006 Richard W.M. Jones ("rjones at redhat dot com")
15007
15009 Copyright (C) 2009-2013 Red Hat Inc.
15010
15012 This library is free software; you can redistribute it and/or modify it
15013 under the terms of the GNU Lesser General Public License as published
15014 by the Free Software Foundation; either version 2 of the License, or
15015 (at your option) any later version.
15016 This library is distributed in the hope that it will be useful, but
15018 WITHOUT ANY WARRANTY; without even the implied warranty of
15019 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15020 Lesser General Public License for more details.
15021 You should have received a copy of the GNU Lesser General Public
15023 License along with this library; if not, write to the Free Software
15024 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
15025 02110-1301 USA
15026
15028 To get a list of bugs against libguestfs, use this link:
15029 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
15030 To report a new bug against libguestfs, use this link:
15032 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
15033 When reporting a bug, please supply:
15035 · The version of libguestfs.
15037 · Where you got libguestfs (eg. which Linux distro, compiled from
15039 source, etc)
15040 · Describe the bug accurately and give a way to reproduce it.
15042 · Run libguestfs-test-tool(1) and paste the complete, unedited output
15044 into the bug report.
15045libguestfs-1.20.11 2013-08-27 guestfs(3)