1guestfs(3)                  Virtualization Support                  guestfs(3)
2
3
4

NAME

6       guestfs - Library for accessing and modifying virtual machine images
7

SYNOPSIS

9        #include <guestfs.h>
10
11        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
20        cc prog.c -o prog -lguestfs
21       or:
22        cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
23

DESCRIPTION

25       Libguestfs is a library for accessing and modifying disk images and
26       virtual machines.
27
28       This manual page documents the C API.
29
30       If you are looking for an introduction to libguestfs, see the web site:
31       http://libguestfs.org/
32
33       Each virt tool has its own man page (for a full list, go to "SEE ALSO"
34       at the end of this file).
35
36       Other libguestfs manual pages:
37
38       guestfs-faq(1)
39           Frequently Asked Questions (FAQ).
40
41       guestfs-examples(3)
42           Examples of using the API from C.  For examples in other languages,
43           see "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES" below.
44
45       guestfs-recipes(1)
46           Tips and recipes.
47
48       guestfs-performance(1)
49           Performance tips and solutions.
50
51       libguestfs-test-tool(1)
52       guestfs-testing(1)
53           Help testing libguestfs.
54
55       guestfs-building(1)
56           How to build libguestfs from source.
57
58       guestfs-hacking(1)
59           Contribute code to libguestfs.
60
61       guestfs-internals(1)
62           How libguestfs works.
63
64       guestfs-security(1)
65           Security information, including CVEs affecting libguestfs.
66

API OVERVIEW

68       This section provides a gentler overview of the libguestfs API.  We
69       also try to group API calls together, where that may not be obvious
70       from reading about the individual calls in the main section of this
71       manual.
72
73   HANDLES
74       Before you can use libguestfs calls, you have to create a handle.  Then
75       you must add at least one disk image to the handle, followed by
76       launching the handle, then performing whatever operations you want, and
77       finally closing the handle.  By convention we use the single letter "g"
78       for the name of the handle variable, although of course you can use any
79       name you want.
80
81       The general structure of all libguestfs-using programs looks like this:
82
83        guestfs_h *g = guestfs_create ();
84
85        /* Call guestfs_add_drive additional times if there are
86         * multiple disk images.
87         */
88        guestfs_add_drive (g, "guest.img");
89
90        /* Most manipulation calls won't work until you've launched
91         * the handle 'g'.  You have to do this _after_ adding drives
92         * and _before_ other commands.
93         */
94        guestfs_launch (g);
95
96        /* Either: examine what partitions, LVs etc are available: */
97        char **partitions = guestfs_list_partitions (g);
98        char **logvols = guestfs_lvs (g);
99
100        /* Or: ask libguestfs to find filesystems for you: */
101        char **filesystems = guestfs_list_filesystems (g);
102
103        /* Or: use inspection (see INSPECTION section below). */
104
105        /* To access a filesystem in the image, you must mount it. */
106        guestfs_mount (g, "/dev/sda1", "/");
107
108        /* Now you can perform filesystem actions on the guest
109         * disk image.
110         */
111        guestfs_touch (g, "/hello");
112
113        /* Synchronize the disk.  This is the opposite of guestfs_launch. */
114        guestfs_shutdown (g);
115
116        /* Close and free the handle 'g'. */
117        guestfs_close (g);
118
119       The code above doesn't include any error checking.  In real code you
120       should check return values carefully for errors.  In general all
121       functions that return integers return "-1" on error, and all functions
122       that return pointers return "NULL" on error.  See section "ERROR
123       HANDLING" below for how to handle errors, and consult the documentation
124       for each function call below to see precisely how they return error
125       indications.
126
127       The code above does not free(3) the strings and arrays returned from
128       functions.  Consult the documentation for each function to find out how
129       to free the return value.
130
131       See guestfs-examples(3) for fully worked examples.
132
133   DISK IMAGES
134       The image filename ("guest.img" in the example above) could be a disk
135       image from a virtual machine, a dd(1) copy of a physical hard disk, an
136       actual block device, or simply an empty file of zeroes that you have
137       created through posix_fallocate(3).  Libguestfs lets you do useful
138       things to all of these.
139
140       The call you should use in modern code for adding drives is
141       "guestfs_add_drive_opts".  To add a disk image, allowing writes, and
142       specifying that the format is raw, do:
143
144        guestfs_add_drive_opts (g, filename,
145                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
146                                -1);
147
148       You can add a disk read-only using:
149
150        guestfs_add_drive_opts (g, filename,
151                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
152                                GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
153                                -1);
154
155       or by calling the older function "guestfs_add_drive_ro".  If you use
156       the readonly flag, libguestfs won't modify the file.  (See also "DISK
157       IMAGE FORMATS" below).
158
159       Be extremely cautious if the disk image is in use, eg. if it is being
160       used by a virtual machine.  Adding it read-write will almost certainly
161       cause disk corruption, but adding it read-only is safe.
162
163       You should usually add at least one disk image, and you may add
164       multiple disk images.  If adding multiple disk images, they usually
165       have to be "related", ie. from the same guest.  In the API, the disk
166       images are usually referred to as /dev/sda (for the first one you
167       added), /dev/sdb (for the second one you added), etc.
168
169       Once "guestfs_launch" has been called you cannot add any more images.
170       You can call "guestfs_list_devices" to get a list of the device names,
171       in the order that you added them.  See also "BLOCK DEVICE NAMING"
172       below.
173
174       There are slightly different rules when hotplugging disks (in
175       libguestfs ≥ 1.20).  See "HOTPLUGGING" below.
176
177   MOUNTING
178       Before you can read or write files, create directories and so on in a
179       disk image that contains filesystems, you have to mount those
180       filesystems using "guestfs_mount" or "guestfs_mount_ro".  If you
181       already know that a disk image contains (for example) one partition
182       with a filesystem on that partition, then you can mount it directly:
183
184        guestfs_mount (g, "/dev/sda1", "/");
185
186       where /dev/sda1 means literally the first partition (1) of the first
187       disk image that we added (/dev/sda).  If the disk contains Linux LVM2
188       logical volumes you could refer to those instead (eg. /dev/VG/LV).
189       Note that these are libguestfs virtual devices, and are nothing to do
190       with host devices.
191
192       If you are given a disk image and you don’t know what it contains then
193       you have to find out.  Libguestfs can do that too: use
194       "guestfs_list_partitions" and "guestfs_lvs" to list possible partitions
195       and LVs, and either try mounting each to see what is mountable, or else
196       examine them with "guestfs_vfs_type" or "guestfs_file".  To list just
197       filesystems, use "guestfs_list_filesystems".
198
199       Libguestfs also has a set of APIs for inspection of unknown disk images
200       (see "INSPECTION" below).  You might also want to look at higher level
201       programs built on top of libguestfs, in particular virt-inspector(1).
202
203       To mount a filesystem read-only, use "guestfs_mount_ro".  There are
204       several other variations of the "guestfs_mount_*" call.
205
206   FILESYSTEM ACCESS AND MODIFICATION
207       The majority of the libguestfs API consists of fairly low-level calls
208       for accessing and modifying the files, directories, symlinks etc on
209       mounted filesystems.  There are over a hundred such calls which you can
210       find listed in detail below in this man page, and we don't even pretend
211       to cover them all in this overview.
212
213       Specify filenames as full paths, starting with "/" and including the
214       mount point.
215
216       For example, if you mounted a filesystem at "/" and you want to read
217       the file called "etc/passwd" then you could do:
218
219        char *data = guestfs_cat (g, "/etc/passwd");
220
221       This would return "data" as a newly allocated buffer containing the
222       full content of that file (with some conditions: see also "DOWNLOADING"
223       below), or "NULL" if there was an error.
224
225       As another example, to create a top-level directory on that filesystem
226       called "var" you would do:
227
228        guestfs_mkdir (g, "/var");
229
230       To create a symlink you could do:
231
232        guestfs_ln_s (g, "/etc/init.d/portmap",
233                      "/etc/rc3.d/S30portmap");
234
235       Libguestfs will reject attempts to use relative paths and there is no
236       concept of a current working directory.
237
238       Libguestfs can return errors in many situations: for example if the
239       filesystem isn't writable, or if a file or directory that you requested
240       doesn't exist.  If you are using the C API (documented here) you have
241       to check for those error conditions after each call.  (Other language
242       bindings turn these errors into exceptions).
243
244       File writes are affected by the per-handle umask, set by calling
245       "guestfs_umask" and defaulting to 022.  See "UMASK".
246
247       Since libguestfs 1.18, it is possible to mount the libguestfs
248       filesystem on a local directory, subject to some restrictions.  See
249       "MOUNT LOCAL" below.
250
251   PARTITIONING
252       Libguestfs contains API calls to read, create and modify partition
253       tables on disk images.
254
255       In the common case where you want to create a single partition covering
256       the whole disk, you should use the "guestfs_part_disk" call:
257
258        const char *parttype = "mbr";
259        if (disk_is_larger_than_2TB)
260          parttype = "gpt";
261        guestfs_part_disk (g, "/dev/sda", parttype);
262
263       Obviously this effectively wipes anything that was on that disk image
264       before.
265
266   LVM2
267       Libguestfs provides access to a large part of the LVM2 API, such as
268       "guestfs_lvcreate" and "guestfs_vgremove".  It won't make much sense
269       unless you familiarize yourself with the concepts of physical volumes,
270       volume groups and logical volumes.
271
272       This author strongly recommends reading the LVM HOWTO, online at
273       http://tldp.org/HOWTO/LVM-HOWTO/.
274
275   DOWNLOADING
276       Use "guestfs_cat" to download small, text only files.  This call cannot
277       handle files containing any ASCII NUL ("\0") characters.  However the
278       API is very simple to use.
279
280       "guestfs_read_file" can be used to read files which contain arbitrary 8
281       bit data, since it returns a (pointer, size) pair.
282
283       "guestfs_download" can be used to download any file, with no limits on
284       content or size.
285
286       To download multiple files, see "guestfs_tar_out" and
287       "guestfs_tgz_out".
288
289   UPLOADING
290       To write a small file with fixed content, use "guestfs_write".  To
291       create a file of all zeroes, use "guestfs_truncate_size" (sparse) or
292       "guestfs_fallocate64" (with all disk blocks allocated).  There are a
293       variety of other functions for creating test files, for example
294       "guestfs_fill" and "guestfs_fill_pattern".
295
296       To upload a single file, use "guestfs_upload".  This call has no limits
297       on file content or size.
298
299       To upload multiple files, see "guestfs_tar_in" and "guestfs_tgz_in".
300
301       However the fastest way to upload large numbers of arbitrary files is
302       to turn them into a squashfs or CD ISO (see mksquashfs(8) and
303       mkisofs(8)), then attach this using "guestfs_add_drive_ro".  If you add
304       the drive in a predictable way (eg. adding it last after all other
305       drives) then you can get the device name from "guestfs_list_devices"
306       and mount it directly using "guestfs_mount_ro".  Note that squashfs
307       images are sometimes non-portable between kernel versions, and they
308       don't support labels or UUIDs.  If you want to pre-build an image or
309       you need to mount it using a label or UUID, use an ISO image instead.
310
311   COPYING
312       There are various different commands for copying between files and
313       devices and in and out of the guest filesystem.  These are summarised
314       in the table below.
315
316       file to file
317           Use "guestfs_cp" to copy a single file, or "guestfs_cp_a" to copy
318           directories recursively.
319
320           To copy part of a file (offset and size) use
321           "guestfs_copy_file_to_file".
322
323       file to device
324       device to file
325       device to device
326           Use "guestfs_copy_file_to_device", "guestfs_copy_device_to_file",
327           or "guestfs_copy_device_to_device".
328
329           Example: duplicate the contents of an LV:
330
331            guestfs_copy_device_to_device (g,
332                    "/dev/VG/Original", "/dev/VG/Copy",
333                    /* -1 marks the end of the list of optional parameters */
334                    -1);
335
336           The destination (/dev/VG/Copy) must be at least as large as the
337           source (/dev/VG/Original).  To copy less than the whole source
338           device, use the optional "size" parameter:
339
340            guestfs_copy_device_to_device (g,
341                    "/dev/VG/Original", "/dev/VG/Copy",
342                    GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
343                    -1);
344
345       file on the host to file or device
346           Use "guestfs_upload".  See "UPLOADING" above.
347
348       file or device to file on the host
349           Use "guestfs_download".  See "DOWNLOADING" above.
350
351   UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
352       Calls like "guestfs_upload", "guestfs_download", "guestfs_tar_in",
353       "guestfs_tar_out" etc appear to only take filenames as arguments, so it
354       appears you can only upload and download to files.  However many
355       Un*x-like hosts let you use the special device files /dev/stdin,
356       /dev/stdout, /dev/stderr and /dev/fd/N to read and write from stdin,
357       stdout, stderr, and arbitrary file descriptor N.
358
359       For example, virt-cat(1) writes its output to stdout by doing:
360
361        guestfs_download (g, filename, "/dev/stdout");
362
363       and you can write tar output to a file descriptor "fd" by doing:
364
365        char devfd[64];
366        snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
367        guestfs_tar_out (g, "/", devfd);
368
369   LISTING FILES
370       "guestfs_ll" is just designed for humans to read (mainly when using the
371       guestfish(1)-equivalent command "ll").
372
373       "guestfs_ls" is a quick way to get a list of files in a directory from
374       programs, as a flat list of strings.
375
376       "guestfs_readdir" is a programmatic way to get a list of files in a
377       directory, plus additional information about each one.  It is more
378       equivalent to using the readdir(3) call on a local filesystem.
379
380       "guestfs_find" and "guestfs_find0" can be used to recursively list
381       files.
382
383   RUNNING COMMANDS
384       Although libguestfs is primarily an API for manipulating files inside
385       guest images, we also provide some limited facilities for running
386       commands inside guests.
387
388       There are many limitations to this:
389
390       ·   The kernel version that the command runs under will be different
391           from what it expects.
392
393       ·   If the command needs to communicate with daemons, then most likely
394           they won't be running.
395
396       ·   The command will be running in limited memory.
397
398       ·   The network may not be available unless you enable it (see
399           "guestfs_set_network").
400
401       ·   Only supports Linux guests (not Windows, BSD, etc).
402
403       ·   Architecture limitations (eg. won’t work for a PPC guest on an X86
404           host).
405
406       ·   For SELinux guests, you may need to relabel the guest after
407           creating new files.  See "SELINUX" below.
408
409       ·   Security: It is not safe to run commands from untrusted, possibly
410           malicious guests.  These commands may attempt to exploit your
411           program by sending unexpected output.  They could also try to
412           exploit the Linux kernel or qemu provided by the libguestfs
413           appliance.  They could use the network provided by the libguestfs
414           appliance to bypass ordinary network partitions and firewalls.
415           They could use the elevated privileges or different SELinux context
416           of your program to their advantage.
417
418           A secure alternative is to use libguestfs to install a "firstboot"
419           script (a script which runs when the guest next boots normally),
420           and to have this script run the commands you want in the normal
421           context of the running guest, network security and so on.  For
422           information about other security issues, see guestfs-security(1).
423
424       The two main API calls to run commands are "guestfs_command" and
425       "guestfs_sh" (there are also variations).
426
427       The difference is that "guestfs_sh" runs commands using the shell, so
428       any shell globs, redirections, etc will work.
429
430   CONFIGURATION FILES
431       To read and write configuration files in Linux guest filesystems, we
432       strongly recommend using Augeas.  For example, Augeas understands how
433       to read and write, say, a Linux shadow password file or X.org
434       configuration file, and so avoids you having to write that code.
435
436       The main Augeas calls are bound through the "guestfs_aug_*" APIs.  We
437       don't document Augeas itself here because there is excellent
438       documentation on the http://augeas.net/ website.
439
440       If you don’t want to use Augeas (you fool!) then try calling
441       "guestfs_read_lines" to get the file as a list of lines which you can
442       iterate over.
443
444   SYSTEMD JOURNAL FILES
445       To read the systemd journal from a Linux guest, use the
446       "guestfs_journal_*" APIs starting with "guestfs_journal_open".
447
448       Consult the journal documentation here: sd-journal(3),
449       sd_journal_open(3).
450
451   SELINUX
452       We support SELinux guests.  However it is not possible to load the
453       SELinux policy of the guest into the appliance kernel.  Therefore the
454       strategy for dealing with SELinux guests is to relabel them after
455       making changes.
456
457       In libguestfs ≥ 1.34 there is a new API, "guestfs_setfiles", which can
458       be used for this.  To properly use this API you have to parse the guest
459       SELinux configuration.  See the virt-customize(1) module
460       customize/SELinux_relabel.ml for how to do this.
461
462       A simpler but slower alternative is to touch /.autorelabel in the
463       guest, which means that the guest will relabel itself at next boot.
464
465       Libguestfs ≤ 1.32 had APIs "guestfs_set_selinux",
466       "guestfs_get_selinux", "guestfs_setcon" and "guestfs_getcon".  These
467       did not work properly, are deprecated, and should not be used in new
468       code.
469
470   UMASK
471       Certain calls are affected by the current file mode creation mask (the
472       "umask").  In particular ones which create files or directories, such
473       as "guestfs_touch", "guestfs_mknod" or "guestfs_mkdir".  This affects
474       either the default mode that the file is created with or modifies the
475       mode that you supply.
476
477       The default umask is 022, so files are created with modes such as 0644
478       and directories with 0755.
479
480       There are two ways to avoid being affected by umask.  Either set umask
481       to 0 (call "guestfs_umask (g, 0)" early after launching).  Or call
482       "guestfs_chmod" after creating each file or directory.
483
484       For more information about umask, see umask(2).
485
486   LABELS AND UUIDS
487       Many filesystems, devices and logical volumes support either labels
488       (short strings like "BOOT" which might not be unique) and/or UUIDs
489       (globally unique IDs).
490
491       For filesystems, use "guestfs_vfs_label" or "guestfs_vfs_uuid" to read
492       the label or UUID.  Some filesystems let you call "guestfs_set_label"
493       or "guestfs_set_uuid" to change the label or UUID.
494
495       You can locate a filesystem by its label or UUID using
496       "guestfs_findfs_label" or "guestfs_findfs_uuid".
497
498       For LVM2 (which supports only UUIDs), there is a rich set of APIs for
499       fetching UUIDs, fetching UUIDs of the contained objects, and changing
500       UUIDs.  See: "guestfs_lvuuid", "guestfs_vguuid", "guestfs_pvuuid",
501       "guestfs_vglvuuids", "guestfs_vgpvuuids", "guestfs_vgchange_uuid",
502       "guestfs_vgchange_uuid_all", "guestfs_pvchange_uuid",
503       "guestfs_pvchange_uuid_all".
504
505       Note when cloning a filesystem, device or whole guest, it is a good
506       idea to set new randomly generated UUIDs on the copy.
507
508   ENCRYPTED DISKS
509       Libguestfs allows you to access Linux guests which have been encrypted
510       using whole disk encryption that conforms to the Linux Unified Key
511       Setup (LUKS) standard.  This includes nearly all whole disk encryption
512       systems used by modern Linux guests.
513
514       Use "guestfs_vfs_type" to identify LUKS-encrypted block devices (it
515       returns the string "crypto_LUKS").
516
517       Then open these devices by calling "guestfs_luks_open".  Obviously you
518       will require the passphrase!
519
520       Opening a LUKS device creates a new device mapper device called
521       /dev/mapper/mapname (where "mapname" is the string you supply to
522       "guestfs_luks_open").  Reads and writes to this mapper device are
523       decrypted from and encrypted to the underlying block device
524       respectively.
525
526       LVM volume groups on the device can be made visible by calling
527       "guestfs_vgscan" followed by "guestfs_vg_activate_all".  The logical
528       volume(s) can now be mounted in the usual way.
529
530       Use the reverse process to close a LUKS device.  Unmount any logical
531       volumes on it, deactivate the volume groups by calling
532       "guestfs_vg_activate (g, 0, ["/dev/VG"])".  Then close the mapper
533       device by calling "guestfs_luks_close" on the /dev/mapper/mapname
534       device (not the underlying encrypted block device).
535
536   MOUNT LOCAL
537       In libguestfs ≥ 1.18, it is possible to mount the libguestfs filesystem
538       on a local directory and access it using ordinary POSIX calls and
539       programs.
540
541       Availability of this is subject to a number of restrictions: it
542       requires FUSE (the Filesystem in USErspace), and libfuse must also have
543       been available when libguestfs was compiled.  FUSE may require that a
544       kernel module is loaded, and it may be necessary to add the current
545       user to a special "fuse" group.  See the documentation for your
546       distribution and http://fuse.sf.net for further information.
547
548       The call to mount the libguestfs filesystem on a local directory is
549       "guestfs_mount_local" (q.v.) followed by "guestfs_mount_local_run".
550       The latter does not return until you unmount the filesystem.  The
551       reason is that the call enters the FUSE main loop and processes kernel
552       requests, turning them into libguestfs calls.  An alternative design
553       would have been to create a background thread to do this, but
554       libguestfs doesn't require pthreads.  This way is also more flexible:
555       for example the user can create another thread for
556       "guestfs_mount_local_run".
557
558       "guestfs_mount_local" needs a certain amount of time to set up the
559       mountpoint.  The mountpoint is not ready to use until the call returns.
560       At this point, accesses to the filesystem will block until the main
561       loop is entered (ie. "guestfs_mount_local_run").  So if you need to
562       start another process to access the filesystem, put the fork between
563       "guestfs_mount_local" and "guestfs_mount_local_run".
564
565       MOUNT LOCAL COMPATIBILITY
566
567       Since local mounting was only added in libguestfs 1.18, and may not be
568       available even in these builds, you should consider writing code so
569       that it doesn't depend on this feature, and can fall back to using
570       libguestfs file system calls.
571
572       If libguestfs was compiled without support for "guestfs_mount_local"
573       then calling it will return an error with errno set to "ENOTSUP" (see
574       "guestfs_last_errno").
575
576       MOUNT LOCAL PERFORMANCE
577
578       Libguestfs on top of FUSE performs quite poorly.  For best performance
579       do not use it.  Use ordinary libguestfs filesystem calls, upload,
580       download etc. instead.
581
582   HOTPLUGGING
583       In libguestfs ≥ 1.20, you may add drives and remove after calling
584       "guestfs_launch".  There are some restrictions, see below.  This is
585       called hotplugging.
586
587       Only a subset of the backends support hotplugging (currently only the
588       libvirt backend has support).  It also requires that you use libvirt ≥
589       0.10.3 and qemu ≥ 1.2.
590
591       To hot-add a disk, simply call "guestfs_add_drive_opts" after
592       "guestfs_launch".  It is mandatory to specify the "label" parameter so
593       that the newly added disk has a predictable name.  For example:
594
595        if (guestfs_launch (g) == -1)
596          error ("launch failed");
597
598        if (guestfs_add_drive_opts (g, filename,
599                                    GUESTFS_ADD_DRIVE_OPTS_LABEL, "newdisk",
600                                    -1) == -1)
601          error ("hot-add of disk failed");
602
603        if (guestfs_part_disk ("/dev/disk/guestfs/newdisk", "mbr") == -1)
604          error ("partitioning of hot-added disk failed");
605
606       To hot-remove a disk, call "guestfs_remove_drive".  You can call this
607       before or after "guestfs_launch".  You can only remove disks that were
608       previously added with a label.
609
610       Backends that support hotplugging do not require that you add ≥ 1 disk
611       before calling launch.  When hotplugging is supported you don't need to
612       add any disks.
613
614   REMOTE STORAGE
615       CEPH
616
617       Libguestfs can access Ceph (librbd/RBD) disks.
618
619       To do this, set the optional "protocol" and "server" parameters of
620       "guestfs_add_drive_opts" like this:
621
622        char **servers = { "ceph1.example.org:3000", /* ... */, NULL };
623        guestfs_add_drive_opts (g, "pool/image",
624                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
625                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "rbd",
626                                GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
627                                GUESTFS_ADD_DRIVE_OPTS_USERNAME, "rbduser",
628                                GUESTFS_ADD_DRIVE_OPTS_SECRET, "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
629                                -1);
630
631       "servers" (the "server" parameter) is a list of one or more Ceph
632       servers.  The server string is documented in "guestfs_add_drive_opts".
633       The "username" and "secret" parameters are also optional, and if not
634       given, then no authentication will be used.
635
636       FTP, HTTP AND TFTP
637
638       Libguestfs can access remote disks over FTP, FTPS, HTTP, HTTPS or TFTP
639       protocols.
640
641       To do this, set the optional "protocol" and "server" parameters of
642       "guestfs_add_drive_opts" like this:
643
644        char **servers = { "www.example.org", NULL };
645        guestfs_add_drive_opts (g, "/disk.img",
646                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
647                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "http",
648                                GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
649                                -1);
650
651       The "protocol" can be one of "ftp", "ftps", "http", "https" or "tftp".
652
653       "servers" (the "server" parameter) is a list which must have a single
654       element.  The single element is a string defining the web, FTP or TFTP
655       server.  The format of this string is documented in
656       "guestfs_add_drive_opts".
657
658       GLUSTER
659
660       Libguestfs can access Gluster disks.
661
662       To do this, set the optional "protocol" and "server" parameters of
663       "guestfs_add_drive_opts" like this:
664
665        char **servers = { "gluster.example.org:24007", NULL };
666        guestfs_add_drive_opts (g, "volname/image",
667                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
668                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "gluster",
669                                GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
670                                -1);
671
672       "servers" (the "server" parameter) is a list which must have a single
673       element.  The single element is a string defining the Gluster server.
674       The format of this string is documented in "guestfs_add_drive_opts".
675
676       Note that gluster usually requires the client process (ie. libguestfs)
677       to run as root and will give unfathomable errors if it is not (eg. "No
678       data available").
679
680       ISCSI
681
682       Libguestfs can access iSCSI disks remotely.
683
684       To do this, set the optional "protocol" and "server" parameters like
685       this:
686
687        char **server = { "iscsi.example.org:3000", NULL };
688        guestfs_add_drive_opts (g, "target-iqn-name/lun",
689                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
690                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "iscsi",
691                                GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
692                                -1);
693
694       The "server" parameter is a list which must have a single element.  The
695       single element is a string defining the iSCSI server.  The format of
696       this string is documented in "guestfs_add_drive_opts".
697
698       NETWORK BLOCK DEVICE
699
700       Libguestfs can access Network Block Device (NBD) disks remotely.
701
702       To do this, set the optional "protocol" and "server" parameters of
703       "guestfs_add_drive_opts" like this:
704
705        char **server = { "nbd.example.org:3000", NULL };
706        guestfs_add_drive_opts (g, "" /* export name - see below */,
707                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
708                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
709                                GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
710                                -1);
711
712       Notes:
713
714       ·   "server" is in fact a list of servers.  For NBD you must always
715           supply a list with a single element.  (Other remote protocols
716           require zero or more than one server, hence the requirement for
717           this parameter to be a list).
718
719       ·   The "server" string is documented in "guestfs_add_drive_opts".  To
720           connect to a local qemu-nbd instance over a Unix domain socket, use
721           "unix:/path/to/socket".
722
723       ·   The "filename" parameter is the NBD export name.  Use an empty
724           string to mean the default export.  Many NBD servers, including
725           qemu-nbd, do not support export names.
726
727       ·   If using qemu-nbd as your server, you should always specify the
728           "-t" option.  The reason is that libguestfs may open several
729           connections to the server.
730
731       ·   The libvirt backend requires that you set the "format" parameter of
732           "guestfs_add_drive_opts" accurately when you use writable NBD
733           disks.
734
735       ·   The libvirt backend has a bug that stops Unix domain socket
736           connections from working:
737           https://bugzilla.redhat.com/show_bug.cgi?id=922888
738
739       ·   The direct backend does not support readonly connections because of
740           a bug in qemu: https://bugs.launchpad.net/qemu/+bug/1155677
741
742       SHEEPDOG
743
744       Libguestfs can access Sheepdog disks.
745
746       To do this, set the optional "protocol" and "server" parameters of
747       "guestfs_add_drive_opts" like this:
748
749        char **servers = { /* optional servers ... */ NULL };
750        guestfs_add_drive_opts (g, "volume",
751                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
752                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "sheepdog",
753                                GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
754                                -1);
755
756       The optional list of "servers" may be zero or more server addresses
757       ("hostname:port").  The format of the server strings is documented in
758       "guestfs_add_drive_opts".
759
760       SSH
761
762       Libguestfs can access disks over a Secure Shell (SSH) connection.
763
764       To do this, set the "protocol" and "server" and (optionally) "username"
765       parameters of "guestfs_add_drive_opts" like this:
766
767        char **server = { "remote.example.com", NULL };
768        guestfs_add_drive_opts (g, "/path/to/disk.img",
769                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
770                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "ssh",
771                                GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
772                                GUESTFS_ADD_DRIVE_OPTS_USERNAME, "remoteuser",
773                                -1);
774
775       The format of the server string is documented in
776       "guestfs_add_drive_opts".
777
778   INSPECTION
779       Libguestfs has APIs for inspecting an unknown disk image to find out if
780       it contains operating systems, an install CD or a live CD.
781
782       Add all disks belonging to the unknown virtual machine and call
783       "guestfs_launch" in the usual way.
784
785       Then call "guestfs_inspect_os".  This function uses other libguestfs
786       calls and certain heuristics, and returns a list of operating systems
787       that were found.  An empty list means none were found.  A single
788       element is the root filesystem of the operating system.  For dual- or
789       multi-boot guests, multiple roots can be returned, each one
790       corresponding to a separate operating system.  (Multi-boot virtual
791       machines are extremely rare in the world of virtualization, but since
792       this scenario can happen, we have built libguestfs to deal with it.)
793
794       For each root, you can then call various "guestfs_inspect_get_*"
795       functions to get additional details about that operating system.  For
796       example, call "guestfs_inspect_get_type" to return the string "windows"
797       or "linux" for Windows and Linux-based operating systems respectively.
798
799       Un*x-like and Linux-based operating systems usually consist of several
800       filesystems which are mounted at boot time (for example, a separate
801       boot partition mounted on /boot).  The inspection rules are able to
802       detect how filesystems correspond to mount points.  Call
803       "guestfs_inspect_get_mountpoints" to get this mapping.  It might return
804       a hash table like this example:
805
806        /boot => /dev/sda1
807        /     => /dev/vg_guest/lv_root
808        /usr  => /dev/vg_guest/lv_usr
809
810       The caller can then make calls to "guestfs_mount" to mount the
811       filesystems as suggested.
812
813       Be careful to mount filesystems in the right order (eg. / before /usr).
814       Sorting the keys of the hash by length, shortest first, should work.
815
816       Inspection currently only works for some common operating systems.
817       Contributors are welcome to send patches for other operating systems
818       that we currently cannot detect.
819
820       Encrypted disks must be opened before inspection.  See "ENCRYPTED
821       DISKS" for more details.  The "guestfs_inspect_os" function just
822       ignores any encrypted devices.
823
824       A note on the implementation: The call "guestfs_inspect_os" performs
825       inspection and caches the results in the guest handle.  Subsequent
826       calls to "guestfs_inspect_get_*" return this cached information, but do
827       not re-read the disks.  If you change the content of the guest disks,
828       you can redo inspection by calling "guestfs_inspect_os" again.
829       ("guestfs_inspect_list_applications2" works a little differently from
830       the other calls and does read the disks.  See documentation for that
831       function for details).
832
833       INSPECTING INSTALL DISKS
834
835       Libguestfs (since 1.9.4) can detect some install disks, install CDs,
836       live CDs and more.
837
838       Further information is available about the operating system that can be
839       installed using the regular inspection APIs like
840       "guestfs_inspect_get_product_name", "guestfs_inspect_get_major_version"
841       etc.
842
843   SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
844       Libguestfs can mount NTFS partitions.  It does this using the
845       http://www.ntfs-3g.org/ driver.
846
847       DRIVE LETTERS AND PATHS
848
849       DOS and Windows still use drive letters, and the filesystems are always
850       treated as case insensitive by Windows itself, and therefore you might
851       find a Windows configuration file referring to a path like
852       "c:\windows\system32".  When the filesystem is mounted in libguestfs,
853       that directory might be referred to as /WINDOWS/System32.
854
855       Drive letter mappings can be found using inspection (see "INSPECTION"
856       and "guestfs_inspect_get_drive_mappings")
857
858       Dealing with separator characters (backslash vs forward slash) is
859       outside the scope of libguestfs, but usually a simple character
860       replacement will work.
861
862       To resolve the case insensitivity of paths, call
863       "guestfs_case_sensitive_path".
864
865       LONG FILENAMES ON NTFS
866
867       NTFS supports filenames up to 255 characters long.  "Character" means a
868       2 byte UTF-16 codepoint which can encode the most common Unicode
869       codepoints.
870
871       Most Linux filesystems support filenames up to 255 bytes.  This means
872       you may get an error:
873
874        File name too long
875
876       when you copy a file from NTFS to a Linux filesystem if the name, when
877       reencoded as UTF-8, would exceed 255 bytes in length.
878
879       This will most often happen when using non-ASCII names that are longer
880       than ~127 characters (eg. Greek, Cyrillic) or longer than ~85
881       characters (Asian languages).
882
883       A workaround is not to try to store such long filenames on Linux native
884       filesystems.  Since the tar(1) format can store unlimited length
885       filenames, keep the files in a tarball.
886
887       ACCESSING THE WINDOWS REGISTRY
888
889       Libguestfs also provides some help for decoding Windows Registry "hive"
890       files, through a separate C library called hivex(3).
891
892       Before libguestfs 1.19.35 you had to download the hive file, operate on
893       it locally using hivex, and upload it again.  Since this version, we
894       have included the major hivex APIs directly in the libguestfs API (see
895       "guestfs_hivex_open").  This means that if you have opened a Windows
896       guest, you can read and write the registry directly.
897
898       See also virt-win-reg(1).
899
900       SYMLINKS ON NTFS-3G FILESYSTEMS
901
902       Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
903       provide something which looks like a Linux symlink.  The way it tries
904       to do the rewriting is described here:
905
906       http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
907
908       The essential problem is that ntfs-3g simply does not have enough
909       information to do a correct job.  NTFS links can contain drive letters
910       and references to external device GUIDs that ntfs-3g has no way of
911       resolving.  It is almost certainly the case that libguestfs callers
912       should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
913       NTFS volumes).
914
915       Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
916       "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
917       attribute, and read the raw reparse data from that (you can find the
918       format documented in various places around the web).
919
920       EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
921
922       There are other useful extended attributes that can be read from
923       ntfs-3g filesystems (using "guestfs_getxattr").  See:
924
925       http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
926
927       WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP
928
929       Windows guests which have been hibernated (instead of fully shut down)
930       cannot be mounted.  This is a limitation of ntfs-3g.  You will see an
931       error like this:
932
933        The disk contains an unclean file system (0, 0).
934        Metadata kept in Windows cache, refused to mount.
935        Failed to mount '/dev/sda2': Operation not permitted
936        The NTFS partition is in an unsafe state. Please resume
937        and shutdown Windows fully (no hibernation or fast
938        restarting), or mount the volume read-only with the
939        'ro' mount option.
940
941       In Windows 8, the shutdown button does not shut down the guest at all.
942       Instead it usually hibernates the guest.  This is known as "fast
943       startup".
944
945       Some suggested workarounds are:
946
947       ·   Mount read-only (eg. "guestfs_mount_ro").
948
949       ·   On Windows 8, turn off fast startup.  It is in the Control Panel →
950           Power Options → Choose what the power buttons do → Change settings
951           that are currently unavailable → Turn on fast startup.
952
953       ·   On Windows 7 and earlier, shut the guest off properly instead of
954           hibernating it.
955
956   RESIZE2FS ERRORS
957       The "guestfs_resize2fs", "guestfs_resize2fs_size" and
958       "guestfs_resize2fs_M" calls are used to resize ext2/3/4 filesystems.
959
960       The underlying program (resize2fs(8)) requires that the filesystem is
961       clean and recently fsck'd before you can resize it.  Also, if the
962       resize operation fails for some reason, then you had to call fsck the
963       filesystem again to fix it.
964
965       In libguestfs "lt" 1.17.14, you usually had to call "guestfs_e2fsck_f"
966       before the resize.  However, in "ge" 1.17.14, e2fsck(8) is called
967       automatically before the resize, so you no longer need to do this.
968
969       The resize2fs(8) program can still fail, in which case it prints an
970       error message similar to:
971
972        Please run 'e2fsck -fy <device>' to fix the filesystem
973        after the aborted resize operation.
974
975       You can do this by calling "guestfs_e2fsck" with the "forceall" option.
976       However in the context of disk images, it is usually better to avoid
977       this situation, eg. by rolling back to an earlier snapshot, or by
978       copying and resizing and on failure going back to the original.
979
980   USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
981       Although we don’t want to discourage you from using the C API, we will
982       mention here that the same API is also available in other languages.
983
984       The API is broadly identical in all supported languages.  This means
985       that the C call "guestfs_add_drive_ro(g,file)" is
986       "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
987       and "g#add_drive_ro file" in OCaml.  In other words, a straightforward,
988       predictable isomorphism between each language.
989
990       Error messages are automatically transformed into exceptions if the
991       language supports it.
992
993       We don’t try to "object orientify" parts of the API in OO languages,
994       although contributors are welcome to write higher level APIs above what
995       we provide in their favourite languages if they wish.
996
997       C++ You can use the guestfs.h header file from C++ programs.  The C++
998           API is identical to the C API.  C++ classes and exceptions are not
999           used.
1000
1001       C#  The C# bindings are highly experimental.  Please read the warnings
1002           at the top of csharp/Libguestfs.cs.
1003
1004       Erlang
1005           See guestfs-erlang(3).
1006
1007       GObject
1008           Experimental GObject bindings (with GObject Introspection support)
1009           are available.
1010
1011           See guestfs-gobject(3).
1012
1013       Go  See guestfs-golang(3).
1014
1015       Haskell
1016           This language binding is working but incomplete:
1017
1018           ·   Functions with optional arguments are not bound.  Implementing
1019               optional arguments in Haskell seems to be very complex.
1020
1021           ·   Events are not bound.
1022
1023           ·   Functions with the following return types are not bound:
1024
1025               ·   Any function returning a struct.
1026
1027               ·   Any function returning a list of structs.
1028
1029               ·   A few functions that return fixed length buffers
1030                   (specifically ones declared "RBufferOut" in the generator).
1031
1032               ·   A tiny number of obscure functions that return constant
1033                   strings (specifically ones declared "RConstOptString" in
1034                   the generator).
1035
1036       Java
1037           Full documentation is contained in the Javadoc which is distributed
1038           with libguestfs.  For examples, see guestfs-java(3).
1039
1040       Lua See guestfs-lua(3).
1041
1042       OCaml
1043           See guestfs-ocaml(3).
1044
1045       Perl
1046           See guestfs-perl(3) and Sys::Guestfs(3).
1047
1048       PHP For documentation see "README-PHP" supplied with libguestfs sources
1049           or in the php-libguestfs package for your distribution.
1050
1051           The PHP binding only works correctly on 64 bit machines.
1052
1053       Python
1054           See guestfs-python(3).
1055
1056       Ruby
1057           See guestfs-ruby(3).
1058
1059           For JRuby, use the Java bindings.
1060
1061       shell scripts
1062           See guestfish(1).
1063
1064   LIBGUESTFS GOTCHAS
1065       http://en.wikipedia.org/wiki/Gotcha_(programming): "A feature of a
1066       system [...] that works in the way it is documented but is
1067       counterintuitive and almost invites mistakes."
1068
1069       Since we developed libguestfs and the associated tools, there are
1070       several things we would have designed differently, but are now stuck
1071       with for backwards compatibility or other reasons.  If there is ever a
1072       libguestfs 2.0 release, you can expect these to change.  Beware of
1073       them.
1074
1075       Read-only should be the default.
1076           In guestfish(3), --ro should be the default, and you should have to
1077           specify --rw if you want to make changes to the image.
1078
1079           This would reduce the potential to corrupt live VM images.
1080
1081           Note that many filesystems change the disk when you just mount and
1082           unmount, even if you didn't perform any writes.  You need to use
1083           "guestfs_add_drive_ro" to guarantee that the disk is not changed.
1084
1085       guestfish command line is hard to use.
1086           guestfish disk.img doesn't do what people expect (open disk.img for
1087           examination).  It tries to run a guestfish command disk.img which
1088           doesn't exist, so it fails.  In earlier versions of guestfish the
1089           error message was also unintuitive, but we have corrected this
1090           since.  Like the Bourne shell, we should have used "guestfish -c
1091           command" to run commands.
1092
1093       guestfish megabyte modifiers don’t work right on all commands
1094           In recent guestfish you can use "1M" to mean 1 megabyte (and
1095           similarly for other modifiers).  What guestfish actually does is to
1096           multiply the number part by the modifier part and pass the result
1097           to the C API.  However this doesn't work for a few APIs which
1098           aren't expecting bytes, but are already expecting some other unit
1099           (eg. megabytes).
1100
1101           The most common is "guestfs_lvcreate".  The guestfish command:
1102
1103            lvcreate LV VG 100M
1104
1105           does not do what you might expect.  Instead because
1106           "guestfs_lvcreate" is already expecting megabytes, this tries to
1107           create a 100 terabyte (100 megabytes * megabytes) logical volume.
1108           The error message you get from this is also a little obscure.
1109
1110           This could be fixed in the generator by specially marking
1111           parameters and return values which take bytes or other units.
1112
1113       Ambiguity between devices and paths
1114           There is a subtle ambiguity in the API between a device name (eg.
1115           /dev/sdb2) and a similar pathname.  A file might just happen to be
1116           called "sdb2" in the directory /dev (consider some non-Unix VM
1117           image).
1118
1119           In the current API we usually resolve this ambiguity by having two
1120           separate calls, for example "guestfs_checksum" and
1121           "guestfs_checksum_device".  Some API calls are ambiguous and
1122           (incorrectly) resolve the problem by detecting if the path supplied
1123           begins with /dev/.
1124
1125           To avoid both the ambiguity and the need to duplicate some calls,
1126           we could make paths/devices into structured names.  One way to do
1127           this would be to use a notation like grub ("hd(0,0)"), although
1128           nobody really likes this aspect of grub.  Another way would be to
1129           use a structured type, equivalent to this OCaml type:
1130
1131            type path = Path of string | Device of int | Partition of int * int
1132
1133           which would allow you to pass arguments like:
1134
1135            Path "/foo/bar"
1136            Device 1            (* /dev/sdb, or perhaps /dev/sda *)
1137            Partition (1, 2)    (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
1138            Path "/dev/sdb2"    (* not a device *)
1139
1140           As you can see there are still problems to resolve even with this
1141           representation.  Also consider how it might work in guestfish.
1142
1143   KEYS AND PASSPHRASES
1144       Certain libguestfs calls take a parameter that contains sensitive key
1145       material, passed in as a C string.
1146
1147       In the future we would hope to change the libguestfs implementation so
1148       that keys are mlock(2)-ed into physical RAM, and thus can never end up
1149       in swap.  However this is not done at the moment, because of the
1150       complexity of such an implementation.
1151
1152       Therefore you should be aware that any key parameter you pass to
1153       libguestfs might end up being written out to the swap partition.  If
1154       this is a concern, scrub the swap partition or don't use libguestfs on
1155       encrypted devices.
1156
1157   MULTIPLE HANDLES AND MULTIPLE THREADS
1158       All high-level libguestfs actions are synchronous.  If you want to use
1159       libguestfs asynchronously then you must create a thread.
1160
1161       Threads in libguestfs  1.38
1162
1163       In libguestfs ≥ 1.38, each handle ("guestfs_h") contains a lock which
1164       is acquired automatically when you call a libguestfs function.  The
1165       practical effect of this is you can call libguestfs functions with the
1166       same handle from multiple threads without needing to do any locking.
1167
1168       Also in libguestfs ≥ 1.38, the last error on the handle
1169       ("guestfs_last_error", "guestfs_last_errno") is stored in thread-local
1170       storage, so it is safe to write code like:
1171
1172        if (guestfs_add_drive_ro (g, drive) == -1)
1173          fprintf (stderr, "error was: %s\n", guestfs_last_error (g));
1174
1175       even when other threads may be concurrently using the same handle "g".
1176
1177       Threads in libguestfs < 1.38
1178
1179       In libguestfs < 1.38, you must use the handle only from a single
1180       thread.  Either use the handle exclusively from one thread, or provide
1181       your own mutex so that two threads cannot issue calls on the same
1182       handle at the same time.  Even apparently innocent functions like
1183       "guestfs_get_trace" are not safe to be called from multiple threads
1184       without a mutex in libguestfs < 1.38.
1185
1186       Use "guestfs_set_identifier" to make it simpler to identify threads in
1187       trace output.
1188
1189   PATH
1190       Libguestfs needs a supermin appliance, which it finds by looking along
1191       an internal path.
1192
1193       By default it looks for these in the directory "$libdir/guestfs" (eg.
1194       /usr/local/lib/guestfs or /usr/lib64/guestfs).
1195
1196       Use "guestfs_set_path" or set the environment variable
1197       "LIBGUESTFS_PATH" to change the directories that libguestfs will search
1198       in.  The value is a colon-separated list of paths.  The current
1199       directory is not searched unless the path contains an empty element or
1200       ".".  For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
1201       current directory and then /usr/lib/guestfs.
1202
1203   QEMU WRAPPERS
1204       If you want to compile your own qemu, run qemu from a non-standard
1205       location, or pass extra arguments to qemu, then you can write a shell-
1206       script wrapper around qemu.
1207
1208       There is one important rule to remember: you must "exec qemu" as the
1209       last command in the shell script (so that qemu replaces the shell and
1210       becomes the direct child of the libguestfs-using program).  If you
1211       don't do this, then the qemu process won't be cleaned up correctly.
1212
1213       Here is an example of a wrapper, where I have built my own copy of qemu
1214       from source:
1215
1216        #!/bin/sh -
1217        qemudir=/home/rjones/d/qemu
1218        exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1219
1220       Save this script as /tmp/qemu.wrapper (or wherever), "chmod +x", and
1221       then use it by setting the LIBGUESTFS_HV environment variable.  For
1222       example:
1223
1224        LIBGUESTFS_HV=/tmp/qemu.wrapper guestfish
1225
1226       Note that libguestfs also calls qemu with the -help and -version
1227       options in order to determine features.
1228
1229       Wrappers can also be used to edit the options passed to qemu.  In the
1230       following example, the "-machine ..." option ("-machine" and the
1231       following argument) are removed from the command line and replaced with
1232       "-machine pc,accel=tcg".  The while loop iterates over the options
1233       until it finds the right one to remove, putting the remaining options
1234       into the "args" array.
1235
1236        #!/bin/bash -
1237
1238        i=0
1239        while [ $# -gt 0 ]; do
1240            case "$1" in
1241            -machine)
1242                shift 2;;
1243            *)
1244                args[i]="$1"
1245                (( i++ ))
1246                shift ;;
1247            esac
1248        done
1249
1250        exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
1251
1252   BACKEND
1253       The backend (previously known as the "attach method") controls how
1254       libguestfs creates and/or connects to the backend daemon, eg. by
1255       starting qemu directly, or using libvirt to manage an appliance,
1256       running User-Mode Linux, or connecting to an already running daemon.
1257
1258       You can set the backend by calling "guestfs_set_backend", or by setting
1259       the environment variable "LIBGUESTFS_BACKEND".
1260
1261       Possible backends are described below:
1262
1263       "direct"
1264       "appliance"
1265           Run qemu directly to launch an appliance.
1266
1267           "direct" and "appliance" are synonyms.
1268
1269           This is the ordinary method and normally the default, but see the
1270           note below.
1271
1272       "libvirt"
1273       "libvirt:null"
1274       "libvirt:URI"
1275           Use libvirt to launch and manage the appliance.
1276
1277           "libvirt" causes libguestfs to choose a suitable URI for creating
1278           session guests.  If using the libvirt backend, you almost always
1279           should use this.
1280
1281           "libvirt:null" causes libguestfs to use the "NULL" connection URI,
1282           which causes libvirt to try to guess what the user meant.  You
1283           probably don't want to use this.
1284
1285           "libvirt:URI" uses URI as the libvirt connection URI (see
1286           http://libvirt.org/uri.html).  The typical libvirt backend with a
1287           URI would be "libvirt:qemu:///session"
1288
1289           The libvirt backend supports more features, including hotplugging
1290           (see "HOTPLUGGING") and sVirt.
1291
1292       "uml"
1293           Run the User-Mode Linux kernel.  The location of the kernel is set
1294           using $LIBGUESTFS_HV or using the "guestfs_set_qemu" API (note that
1295           qemu is not involved, we just reuse the same variable in the handle
1296           for convenience).
1297
1298           User-Mode Linux can be much faster, simpler and more lightweight
1299           than using a full-blown virtual machine, but it also has some
1300           shortcomings.  See "USER-MODE LINUX BACKEND" below.
1301
1302       "unix:path"
1303           Connect to the Unix domain socket path.
1304
1305           This method lets you connect to an existing daemon or (using
1306           virtio-serial) to a live guest.  For more information, see
1307           "ATTACHING TO RUNNING DAEMONS".
1308
1309       "direct" is usually the default backend.  However since libguestfs ≥
1310       1.19.24, libguestfs can be built with a different default by doing:
1311
1312        ./configure --with-default-backend=...
1313
1314       To find out if libguestfs was compiled with a different default
1315       backend, do:
1316
1317        unset LIBGUESTFS_BACKEND
1318        guestfish get-backend
1319
1320   BACKEND SETTINGS
1321       Each backend can be configured by passing a list of strings.  You can
1322       either call "guestfs_set_backend_settings" with a list of strings, or
1323       set the "LIBGUESTFS_BACKEND_SETTINGS" environment variable to a colon-
1324       separated list of strings (before creating the handle).
1325
1326       force_tcg
1327
1328       Using:
1329
1330        export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
1331
1332       will force the direct and libvirt backends to use TCG (software
1333       emulation) instead of KVM (hardware accelerated virtualization).
1334
1335       gdb
1336
1337       The direct backend supports:
1338
1339        export LIBGUESTFS_BACKEND_SETTINGS=gdb
1340
1341       When this is set, qemu will not start running the appliance
1342       immediately.  It will wait for you to connect to it using gdb:
1343
1344        $ gdb
1345        (gdb) symbol-file /path/to/vmlinux
1346        (gdb) target remote tcp::1234
1347        (gdb) cont
1348
1349       You can then debug the appliance kernel, which is useful to debug boot
1350       failures (especially ones where there are no debug messages printed -
1351       tip: look in the kernel "log_buf").
1352
1353       On Fedora, install "kernel-debuginfo" for the "vmlinux" file
1354       (containing symbols).  Make sure the symbols precisely match the kernel
1355       being used.
1356
1357   ATTACHING TO RUNNING DAEMONS
1358       Note (1): This is highly experimental and has a tendency to eat babies.
1359       Use with caution.
1360
1361       Note (2): This section explains how to attach to a running daemon from
1362       a low level perspective.  For most users, simply using virt tools such
1363       as guestfish(1) with the --live option will "just work".
1364
1365       Using guestfs_set_backend
1366
1367       By calling "guestfs_set_backend" you can change how the library
1368       connects to the "guestfsd" daemon in "guestfs_launch" (read
1369       "ARCHITECTURE" in guestfs-internals(1) for some background).
1370
1371       The normal backend is "direct", where a small appliance is created
1372       containing the daemon, and then the library connects to this.
1373       "libvirt" or "libvirt:URI" are alternatives that use libvirt to start
1374       the appliance.
1375
1376       Setting the backend to "unix:path" (where path is the path of a Unix
1377       domain socket) causes "guestfs_launch" to connect to an existing daemon
1378       over the Unix domain socket.
1379
1380       The normal use for this is to connect to a running virtual machine that
1381       contains a "guestfsd" daemon, and send commands so you can read and
1382       write files inside the live virtual machine.
1383
1384       Using guestfs_add_domain with live flag
1385
1386       "guestfs_add_domain" provides some help for getting the correct
1387       backend.  If you pass the "live" option to this function, then (if the
1388       virtual machine is running) it will examine the libvirt XML looking for
1389       a virtio-serial channel to connect to:
1390
1391        <domain>
1392          ...
1393          <devices>
1394            ...
1395            <channel type='unix'>
1396              <source mode='bind' path='/path/to/socket'/>
1397              <target type='virtio' name='org.libguestfs.channel.0'/>
1398            </channel>
1399            ...
1400          </devices>
1401        </domain>
1402
1403       "guestfs_add_domain" extracts /path/to/socket and sets the backend to
1404       "unix:/path/to/socket".
1405
1406       Some of the libguestfs tools (including guestfish) support a --live
1407       option which is passed through to "guestfs_add_domain" thus allowing
1408       you to attach to and modify live virtual machines.
1409
1410       The virtual machine needs to have been set up beforehand so that it has
1411       the virtio-serial channel and so that guestfsd is running inside it.
1412
1413   USER-MODE LINUX BACKEND
1414       Setting the following environment variables (or the equivalent in the
1415       API) selects the User-Mode Linux backend:
1416
1417        export LIBGUESTFS_BACKEND=uml
1418        export LIBGUESTFS_HV=/path/to/vmlinux
1419
1420       "vmlinux" (or it may be called "linux") is the Linux binary, compiled
1421       to run as a userspace process.  Note that we reuse the qemu variable in
1422       the handle for convenience; qemu is not involved.
1423
1424       User-Mode Linux can be faster and more lightweight than running a full-
1425       blown virtual machine as the backend (especially if you are already
1426       running libguestfs in a virtual machine or cloud instance), but it also
1427       has some shortcomings compared to the usual qemu/KVM-based backend.
1428
1429       BUILDING USER-MODE LINUX FROM SOURCE
1430
1431       Your Linux distro may provide UML in which case you can ignore this
1432       section.
1433
1434       These instructions are adapted from:
1435       http://user-mode-linux.sourceforge.net/source.html
1436
1437       1. Check out Linux sources
1438           Clone the Linux git repository or download the Linux source
1439           tarball.
1440
1441       2. Configure the kernel
1442           Note: All ‘make’ commands must have "ARCH=um" added.
1443
1444            make menuconfig ARCH=um
1445
1446           Make sure any filesystem drivers that you need are compiled into
1447           the kernel.
1448
1449           Currently, it needs a large amount of extra work to get modules
1450           working.  It’s recommended that you disable module support in the
1451           kernel configuration, which will cause everything to be compiled
1452           into the image.
1453
1454       3. Build the kernel
1455            make ARCH=um
1456
1457           This will leave a file called "linux" or "vmlinux" in the top-level
1458           directory.  This is the UML kernel.  You should set "LIBGUESTFS_HV"
1459           to point to this file.
1460
1461       USER-MODE LINUX DIFFERENCES FROM KVM
1462
1463       UML only supports raw-format images
1464           Only plain raw-format images will work.  No qcow2, no backing
1465           files.
1466
1467       UML does not support any remote drives
1468           No NBD, etc.
1469
1470       UML only works on ix86 and x86-64
1471       UML is experimental
1472           In particular, support for UML in libguestfs depends on support for
1473           UML in the upstream kernel.  If UML was ever removed from the
1474           upstream Linux kernel, then we might remove it from libguestfs too.
1475
1476   ABI GUARANTEE
1477       We guarantee the libguestfs ABI (binary interface), for public, high-
1478       level actions as outlined in this section.  Although we will deprecate
1479       some actions, for example if they get replaced by newer calls, we will
1480       keep the old actions forever.  This allows you the developer to program
1481       in confidence against the libguestfs API.
1482
1483   BLOCK DEVICE NAMING
1484       Libguestfs defines /dev/sd* as the standard naming scheme for devices
1485       passed to API calls.  So /dev/sda means "the first device added by
1486       "guestfs_add_drive_opts"", and /dev/sdb3 means "the third partition on
1487       the second device".
1488
1489       Internally device names are sometimes translated, but this should not
1490       be visible at the API level.
1491
1492       DISK LABELS
1493
1494       In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1495       using the optional "label" parameter to "guestfs_add_drive_opts".
1496       (Note that disk labels are different from and not related to filesystem
1497       labels).
1498
1499       Not all versions of libguestfs support setting a disk label, and when
1500       it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1501
1502       When you add a disk with a label, it can either be addressed using
1503       /dev/sd*, or using /dev/disk/guestfs/label.  Partitions on the disk can
1504       be addressed using /dev/disk/guestfs/labelpartnum.
1505
1506       Listing devices ("guestfs_list_devices") and partitions
1507       ("guestfs_list_partitions") returns the block device names.  However
1508       you can use "guestfs_list_disk_labels" to map disk labels to block
1509       device and partition names.
1510
1511   NULL DISKS
1512       When adding a disk using, eg., "guestfs_add_drive", you can set the
1513       filename to "/dev/null".  This string is treated specially by
1514       libguestfs, causing it to add a "null disk".
1515
1516       A null disk has the following properties:
1517
1518       ·   A null disk will appear as a normal device, eg. in calls to
1519           "guestfs_list_devices".
1520
1521       ·   You may add "/dev/null" multiple times.
1522
1523       ·   You should not try to access a null disk in any way.  For example,
1524           you shouldn't try to read it or mount it.
1525
1526       Null disks are used for three main purposes:
1527
1528       1.  Performance testing of libguestfs (see guestfs-performance(1)).
1529
1530       2.  The internal test suite.
1531
1532       3.  If you want to use libguestfs APIs that don’t refer to disks, since
1533           libguestfs requires that at least one disk is added, you should add
1534           a null disk.
1535
1536           For example, to test if a feature is available, use code like this:
1537
1538            guestfs_h *g;
1539            char **groups = [ "btrfs", NULL ];
1540
1541            g = guestfs_create ();
1542            guestfs_add_drive (g, "/dev/null");
1543            guestfs_launch (g);
1544            if (guestfs_available (g, groups) == 0) {
1545              // group(s) are available
1546            } else {
1547              // group(s) are not available
1548            }
1549            guestfs_close (g);
1550
1551   DISK IMAGE FORMATS
1552       Virtual disks come in a variety of formats.  Some common formats are
1553       listed below.
1554
1555       Note that libguestfs itself is not responsible for handling the disk
1556       format: this is done using qemu(1).  If support for a particular format
1557       is missing or broken, this has to be fixed in qemu.
1558
1559       COMMON VIRTUAL DISK IMAGE FORMATS
1560
1561       raw Raw format is simply a dump of the sequential bytes of the virtual
1562           hard disk.  There is no header, container, compression or
1563           processing of any sort.
1564
1565           Since raw format requires no translation to read or write, it is
1566           both fast and very well supported by qemu and all other
1567           hypervisors.  You can consider it to be a universal format that any
1568           hypervisor can access.
1569
1570           Raw format files are not compressed and so take up the full space
1571           of the original disk image even when they are empty.  A variation
1572           (on Linux/Unix at least) is to not store ranges of all-zero bytes
1573           by storing the file as a sparse file.  This "variant format" is
1574           sometimes called raw sparse.  Many utilities, including
1575           virt-sparsify(1), can make raw disk images sparse.
1576
1577       qcow2
1578           Qcow2 is the native disk image format used by qemu.  Internally it
1579           uses a two-level directory structure so that only blocks containing
1580           data are stored in the file.  It also has many other features such
1581           as compression, snapshots and backing files.
1582
1583           There are at least two distinct variants of this format, although
1584           qemu (and hence libguestfs) handles both transparently to the user.
1585
1586       vmdk
1587           VMDK is VMware’s native disk image format.  There are many
1588           variations.  Modern qemu (hence libguestfs) supports most
1589           variations, but you should be aware that older versions of qemu had
1590           some very bad data-corrupting bugs in this area.
1591
1592           Note that VMware ESX exposes files with the name guest-flat.vmdk.
1593           These are not VMDK.  They are raw format files which happen to have
1594           a ".vmdk" extension.
1595
1596       vdi VDI is VirtualBox’s native disk image format.  Qemu (hence
1597           libguestfs) has generally good support for this.
1598
1599       vpc
1600       vhd VPC (old) and VHD (modern) are the native disk image format of
1601           Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1602
1603       Obsolete formats
1604           The following formats are obsolete and should not be used: qcow
1605           (aka qcow1), cow, bochs.
1606
1607       DETECTING THE FORMAT OF A DISK IMAGE
1608
1609       Firstly note there is a security issue with auto-detecting the format
1610       of a disk image.  It may or may not apply in your use case.  Read
1611       "CVE-2010-3851" below.
1612
1613       Libguestfs offers an API to get the format of a disk image
1614       ("guestfs_disk_format"), and it is safest to use this.
1615
1616       Don’t be tempted to try parsing the text / human-readable output of
1617       "qemu-img" since it cannot be parsed reliably and securely.  Also do
1618       not use the "file" command since the output of that changes over time.
1619

CONNECTION MANAGEMENT

1621   guestfs_h *
1622       "guestfs_h" is the opaque type representing a connection handle.
1623       Create a handle by calling "guestfs_create" or "guestfs_create_flags".
1624       Call "guestfs_close" to free the handle and release all resources used.
1625
1626       For information on using multiple handles and threads, see the section
1627       "MULTIPLE HANDLES AND MULTIPLE THREADS" above.
1628
1629   guestfs_create
1630        guestfs_h *guestfs_create (void);
1631
1632       Create a connection handle.
1633
1634       On success this returns a non-NULL pointer to a handle.  On error it
1635       returns NULL.
1636
1637       You have to "configure" the handle after creating it.  This includes
1638       calling "guestfs_add_drive_opts" (or one of the equivalent calls) on
1639       the handle at least once.
1640
1641       After configuring the handle, you have to call "guestfs_launch".
1642
1643       You may also want to configure error handling for the handle.  See the
1644       "ERROR HANDLING" section below.
1645
1646   guestfs_create_flags
1647        guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
1648
1649       Create a connection handle, supplying extra flags and extra arguments
1650       to control how the handle is created.
1651
1652       On success this returns a non-NULL pointer to a handle.  On error it
1653       returns NULL.
1654
1655       "guestfs_create" is equivalent to calling guestfs_create_flags(0).
1656
1657       The following flags may be logically ORed together.  (Currently no
1658       extra arguments are used).
1659
1660       "GUESTFS_CREATE_NO_ENVIRONMENT"
1661           Don’t parse any environment variables (such as "LIBGUESTFS_DEBUG"
1662           etc).
1663
1664           You can call "guestfs_parse_environment" or
1665           "guestfs_parse_environment_list" afterwards to parse environment
1666           variables.  Alternately, don't call these functions if you want the
1667           handle to be unaffected by environment variables.  See the example
1668           below.
1669
1670           The default (if this flag is not given) is to implicitly call
1671           "guestfs_parse_environment".
1672
1673       "GUESTFS_CREATE_NO_CLOSE_ON_EXIT"
1674           Don’t try to close the handle in an atexit(3) handler if the
1675           program exits without explicitly closing the handle.
1676
1677           The default (if this flag is not given) is to install such an
1678           atexit handler.
1679
1680       USING "GUESTFS_CREATE_NO_ENVIRONMENT"
1681
1682       You might use "GUESTFS_CREATE_NO_ENVIRONMENT" and an explicit call to
1683       "guestfs_parse_environment" like this:
1684
1685        guestfs_h *g;
1686        int r;
1687
1688        g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
1689        if (!g) {
1690          perror ("guestfs_create_flags");
1691          exit (EXIT_FAILURE);
1692        }
1693        r = guestfs_parse_environment (g);
1694        if (r == -1)
1695          exit (EXIT_FAILURE);
1696
1697       Or to create a handle which is unaffected by environment variables,
1698       omit the call to "guestfs_parse_environment" from the above code.
1699
1700       The above code has another advantage which is that any errors from
1701       parsing the environment are passed through the error handler, whereas
1702       "guestfs_create" prints errors on stderr and ignores them.
1703
1704   guestfs_close
1705        void guestfs_close (guestfs_h *g);
1706
1707       This closes the connection handle and frees up all resources used.  If
1708       a close callback was set on the handle, then it is called.
1709
1710       The correct way to close the handle is:
1711
1712        if (guestfs_shutdown (g) == -1) {
1713          /* handle write errors here */
1714        }
1715        guestfs_close (g);
1716
1717       "guestfs_shutdown" is only needed if all of the following are true:
1718
1719       1.  one or more disks were added in read-write mode, and
1720
1721       2.  guestfs_launch was called, and
1722
1723       3.  you made some changes, and
1724
1725       4.  you have a way to handle write errors (eg. by exiting with an error
1726           code or reporting something to the user).
1727

ERROR HANDLING

1729       API functions can return errors.  For example, almost all functions
1730       that return "int" will return "-1" to indicate an error.
1731
1732       Additional information is available for errors: an error message string
1733       and optionally an error number (errno) if the thing that failed was a
1734       system call.
1735
1736       You can get at the additional information about the last error on the
1737       handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1738       setting up an error handler with "guestfs_set_error_handler".
1739
1740       When the handle is created, a default error handler is installed which
1741       prints the error message string to "stderr".  For small short-running
1742       command line programs it is sufficient to do:
1743
1744        if (guestfs_launch (g) == -1)
1745          exit (EXIT_FAILURE);
1746
1747       since the default error handler will ensure that an error message has
1748       been printed to "stderr" before the program exits.
1749
1750       For other programs the caller will almost certainly want to install an
1751       alternate error handler or do error handling in-line as in the example
1752       below.  The non-C language bindings all install NULL error handlers and
1753       turn errors into exceptions using code similar to this:
1754
1755        const char *msg;
1756        int errnum;
1757
1758        /* This disables the default behaviour of printing errors
1759           on stderr. */
1760        guestfs_set_error_handler (g, NULL, NULL);
1761
1762        if (guestfs_launch (g) == -1) {
1763          /* Examine the error message and print it, throw it,
1764             etc. */
1765          msg = guestfs_last_error (g);
1766          errnum = guestfs_last_errno (g);
1767
1768          fprintf (stderr, "%s", msg);
1769          if (errnum != 0)
1770            fprintf (stderr, ": %s", strerror (errnum));
1771          fprintf (stderr, "\n");
1772
1773          /* ... */
1774        }
1775
1776       "guestfs_create" returns "NULL" if the handle cannot be created, and
1777       because there is no handle if this happens there is no way to get
1778       additional error information.  Since libguestfs ≥ 1.20, you can use
1779       "guestfs_create_flags" to properly deal with errors during handle
1780       creation, although the vast majority of programs can continue to use
1781       "guestfs_create" and not worry about this situation.
1782
1783       Out of memory errors are handled differently.  The default action is to
1784       call abort(3).  If this is undesirable, then you can set a handler
1785       using "guestfs_set_out_of_memory_handler".
1786
1787   guestfs_last_error
1788        const char *guestfs_last_error (guestfs_h *g);
1789
1790       This returns the last error message that happened on "g".  If there has
1791       not been an error since the handle was created, then this returns
1792       "NULL".
1793
1794       Note the returned string does not have a newline character at the end.
1795       Most error messages are single lines.  Some are split over multiple
1796       lines and contain "\n" characters within the string but not at the end.
1797
1798       The lifetime of the returned string is until the next error occurs on
1799       the same handle, or "guestfs_close" is called.  If you need to keep it
1800       longer, copy it.
1801
1802   guestfs_last_errno
1803        int guestfs_last_errno (guestfs_h *g);
1804
1805       This returns the last error number (errno) that happened on "g".
1806
1807       If successful, an errno integer not equal to zero is returned.
1808
1809       In many cases the special errno "ENOTSUP" is returned if you tried to
1810       call a function or use a feature which is not supported.
1811
1812       If no error number is available, this returns 0.  This call can return
1813       0 in three situations:
1814
1815       1.  There has not been any error on the handle.
1816
1817       2.  There has been an error but the errno was meaningless.  This
1818           corresponds to the case where the error did not come from a failed
1819           system call, but for some other reason.
1820
1821       3.  There was an error from a failed system call, but for some reason
1822           the errno was not captured and returned.  This usually indicates a
1823           bug in libguestfs.
1824
1825       Libguestfs tries to convert the errno from inside the appliance into a
1826       corresponding errno for the caller (not entirely trivial: the appliance
1827       might be running a completely different operating system from the
1828       library and error numbers are not standardized across Un*xen).  If this
1829       could not be done, then the error is translated to "EINVAL".  In
1830       practice this should only happen in very rare circumstances.
1831
1832   guestfs_set_error_handler
1833        typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1834                                                  void *opaque,
1835                                                  const char *msg);
1836        void guestfs_set_error_handler (guestfs_h *g,
1837                                        guestfs_error_handler_cb cb,
1838                                        void *opaque);
1839
1840       The callback "cb" will be called if there is an error.  The parameters
1841       passed to the callback are an opaque data pointer and the error message
1842       string.
1843
1844       "errno" is not passed to the callback.  To get that the callback must
1845       call "guestfs_last_errno".
1846
1847       Note that the message string "msg" is freed as soon as the callback
1848       function returns, so if you want to stash it somewhere you must make
1849       your own copy.
1850
1851       The default handler prints messages on "stderr".
1852
1853       If you set "cb" to "NULL" then no handler is called.
1854
1855   guestfs_get_error_handler
1856        guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1857                                                            void **opaque_rtn);
1858
1859       Returns the current error handler callback.
1860
1861   guestfs_push_error_handler
1862        void guestfs_push_error_handler (guestfs_h *g,
1863                                         guestfs_error_handler_cb cb,
1864                                         void *opaque);
1865
1866       This is the same as "guestfs_set_error_handler", except that the old
1867       error handler is stashed away in a stack inside the handle.  You can
1868       restore the previous error handler by calling
1869       "guestfs_pop_error_handler".
1870
1871       Use the following code to temporarily disable errors around a function:
1872
1873        guestfs_push_error_handler (g, NULL, NULL);
1874        guestfs_mkdir (g, "/foo"); /* We don't care if this fails. */
1875        guestfs_pop_error_handler (g);
1876
1877   guestfs_pop_error_handler
1878        void guestfs_pop_error_handler (guestfs_h *g);
1879
1880       Restore the previous error handler (see "guestfs_push_error_handler").
1881
1882       If you pop the stack too many times, then the default error handler is
1883       restored.
1884
1885   guestfs_set_out_of_memory_handler
1886        typedef void (*guestfs_abort_cb) (void);
1887        void guestfs_set_out_of_memory_handler (guestfs_h *g,
1888                                                guestfs_abort_cb);
1889
1890       The callback "cb" will be called if there is an out of memory
1891       situation.  Note this callback must not return.
1892
1893       The default is to call abort(3).
1894
1895       You cannot set "cb" to "NULL".  You can’t ignore out of memory
1896       situations.
1897
1898   guestfs_get_out_of_memory_handler
1899        guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1900
1901       This returns the current out of memory handler.
1902

API CALLS

1904   guestfs_acl_delete_def_file
1905        int
1906        guestfs_acl_delete_def_file (guestfs_h *g,
1907                                     const char *dir);
1908
1909       This function deletes the default POSIX Access Control List (ACL)
1910       attached to directory "dir".
1911
1912       This function returns 0 on success or -1 on error.
1913
1914       This function depends on the feature "acl".  See also
1915       "guestfs_feature_available".
1916
1917       (Added in 1.19.63)
1918
1919   guestfs_acl_get_file
1920        char *
1921        guestfs_acl_get_file (guestfs_h *g,
1922                              const char *path,
1923                              const char *acltype);
1924
1925       This function returns the POSIX Access Control List (ACL) attached to
1926       "path".  The ACL is returned in "long text form" (see acl(5)).
1927
1928       The "acltype" parameter may be:
1929
1930       "access"
1931           Return the ordinary (access) ACL for any file, directory or other
1932           filesystem object.
1933
1934       "default"
1935           Return the default ACL.  Normally this only makes sense if "path"
1936           is a directory.
1937
1938       This function returns a string, or NULL on error.  The caller must free
1939       the returned string after use.
1940
1941       This function depends on the feature "acl".  See also
1942       "guestfs_feature_available".
1943
1944       (Added in 1.19.63)
1945
1946   guestfs_acl_set_file
1947        int
1948        guestfs_acl_set_file (guestfs_h *g,
1949                              const char *path,
1950                              const char *acltype,
1951                              const char *acl);
1952
1953       This function sets the POSIX Access Control List (ACL) attached to
1954       "path".
1955
1956       The "acltype" parameter may be:
1957
1958       "access"
1959           Set the ordinary (access) ACL for any file, directory or other
1960           filesystem object.
1961
1962       "default"
1963           Set the default ACL.  Normally this only makes sense if "path" is a
1964           directory.
1965
1966       The "acl" parameter is the new ACL in either "long text form" or "short
1967       text form" (see acl(5)).  The new ACL completely replaces any previous
1968       ACL on the file.  The ACL must contain the full Unix permissions (eg.
1969       "u::rwx,g::rx,o::rx").
1970
1971       If you are specifying individual users or groups, then the mask field
1972       is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1973       "g:ID:..." field(s).  A full ACL string might therefore look like this:
1974
1975        u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1976        \ Unix permissions / \mask/ \      ACL        /
1977
1978       You should use numeric UIDs and GIDs.  To map usernames and groupnames
1979       to the correct numeric ID in the context of the guest, use the Augeas
1980       functions (see "guestfs_aug_init").
1981
1982       This function returns 0 on success or -1 on error.
1983
1984       This function depends on the feature "acl".  See also
1985       "guestfs_feature_available".
1986
1987       (Added in 1.19.63)
1988
1989   guestfs_add_cdrom
1990        int
1991        guestfs_add_cdrom (guestfs_h *g,
1992                           const char *filename);
1993
1994       This function is deprecated.  In new code, use the
1995       "guestfs_add_drive_ro" call instead.
1996
1997       Deprecated functions will not be removed from the API, but the fact
1998       that they are deprecated indicates that there are problems with correct
1999       use of these functions.
2000
2001       This function adds a virtual CD-ROM disk image to the guest.
2002
2003       The image is added as read-only drive, so this function is equivalent
2004       of "guestfs_add_drive_ro".
2005
2006       This function returns 0 on success or -1 on error.
2007
2008       (Added in 0.3)
2009
2010   guestfs_add_domain
2011        int
2012        guestfs_add_domain (guestfs_h *g,
2013                            const char *dom,
2014                            ...);
2015
2016       You may supply a list of optional arguments to this call.  Use zero or
2017       more of the following pairs of parameters, and terminate the list with
2018       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2019
2020        GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
2021        GUESTFS_ADD_DOMAIN_READONLY, int readonly,
2022        GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
2023        GUESTFS_ADD_DOMAIN_LIVE, int live,
2024        GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
2025        GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
2026        GUESTFS_ADD_DOMAIN_CACHEMODE, const char *cachemode,
2027        GUESTFS_ADD_DOMAIN_DISCARD, const char *discard,
2028        GUESTFS_ADD_DOMAIN_COPYONREAD, int copyonread,
2029
2030       This function adds the disk(s) attached to the named libvirt domain
2031       "dom".  It works by connecting to libvirt, requesting the domain and
2032       domain XML from libvirt, parsing it for disks, and calling
2033       "guestfs_add_drive_opts" on each one.
2034
2035       The number of disks added is returned.  This operation is atomic: if an
2036       error is returned, then no disks are added.
2037
2038       This function does some minimal checks to make sure the libvirt domain
2039       is not running (unless "readonly" is true).  In a future version we
2040       will try to acquire the libvirt lock on each disk.
2041
2042       Disks must be accessible locally.  This often means that adding disks
2043       from a remote libvirt connection (see http://libvirt.org/remote.html)
2044       will fail unless those disks are accessible via the same device path
2045       locally too.
2046
2047       The optional "libvirturi" parameter sets the libvirt URI (see
2048       http://libvirt.org/uri.html).  If this is not set then we connect to
2049       the default libvirt URI (or one set through an environment variable,
2050       see the libvirt documentation for full details).
2051
2052       The optional "live" flag controls whether this call will try to connect
2053       to a running virtual machine "guestfsd" process if it sees a suitable
2054       <channel> element in the libvirt XML definition.  The default (if the
2055       flag is omitted) is never to try.  See "ATTACHING TO RUNNING DAEMONS"
2056       for more information.
2057
2058       If the "allowuuid" flag is true (default is false) then a UUID may be
2059       passed instead of the domain name.  The "dom" string is treated as a
2060       UUID first and looked up, and if that lookup fails then we treat "dom"
2061       as a name as usual.
2062
2063       The optional "readonlydisk" parameter controls what we do for disks
2064       which are marked <readonly/> in the libvirt XML.  Possible values are:
2065
2066       readonlydisk = "error"
2067           If "readonly" is false:
2068
2069           The whole call is aborted with an error if any disk with the
2070           <readonly/> flag is found.
2071
2072           If "readonly" is true:
2073
2074           Disks with the <readonly/> flag are added read-only.
2075
2076       readonlydisk = "read"
2077           If "readonly" is false:
2078
2079           Disks with the <readonly/> flag are added read-only.  Other disks
2080           are added read/write.
2081
2082           If "readonly" is true:
2083
2084           Disks with the <readonly/> flag are added read-only.
2085
2086       readonlydisk = "write" (default)
2087           If "readonly" is false:
2088
2089           Disks with the <readonly/> flag are added read/write.
2090
2091           If "readonly" is true:
2092
2093           Disks with the <readonly/> flag are added read-only.
2094
2095       readonlydisk = "ignore"
2096           If "readonly" is true or false:
2097
2098           Disks with the <readonly/> flag are skipped.
2099
2100       The other optional parameters are passed directly through to
2101       "guestfs_add_drive_opts".
2102
2103       On error this function returns -1.
2104
2105       (Added in 1.7.4)
2106
2107   guestfs_add_domain_va
2108        int
2109        guestfs_add_domain_va (guestfs_h *g,
2110                               const char *dom,
2111                               va_list args);
2112
2113       This is the "va_list variant" of "guestfs_add_domain".
2114
2115       See "CALLS WITH OPTIONAL ARGUMENTS".
2116
2117   guestfs_add_domain_argv
2118        int
2119        guestfs_add_domain_argv (guestfs_h *g,
2120                                 const char *dom,
2121                                 const struct guestfs_add_domain_argv *optargs);
2122
2123       This is the "argv variant" of "guestfs_add_domain".
2124
2125       See "CALLS WITH OPTIONAL ARGUMENTS".
2126
2127   guestfs_add_drive
2128        int
2129        guestfs_add_drive (guestfs_h *g,
2130                           const char *filename);
2131
2132       This function is provided for backwards compatibility with earlier
2133       versions of libguestfs.  It simply calls "guestfs_add_drive_opts" with
2134       no optional arguments.
2135
2136       (Added in 0.3)
2137
2138   guestfs_add_drive_opts
2139        int
2140        guestfs_add_drive_opts (guestfs_h *g,
2141                                const char *filename,
2142                                ...);
2143
2144       You may supply a list of optional arguments to this call.  Use zero or
2145       more of the following pairs of parameters, and terminate the list with
2146       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2147
2148        GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2149        GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2150        GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2151        GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2152        GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2153        GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2154        GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2155        GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2156        GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2157        GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2158        GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2159        GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2160
2161       This function adds a disk image called filename to the handle.
2162       filename may be a regular host file or a host device.
2163
2164       When this function is called before "guestfs_launch" (the usual case)
2165       then the first time you call this function, the disk appears in the API
2166       as /dev/sda, the second time as /dev/sdb, and so on.
2167
2168       In libguestfs ≥ 1.20 you can also call this function after launch (with
2169       some restrictions).  This is called "hotplugging".  When hotplugging,
2170       you must specify a "label" so that the new disk gets a predictable
2171       name.  For more information see "HOTPLUGGING".
2172
2173       You don't necessarily need to be root when using libguestfs.  However
2174       you obviously do need sufficient permissions to access the filename for
2175       whatever operations you want to perform (ie. read access if you just
2176       want to read the image or write access if you want to modify the
2177       image).
2178
2179       This call checks that filename exists.
2180
2181       filename may be the special string "/dev/null".  See "NULL DISKS".
2182
2183       The optional arguments are:
2184
2185       "readonly"
2186           If true then the image is treated as read-only.  Writes are still
2187           allowed, but they are stored in a temporary snapshot overlay which
2188           is discarded at the end.  The disk that you add is not modified.
2189
2190       "format"
2191           This forces the image format.  If you omit this (or use
2192           "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2193           automatically detected.  Possible formats include "raw" and
2194           "qcow2".
2195
2196           Automatic detection of the format opens you up to a potential
2197           security hole when dealing with untrusted raw-format images.  See
2198           CVE-2010-3851 and RHBZ#642934.  Specifying the format closes this
2199           security hole.
2200
2201       "iface"
2202           This rarely-used option lets you emulate the behaviour of the
2203           deprecated "guestfs_add_drive_with_if" call (q.v.)
2204
2205       "name"
2206           The name the drive had in the original guest, e.g. /dev/sdb.  This
2207           is used as a hint to the guest inspection process if it is
2208           available.
2209
2210       "label"
2211           Give the disk a label.  The label should be a unique, short string
2212           using only ASCII characters "[a-zA-Z]".  As well as its usual name
2213           in the API (such as /dev/sda), the drive will also be named
2214           /dev/disk/guestfs/label.
2215
2216           See "DISK LABELS".
2217
2218       "protocol"
2219           The optional protocol argument can be used to select an alternate
2220           source protocol.
2221
2222           See also: "REMOTE STORAGE".
2223
2224           "protocol = "file""
2225               filename is interpreted as a local file or device.  This is the
2226               default if the optional protocol parameter is omitted.
2227
2228           "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
2229               Connect to a remote FTP, HTTP or TFTP server.  The "server"
2230               parameter must also be supplied - see below.
2231
2232               See also: "FTP, HTTP AND TFTP"
2233
2234           "protocol = "gluster""
2235               Connect to the GlusterFS server.  The "server" parameter must
2236               also be supplied - see below.
2237
2238               See also: "GLUSTER"
2239
2240           "protocol = "iscsi""
2241               Connect to the iSCSI server.  The "server" parameter must also
2242               be supplied - see below.  The "username" parameter may be
2243               supplied.  See below.  The "secret" parameter may be supplied.
2244               See below.
2245
2246               See also: "ISCSI".
2247
2248           "protocol = "nbd""
2249               Connect to the Network Block Device server.  The "server"
2250               parameter must also be supplied - see below.
2251
2252               See also: "NETWORK BLOCK DEVICE".
2253
2254           "protocol = "rbd""
2255               Connect to the Ceph (librbd/RBD) server.  The "server"
2256               parameter must also be supplied - see below.  The "username"
2257               parameter may be supplied.  See below.  The "secret" parameter
2258               may be supplied.  See below.
2259
2260               See also: "CEPH".
2261
2262           "protocol = "sheepdog""
2263               Connect to the Sheepdog server.  The "server" parameter may
2264               also be supplied - see below.
2265
2266               See also: "SHEEPDOG".
2267
2268           "protocol = "ssh""
2269               Connect to the Secure Shell (ssh) server.
2270
2271               The "server" parameter must be supplied.  The "username"
2272               parameter may be supplied.  See below.
2273
2274               See also: "SSH".
2275
2276       "server"
2277           For protocols which require access to a remote server, this is a
2278           list of server(s).
2279
2280            Protocol       Number of servers required
2281            --------       --------------------------
2282            file           List must be empty or param not used at all
2283            ftp|ftps|http|https|tftp  Exactly one
2284            gluster        Exactly one
2285            iscsi          Exactly one
2286            nbd            Exactly one
2287            rbd            Zero or more
2288            sheepdog       Zero or more
2289            ssh            Exactly one
2290
2291           Each list element is a string specifying a server.  The string must
2292           be in one of the following formats:
2293
2294            hostname
2295            hostname:port
2296            tcp:hostname
2297            tcp:hostname:port
2298            unix:/path/to/socket
2299
2300           If the port number is omitted, then the standard port number for
2301           the protocol is used (see /etc/services).
2302
2303       "username"
2304           For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
2305           "tftp" protocols, this specifies the remote username.
2306
2307           If not given, then the local username is used for "ssh", and no
2308           authentication is attempted for ceph.  But note this sometimes may
2309           give unexpected results, for example if using the libvirt backend
2310           and if the libvirt backend is configured to start the qemu
2311           appliance as a special user such as "qemu.qemu".  If in doubt,
2312           specify the remote username you want.
2313
2314       "secret"
2315           For the "rbd" protocol only, this specifies the ‘secret’ to use
2316           when connecting to the remote device.  It must be base64 encoded.
2317
2318           If not given, then a secret matching the given username will be
2319           looked up in the default keychain locations, or if no username is
2320           given, then no authentication will be used.
2321
2322       "cachemode"
2323           Choose whether or not libguestfs will obey sync operations (safe
2324           but slow) or not (unsafe but fast).  The possible values for this
2325           string are:
2326
2327           "cachemode = "writeback""
2328               This is the default.
2329
2330               Write operations in the API do not return until a write(2) call
2331               has completed in the host [but note this does not imply that
2332               anything gets written to disk].
2333
2334               Sync operations in the API, including implicit syncs caused by
2335               filesystem journalling, will not return until an fdatasync(2)
2336               call has completed in the host, indicating that data has been
2337               committed to disk.
2338
2339           "cachemode = "unsafe""
2340               In this mode, there are no guarantees.  Libguestfs may cache
2341               anything and ignore sync requests.  This is suitable only for
2342               scratch or temporary disks.
2343
2344       "discard"
2345           Enable or disable discard (a.k.a. trim or unmap) support on this
2346           drive.  If enabled, operations such as "guestfs_fstrim" will be
2347           able to discard / make thin / punch holes in the underlying host
2348           file or device.
2349
2350           Possible discard settings are:
2351
2352           "discard = "disable""
2353               Disable discard support.  This is the default.
2354
2355           "discard = "enable""
2356               Enable discard support.  Fail if discard is not possible.
2357
2358           "discard = "besteffort""
2359               Enable discard support if possible, but don't fail if it is not
2360               supported.
2361
2362               Since not all backends and not all underlying systems support
2363               discard, this is a good choice if you want to use discard if
2364               possible, but don't mind if it doesn't work.
2365
2366       "copyonread"
2367           The boolean parameter "copyonread" enables copy-on-read support.
2368           This only affects disk formats which have backing files, and causes
2369           reads to be stored in the overlay layer, speeding up multiple reads
2370           of the same area of disk.
2371
2372           The default is false.
2373
2374       This function returns 0 on success or -1 on error.
2375
2376       (Added in 0.3)
2377
2378   guestfs_add_drive_opts_va
2379        int
2380        guestfs_add_drive_opts_va (guestfs_h *g,
2381                                   const char *filename,
2382                                   va_list args);
2383
2384       This is the "va_list variant" of "guestfs_add_drive_opts".
2385
2386       See "CALLS WITH OPTIONAL ARGUMENTS".
2387
2388   guestfs_add_drive_opts_argv
2389        int
2390        guestfs_add_drive_opts_argv (guestfs_h *g,
2391                                     const char *filename,
2392                                     const struct guestfs_add_drive_opts_argv *optargs);
2393
2394       This is the "argv variant" of "guestfs_add_drive_opts".
2395
2396       See "CALLS WITH OPTIONAL ARGUMENTS".
2397
2398   guestfs_add_drive_ro
2399        int
2400        guestfs_add_drive_ro (guestfs_h *g,
2401                              const char *filename);
2402
2403       This function is the equivalent of calling "guestfs_add_drive_opts"
2404       with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2405       so the disk is added read-only, with the format being detected
2406       automatically.
2407
2408       This function returns 0 on success or -1 on error.
2409
2410       (Added in 1.0.38)
2411
2412   guestfs_add_drive_ro_with_if
2413        int
2414        guestfs_add_drive_ro_with_if (guestfs_h *g,
2415                                      const char *filename,
2416                                      const char *iface);
2417
2418       This function is deprecated.  In new code, use the "guestfs_add_drive"
2419       call instead.
2420
2421       Deprecated functions will not be removed from the API, but the fact
2422       that they are deprecated indicates that there are problems with correct
2423       use of these functions.
2424
2425       This is the same as "guestfs_add_drive_ro" but it allows you to specify
2426       the QEMU interface emulation to use at run time.
2427
2428       This function returns 0 on success or -1 on error.
2429
2430       (Added in 1.0.84)
2431
2432   guestfs_add_drive_scratch
2433        int
2434        guestfs_add_drive_scratch (guestfs_h *g,
2435                                   int64_t size,
2436                                   ...);
2437
2438       You may supply a list of optional arguments to this call.  Use zero or
2439       more of the following pairs of parameters, and terminate the list with
2440       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2441
2442        GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2443        GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2444
2445       This command adds a temporary scratch drive to the handle.  The "size"
2446       parameter is the virtual size (in bytes).  The scratch drive is blank
2447       initially (all reads return zeroes until you start writing to it).  The
2448       drive is deleted when the handle is closed.
2449
2450       The optional arguments "name" and "label" are passed through to
2451       "guestfs_add_drive".
2452
2453       This function returns 0 on success or -1 on error.
2454
2455       (Added in 1.23.10)
2456
2457   guestfs_add_drive_scratch_va
2458        int
2459        guestfs_add_drive_scratch_va (guestfs_h *g,
2460                                      int64_t size,
2461                                      va_list args);
2462
2463       This is the "va_list variant" of "guestfs_add_drive_scratch".
2464
2465       See "CALLS WITH OPTIONAL ARGUMENTS".
2466
2467   guestfs_add_drive_scratch_argv
2468        int
2469        guestfs_add_drive_scratch_argv (guestfs_h *g,
2470                                        int64_t size,
2471                                        const struct guestfs_add_drive_scratch_argv *optargs);
2472
2473       This is the "argv variant" of "guestfs_add_drive_scratch".
2474
2475       See "CALLS WITH OPTIONAL ARGUMENTS".
2476
2477   guestfs_add_drive_with_if
2478        int
2479        guestfs_add_drive_with_if (guestfs_h *g,
2480                                   const char *filename,
2481                                   const char *iface);
2482
2483       This function is deprecated.  In new code, use the "guestfs_add_drive"
2484       call instead.
2485
2486       Deprecated functions will not be removed from the API, but the fact
2487       that they are deprecated indicates that there are problems with correct
2488       use of these functions.
2489
2490       This is the same as "guestfs_add_drive" but it allows you to specify
2491       the QEMU interface emulation to use at run time.
2492
2493       This function returns 0 on success or -1 on error.
2494
2495       (Added in 1.0.84)
2496
2497   guestfs_add_libvirt_dom
2498        int
2499        guestfs_add_libvirt_dom (guestfs_h *g,
2500                                 void * /* really virDomainPtr */ dom,
2501                                 ...);
2502
2503       You may supply a list of optional arguments to this call.  Use zero or
2504       more of the following pairs of parameters, and terminate the list with
2505       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2506
2507        GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2508        GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2509        GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2510        GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2511        GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2512        GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2513        GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2514
2515       This function adds the disk(s) attached to the libvirt domain "dom".
2516       It works by requesting the domain XML from libvirt, parsing it for
2517       disks, and calling "guestfs_add_drive_opts" on each one.
2518
2519       In the C API we declare "void *dom", but really it has type
2520       "virDomainPtr dom".  This is so we don't need <libvirt.h>.
2521
2522       The number of disks added is returned.  This operation is atomic: if an
2523       error is returned, then no disks are added.
2524
2525       This function does some minimal checks to make sure the libvirt domain
2526       is not running (unless "readonly" is true).  In a future version we
2527       will try to acquire the libvirt lock on each disk.
2528
2529       Disks must be accessible locally.  This often means that adding disks
2530       from a remote libvirt connection (see http://libvirt.org/remote.html)
2531       will fail unless those disks are accessible via the same device path
2532       locally too.
2533
2534       The optional "live" flag controls whether this call will try to connect
2535       to a running virtual machine "guestfsd" process if it sees a suitable
2536       <channel> element in the libvirt XML definition.  The default (if the
2537       flag is omitted) is never to try.  See "ATTACHING TO RUNNING DAEMONS"
2538       for more information.
2539
2540       The optional "readonlydisk" parameter controls what we do for disks
2541       which are marked <readonly/> in the libvirt XML.  See
2542       "guestfs_add_domain" for possible values.
2543
2544       The other optional parameters are passed directly through to
2545       "guestfs_add_drive_opts".
2546
2547       On error this function returns -1.
2548
2549       (Added in 1.29.14)
2550
2551   guestfs_add_libvirt_dom_va
2552        int
2553        guestfs_add_libvirt_dom_va (guestfs_h *g,
2554                                    void * /* really virDomainPtr */ dom,
2555                                    va_list args);
2556
2557       This is the "va_list variant" of "guestfs_add_libvirt_dom".
2558
2559       See "CALLS WITH OPTIONAL ARGUMENTS".
2560
2561   guestfs_add_libvirt_dom_argv
2562        int
2563        guestfs_add_libvirt_dom_argv (guestfs_h *g,
2564                                      void * /* really virDomainPtr */ dom,
2565                                      const struct guestfs_add_libvirt_dom_argv *optargs);
2566
2567       This is the "argv variant" of "guestfs_add_libvirt_dom".
2568
2569       See "CALLS WITH OPTIONAL ARGUMENTS".
2570
2571   guestfs_aug_clear
2572        int
2573        guestfs_aug_clear (guestfs_h *g,
2574                           const char *augpath);
2575
2576       Set the value associated with "path" to "NULL".  This is the same as
2577       the augtool(1) "clear" command.
2578
2579       This function returns 0 on success or -1 on error.
2580
2581       (Added in 1.3.4)
2582
2583   guestfs_aug_close
2584        int
2585        guestfs_aug_close (guestfs_h *g);
2586
2587       Close the current Augeas handle and free up any resources used by it.
2588       After calling this, you have to call "guestfs_aug_init" again before
2589       you can use any other Augeas functions.
2590
2591       This function returns 0 on success or -1 on error.
2592
2593       (Added in 0.7)
2594
2595   guestfs_aug_defnode
2596        struct guestfs_int_bool *
2597        guestfs_aug_defnode (guestfs_h *g,
2598                             const char *name,
2599                             const char *expr,
2600                             const char *val);
2601
2602       Defines a variable "name" whose value is the result of evaluating
2603       "expr".
2604
2605       If "expr" evaluates to an empty nodeset, a node is created, equivalent
2606       to calling "guestfs_aug_set" "expr", "value".  "name" will be the
2607       nodeset containing that single node.
2608
2609       On success this returns a pair containing the number of nodes in the
2610       nodeset, and a boolean flag if a node was created.
2611
2612       This function returns a "struct guestfs_int_bool *", or NULL if there
2613       was an error.  The caller must call "guestfs_free_int_bool" after use.
2614
2615       (Added in 0.7)
2616
2617   guestfs_aug_defvar
2618        int
2619        guestfs_aug_defvar (guestfs_h *g,
2620                            const char *name,
2621                            const char *expr);
2622
2623       Defines an Augeas variable "name" whose value is the result of
2624       evaluating "expr".  If "expr" is NULL, then "name" is undefined.
2625
2626       On success this returns the number of nodes in "expr", or 0 if "expr"
2627       evaluates to something which is not a nodeset.
2628
2629       On error this function returns -1.
2630
2631       (Added in 0.7)
2632
2633   guestfs_aug_get
2634        char *
2635        guestfs_aug_get (guestfs_h *g,
2636                         const char *augpath);
2637
2638       Look up the value associated with "path".  If "path" matches exactly
2639       one node, the "value" is returned.
2640
2641       This function returns a string, or NULL on error.  The caller must free
2642       the returned string after use.
2643
2644       (Added in 0.7)
2645
2646   guestfs_aug_init
2647        int
2648        guestfs_aug_init (guestfs_h *g,
2649                          const char *root,
2650                          int flags);
2651
2652       Create a new Augeas handle for editing configuration files.  If there
2653       was any previous Augeas handle associated with this guestfs session,
2654       then it is closed.
2655
2656       You must call this before using any other "guestfs_aug_*" commands.
2657
2658       "root" is the filesystem root.  "root" must not be NULL, use / instead.
2659
2660       The flags are the same as the flags defined in <augeas.h>, the logical
2661       or of the following integers:
2662
2663       "AUG_SAVE_BACKUP" = 1
2664           Keep the original file with a ".augsave" extension.
2665
2666       "AUG_SAVE_NEWFILE" = 2
2667           Save changes into a file with extension ".augnew", and do not
2668           overwrite original.  Overrides "AUG_SAVE_BACKUP".
2669
2670       "AUG_TYPE_CHECK" = 4
2671           Typecheck lenses.
2672
2673           This option is only useful when debugging Augeas lenses.  Use of
2674           this option may require additional memory for the libguestfs
2675           appliance.  You may need to set the "LIBGUESTFS_MEMSIZE"
2676           environment variable or call "guestfs_set_memsize".
2677
2678       "AUG_NO_STDINC" = 8
2679           Do not use standard load path for modules.
2680
2681       "AUG_SAVE_NOOP" = 16
2682           Make save a no-op, just record what would have been changed.
2683
2684       "AUG_NO_LOAD" = 32
2685           Do not load the tree in "guestfs_aug_init".
2686
2687       To close the handle, you can call "guestfs_aug_close".
2688
2689       To find out more about Augeas, see http://augeas.net/.
2690
2691       This function returns 0 on success or -1 on error.
2692
2693       (Added in 0.7)
2694
2695   guestfs_aug_insert
2696        int
2697        guestfs_aug_insert (guestfs_h *g,
2698                            const char *augpath,
2699                            const char *label,
2700                            int before);
2701
2702       Create a new sibling "label" for "path", inserting it into the tree
2703       before or after "path" (depending on the boolean flag "before").
2704
2705       "path" must match exactly one existing node in the tree, and "label"
2706       must be a label, ie. not contain /, "*" or end with a bracketed index
2707       "[N]".
2708
2709       This function returns 0 on success or -1 on error.
2710
2711       (Added in 0.7)
2712
2713   guestfs_aug_label
2714        char *
2715        guestfs_aug_label (guestfs_h *g,
2716                           const char *augpath);
2717
2718       The label (name of the last element) of the Augeas path expression
2719       "augpath" is returned.  "augpath" must match exactly one node, else
2720       this function returns an error.
2721
2722       This function returns a string, or NULL on error.  The caller must free
2723       the returned string after use.
2724
2725       (Added in 1.23.14)
2726
2727   guestfs_aug_load
2728        int
2729        guestfs_aug_load (guestfs_h *g);
2730
2731       Load files into the tree.
2732
2733       See "aug_load" in the Augeas documentation for the full gory details.
2734
2735       This function returns 0 on success or -1 on error.
2736
2737       (Added in 0.7)
2738
2739   guestfs_aug_ls
2740        char **
2741        guestfs_aug_ls (guestfs_h *g,
2742                        const char *augpath);
2743
2744       This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2745       sorting the resulting nodes into alphabetical order.
2746
2747       This function returns a NULL-terminated array of strings (like
2748       environ(3)), or NULL if there was an error.  The caller must free the
2749       strings and the array after use.
2750
2751       (Added in 0.8)
2752
2753   guestfs_aug_match
2754        char **
2755        guestfs_aug_match (guestfs_h *g,
2756                           const char *augpath);
2757
2758       Returns a list of paths which match the path expression "path".  The
2759       returned paths are sufficiently qualified so that they match exactly
2760       one node in the current tree.
2761
2762       This function returns a NULL-terminated array of strings (like
2763       environ(3)), or NULL if there was an error.  The caller must free the
2764       strings and the array after use.
2765
2766       (Added in 0.7)
2767
2768   guestfs_aug_mv
2769        int
2770        guestfs_aug_mv (guestfs_h *g,
2771                        const char *src,
2772                        const char *dest);
2773
2774       Move the node "src" to "dest".  "src" must match exactly one node.
2775       "dest" is overwritten if it exists.
2776
2777       This function returns 0 on success or -1 on error.
2778
2779       (Added in 0.7)
2780
2781   guestfs_aug_rm
2782        int
2783        guestfs_aug_rm (guestfs_h *g,
2784                        const char *augpath);
2785
2786       Remove "path" and all of its children.
2787
2788       On success this returns the number of entries which were removed.
2789
2790       On error this function returns -1.
2791
2792       (Added in 0.7)
2793
2794   guestfs_aug_save
2795        int
2796        guestfs_aug_save (guestfs_h *g);
2797
2798       This writes all pending changes to disk.
2799
2800       The flags which were passed to "guestfs_aug_init" affect exactly how
2801       files are saved.
2802
2803       This function returns 0 on success or -1 on error.
2804
2805       (Added in 0.7)
2806
2807   guestfs_aug_set
2808        int
2809        guestfs_aug_set (guestfs_h *g,
2810                         const char *augpath,
2811                         const char *val);
2812
2813       Set the value associated with "path" to "val".
2814
2815       In the Augeas API, it is possible to clear a node by setting the value
2816       to NULL.  Due to an oversight in the libguestfs API you cannot do that
2817       with this call.  Instead you must use the "guestfs_aug_clear" call.
2818
2819       This function returns 0 on success or -1 on error.
2820
2821       (Added in 0.7)
2822
2823   guestfs_aug_setm
2824        int
2825        guestfs_aug_setm (guestfs_h *g,
2826                          const char *base,
2827                          const char *sub,
2828                          const char *val);
2829
2830       Change multiple Augeas nodes in a single operation.  "base" is an
2831       expression matching multiple nodes.  "sub" is a path expression
2832       relative to "base".  All nodes matching "base" are found, and then for
2833       each node, "sub" is changed to "val".  "sub" may also be "NULL" in
2834       which case the "base" nodes are modified.
2835
2836       This returns the number of nodes modified.
2837
2838       On error this function returns -1.
2839
2840       (Added in 1.23.14)
2841
2842   guestfs_aug_transform
2843        int
2844        guestfs_aug_transform (guestfs_h *g,
2845                               const char *lens,
2846                               const char *file,
2847                               ...);
2848
2849       You may supply a list of optional arguments to this call.  Use zero or
2850       more of the following pairs of parameters, and terminate the list with
2851       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2852
2853        GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2854
2855       Add an Augeas transformation for the specified "lens" so it can handle
2856       "file".
2857
2858       If "remove" is true ("false" by default), then the transformation is
2859       removed.
2860
2861       This function returns 0 on success or -1 on error.
2862
2863       (Added in 1.35.2)
2864
2865   guestfs_aug_transform_va
2866        int
2867        guestfs_aug_transform_va (guestfs_h *g,
2868                                  const char *lens,
2869                                  const char *file,
2870                                  va_list args);
2871
2872       This is the "va_list variant" of "guestfs_aug_transform".
2873
2874       See "CALLS WITH OPTIONAL ARGUMENTS".
2875
2876   guestfs_aug_transform_argv
2877        int
2878        guestfs_aug_transform_argv (guestfs_h *g,
2879                                    const char *lens,
2880                                    const char *file,
2881                                    const struct guestfs_aug_transform_argv *optargs);
2882
2883       This is the "argv variant" of "guestfs_aug_transform".
2884
2885       See "CALLS WITH OPTIONAL ARGUMENTS".
2886
2887   guestfs_available
2888        int
2889        guestfs_available (guestfs_h *g,
2890                           char *const *groups);
2891
2892       This command is used to check the availability of some groups of
2893       functionality in the appliance, which not all builds of the libguestfs
2894       appliance will be able to provide.
2895
2896       The libguestfs groups, and the functions that those groups correspond
2897       to, are listed in "AVAILABILITY".  You can also fetch this list at
2898       runtime by calling "guestfs_available_all_groups".
2899
2900       The argument "groups" is a list of group names, eg: "["inotify",
2901       "augeas"]" would check for the availability of the Linux inotify
2902       functions and Augeas (configuration file editing) functions.
2903
2904       The command returns no error if all requested groups are available.
2905
2906       It fails with an error if one or more of the requested groups is
2907       unavailable in the appliance.
2908
2909       If an unknown group name is included in the list of groups then an
2910       error is always returned.
2911
2912       Notes:
2913
2914       ·   "guestfs_feature_available" is the same as this call, but with a
2915           slightly simpler to use API: that call returns a boolean true/false
2916           instead of throwing an error.
2917
2918       ·   You must call "guestfs_launch" before calling this function.
2919
2920           The reason is because we don't know what groups are supported by
2921           the appliance/daemon until it is running and can be queried.
2922
2923       ·   If a group of functions is available, this does not necessarily
2924           mean that they will work.  You still have to check for errors when
2925           calling individual API functions even if they are available.
2926
2927       ·   It is usually the job of distro packagers to build complete
2928           functionality into the libguestfs appliance.  Upstream libguestfs,
2929           if built from source with all requirements satisfied, will support
2930           everything.
2931
2932       ·   This call was added in version 1.0.80.  In previous versions of
2933           libguestfs all you could do would be to speculatively execute a
2934           command to find out if the daemon implemented it.  See also
2935           "guestfs_version".
2936
2937       See also "guestfs_filesystem_available".
2938
2939       This function returns 0 on success or -1 on error.
2940
2941       (Added in 1.0.80)
2942
2943   guestfs_available_all_groups
2944        char **
2945        guestfs_available_all_groups (guestfs_h *g);
2946
2947       This command returns a list of all optional groups that this daemon
2948       knows about.  Note this returns both supported and unsupported groups.
2949       To find out which ones the daemon can actually support you have to call
2950       "guestfs_available" / "guestfs_feature_available" on each member of the
2951       returned list.
2952
2953       See also "guestfs_available", "guestfs_feature_available" and
2954       "AVAILABILITY".
2955
2956       This function returns a NULL-terminated array of strings (like
2957       environ(3)), or NULL if there was an error.  The caller must free the
2958       strings and the array after use.
2959
2960       (Added in 1.3.15)
2961
2962   guestfs_base64_in
2963        int
2964        guestfs_base64_in (guestfs_h *g,
2965                           const char *base64file,
2966                           const char *filename);
2967
2968       This command uploads base64-encoded data from "base64file" to filename.
2969
2970       This function returns 0 on success or -1 on error.
2971
2972       (Added in 1.3.5)
2973
2974   guestfs_base64_out
2975        int
2976        guestfs_base64_out (guestfs_h *g,
2977                            const char *filename,
2978                            const char *base64file);
2979
2980       This command downloads the contents of filename, writing it out to
2981       local file "base64file" encoded as base64.
2982
2983       This function returns 0 on success or -1 on error.
2984
2985       (Added in 1.3.5)
2986
2987   guestfs_blkdiscard
2988        int
2989        guestfs_blkdiscard (guestfs_h *g,
2990                            const char *device);
2991
2992       This discards all blocks on the block device "device", giving the free
2993       space back to the host.
2994
2995       This operation requires support in libguestfs, the host filesystem,
2996       qemu and the host kernel.  If this support isn't present it may give an
2997       error or even appear to run but do nothing.  You must also set the
2998       "discard" attribute on the underlying drive (see
2999       "guestfs_add_drive_opts").
3000
3001       This function returns 0 on success or -1 on error.
3002
3003       This function depends on the feature "blkdiscard".  See also
3004       "guestfs_feature_available".
3005
3006       (Added in 1.25.44)
3007
3008   guestfs_blkdiscardzeroes
3009        int
3010        guestfs_blkdiscardzeroes (guestfs_h *g,
3011                                  const char *device);
3012
3013       This call returns true if blocks on "device" that have been discarded
3014       by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
3015       when read the next time.
3016
3017       If it returns false, then it may be that discarded blocks are read as
3018       stale or random data.
3019
3020       This function returns a C truth value on success or -1 on error.
3021
3022       This function depends on the feature "blkdiscardzeroes".  See also
3023       "guestfs_feature_available".
3024
3025       (Added in 1.25.44)
3026
3027   guestfs_blkid
3028        char **
3029        guestfs_blkid (guestfs_h *g,
3030                       const char *device);
3031
3032       This command returns block device attributes for "device". The
3033       following fields are usually present in the returned hash. Other fields
3034       may also be present.
3035
3036       "UUID"
3037           The uuid of this device.
3038
3039       "LABEL"
3040           The label of this device.
3041
3042       "VERSION"
3043           The version of blkid command.
3044
3045       "TYPE"
3046           The filesystem type or RAID of this device.
3047
3048       "USAGE"
3049           The usage of this device, for example "filesystem" or "raid".
3050
3051       This function returns a NULL-terminated array of strings, or NULL if
3052       there was an error.  The array of strings will always have length
3053       "2n+1", where "n" keys and values alternate, followed by the trailing
3054       NULL entry.  The caller must free the strings and the array after use.
3055
3056       (Added in 1.15.9)
3057
3058   guestfs_blockdev_flushbufs
3059        int
3060        guestfs_blockdev_flushbufs (guestfs_h *g,
3061                                    const char *device);
3062
3063       This tells the kernel to flush internal buffers associated with
3064       "device".
3065
3066       This uses the blockdev(8) command.
3067
3068       This function returns 0 on success or -1 on error.
3069
3070       (Added in 1.9.3)
3071
3072   guestfs_blockdev_getbsz
3073        int
3074        guestfs_blockdev_getbsz (guestfs_h *g,
3075                                 const char *device);
3076
3077       This returns the block size of a device.
3078
3079       Note: this is different from both size in blocks and filesystem block
3080       size.  Also this setting is not really used by anything.  You should
3081       probably not use it for anything.  Filesystems have their own idea
3082       about what block size to choose.
3083
3084       This uses the blockdev(8) command.
3085
3086       On error this function returns -1.
3087
3088       (Added in 1.9.3)
3089
3090   guestfs_blockdev_getro
3091        int
3092        guestfs_blockdev_getro (guestfs_h *g,
3093                                const char *device);
3094
3095       Returns a boolean indicating if the block device is read-only (true if
3096       read-only, false if not).
3097
3098       This uses the blockdev(8) command.
3099
3100       This function returns a C truth value on success or -1 on error.
3101
3102       (Added in 1.9.3)
3103
3104   guestfs_blockdev_getsize64
3105        int64_t
3106        guestfs_blockdev_getsize64 (guestfs_h *g,
3107                                    const char *device);
3108
3109       This returns the size of the device in bytes.
3110
3111       See also "guestfs_blockdev_getsz".
3112
3113       This uses the blockdev(8) command.
3114
3115       On error this function returns -1.
3116
3117       (Added in 1.9.3)
3118
3119   guestfs_blockdev_getss
3120        int
3121        guestfs_blockdev_getss (guestfs_h *g,
3122                                const char *device);
3123
3124       This returns the size of sectors on a block device.  Usually 512, but
3125       can be larger for modern devices.
3126
3127       (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
3128       for that).
3129
3130       This uses the blockdev(8) command.
3131
3132       On error this function returns -1.
3133
3134       (Added in 1.9.3)
3135
3136   guestfs_blockdev_getsz
3137        int64_t
3138        guestfs_blockdev_getsz (guestfs_h *g,
3139                                const char *device);
3140
3141       This returns the size of the device in units of 512-byte sectors (even
3142       if the sectorsize isn't 512 bytes ... weird).
3143
3144       See also "guestfs_blockdev_getss" for the real sector size of the
3145       device, and "guestfs_blockdev_getsize64" for the more useful size in
3146       bytes.
3147
3148       This uses the blockdev(8) command.
3149
3150       On error this function returns -1.
3151
3152       (Added in 1.9.3)
3153
3154   guestfs_blockdev_rereadpt
3155        int
3156        guestfs_blockdev_rereadpt (guestfs_h *g,
3157                                   const char *device);
3158
3159       Reread the partition table on "device".
3160
3161       This uses the blockdev(8) command.
3162
3163       This function returns 0 on success or -1 on error.
3164
3165       (Added in 1.9.3)
3166
3167   guestfs_blockdev_setbsz
3168        int
3169        guestfs_blockdev_setbsz (guestfs_h *g,
3170                                 const char *device,
3171                                 int blocksize);
3172
3173       This function is deprecated.  There is no replacement.  Consult the API
3174       documentation in guestfs(3) for further information.
3175
3176       Deprecated functions will not be removed from the API, but the fact
3177       that they are deprecated indicates that there are problems with correct
3178       use of these functions.
3179
3180       This call does nothing and has never done anything because of a bug in
3181       blockdev.  Do not use it.
3182
3183       If you need to set the filesystem block size, use the "blocksize"
3184       option of "guestfs_mkfs".
3185
3186       This function returns 0 on success or -1 on error.
3187
3188       (Added in 1.9.3)
3189
3190   guestfs_blockdev_setra
3191        int
3192        guestfs_blockdev_setra (guestfs_h *g,
3193                                const char *device,
3194                                int sectors);
3195
3196       Set readahead (in 512-byte sectors) for the device.
3197
3198       This uses the blockdev(8) command.
3199
3200       This function returns 0 on success or -1 on error.
3201
3202       (Added in 1.29.10)
3203
3204   guestfs_blockdev_setro
3205        int
3206        guestfs_blockdev_setro (guestfs_h *g,
3207                                const char *device);
3208
3209       Sets the block device named "device" to read-only.
3210
3211       This uses the blockdev(8) command.
3212
3213       This function returns 0 on success or -1 on error.
3214
3215       (Added in 1.9.3)
3216
3217   guestfs_blockdev_setrw
3218        int
3219        guestfs_blockdev_setrw (guestfs_h *g,
3220                                const char *device);
3221
3222       Sets the block device named "device" to read-write.
3223
3224       This uses the blockdev(8) command.
3225
3226       This function returns 0 on success or -1 on error.
3227
3228       (Added in 1.9.3)
3229
3230   guestfs_btrfs_balance_cancel
3231        int
3232        guestfs_btrfs_balance_cancel (guestfs_h *g,
3233                                      const char *path);
3234
3235       Cancel a running balance on a btrfs filesystem.
3236
3237       This function returns 0 on success or -1 on error.
3238
3239       This function depends on the feature "btrfs".  See also
3240       "guestfs_feature_available".
3241
3242       (Added in 1.29.22)
3243
3244   guestfs_btrfs_balance_pause
3245        int
3246        guestfs_btrfs_balance_pause (guestfs_h *g,
3247                                     const char *path);
3248
3249       Pause a running balance on a btrfs filesystem.
3250
3251       This function returns 0 on success or -1 on error.
3252
3253       This function depends on the feature "btrfs".  See also
3254       "guestfs_feature_available".
3255
3256       (Added in 1.29.22)
3257
3258   guestfs_btrfs_balance_resume
3259        int
3260        guestfs_btrfs_balance_resume (guestfs_h *g,
3261                                      const char *path);
3262
3263       Resume a paused balance on a btrfs filesystem.
3264
3265       This function returns 0 on success or -1 on error.
3266
3267       This function depends on the feature "btrfs".  See also
3268       "guestfs_feature_available".
3269
3270       (Added in 1.29.22)
3271
3272   guestfs_btrfs_balance_status
3273        struct guestfs_btrfsbalance *
3274        guestfs_btrfs_balance_status (guestfs_h *g,
3275                                      const char *path);
3276
3277       Show the status of a running or paused balance on a btrfs filesystem.
3278
3279       This function returns a "struct guestfs_btrfsbalance *", or NULL if
3280       there was an error.  The caller must call "guestfs_free_btrfsbalance"
3281       after use.
3282
3283       This function depends on the feature "btrfs".  See also
3284       "guestfs_feature_available".
3285
3286       (Added in 1.29.26)
3287
3288   guestfs_btrfs_device_add
3289        int
3290        guestfs_btrfs_device_add (guestfs_h *g,
3291                                  char *const *devices,
3292                                  const char *fs);
3293
3294       Add the list of device(s) in "devices" to the btrfs filesystem mounted
3295       at "fs".  If "devices" is an empty list, this does nothing.
3296
3297       This function returns 0 on success or -1 on error.
3298
3299       This function depends on the feature "btrfs".  See also
3300       "guestfs_feature_available".
3301
3302       (Added in 1.17.35)
3303
3304   guestfs_btrfs_device_delete
3305        int
3306        guestfs_btrfs_device_delete (guestfs_h *g,
3307                                     char *const *devices,
3308                                     const char *fs);
3309
3310       Remove the "devices" from the btrfs filesystem mounted at "fs".  If
3311       "devices" is an empty list, this does nothing.
3312
3313       This function returns 0 on success or -1 on error.
3314
3315       This function depends on the feature "btrfs".  See also
3316       "guestfs_feature_available".
3317
3318       (Added in 1.17.35)
3319
3320   guestfs_btrfs_filesystem_balance
3321        int
3322        guestfs_btrfs_filesystem_balance (guestfs_h *g,
3323                                          const char *fs);
3324
3325       Balance the chunks in the btrfs filesystem mounted at "fs" across the
3326       underlying devices.
3327
3328       This function returns 0 on success or -1 on error.
3329
3330       This function depends on the feature "btrfs".  See also
3331       "guestfs_feature_available".
3332
3333       (Added in 1.17.35)
3334
3335   guestfs_btrfs_filesystem_defragment
3336        int
3337        guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3338                                             const char *path,
3339                                             ...);
3340
3341       You may supply a list of optional arguments to this call.  Use zero or
3342       more of the following pairs of parameters, and terminate the list with
3343       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3344
3345        GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3346        GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3347
3348       Defragment a file or directory on a btrfs filesystem. compress is one
3349       of zlib or lzo.
3350
3351       This function returns 0 on success or -1 on error.
3352
3353       This function depends on the feature "btrfs".  See also
3354       "guestfs_feature_available".
3355
3356       (Added in 1.29.22)
3357
3358   guestfs_btrfs_filesystem_defragment_va
3359        int
3360        guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3361                                                const char *path,
3362                                                va_list args);
3363
3364       This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3365
3366       See "CALLS WITH OPTIONAL ARGUMENTS".
3367
3368   guestfs_btrfs_filesystem_defragment_argv
3369        int
3370        guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3371                                                  const char *path,
3372                                                  const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3373
3374       This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3375
3376       See "CALLS WITH OPTIONAL ARGUMENTS".
3377
3378   guestfs_btrfs_filesystem_resize
3379        int
3380        guestfs_btrfs_filesystem_resize (guestfs_h *g,
3381                                         const char *mountpoint,
3382                                         ...);
3383
3384       You may supply a list of optional arguments to this call.  Use zero or
3385       more of the following pairs of parameters, and terminate the list with
3386       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3387
3388        GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3389
3390       This command resizes a btrfs filesystem.
3391
3392       Note that unlike other resize calls, the filesystem has to be mounted
3393       and the parameter is the mountpoint not the device (this is a
3394       requirement of btrfs itself).
3395
3396       The optional parameters are:
3397
3398       "size"
3399           The new size (in bytes) of the filesystem.  If omitted, the
3400           filesystem is resized to the maximum size.
3401
3402       See also btrfs(8).
3403
3404       This function returns 0 on success or -1 on error.
3405
3406       This function depends on the feature "btrfs".  See also
3407       "guestfs_feature_available".
3408
3409       (Added in 1.11.17)
3410
3411   guestfs_btrfs_filesystem_resize_va
3412        int
3413        guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3414                                            const char *mountpoint,
3415                                            va_list args);
3416
3417       This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3418
3419       See "CALLS WITH OPTIONAL ARGUMENTS".
3420
3421   guestfs_btrfs_filesystem_resize_argv
3422        int
3423        guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3424                                              const char *mountpoint,
3425                                              const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3426
3427       This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3428
3429       See "CALLS WITH OPTIONAL ARGUMENTS".
3430
3431   guestfs_btrfs_filesystem_show
3432        char **
3433        guestfs_btrfs_filesystem_show (guestfs_h *g,
3434                                       const char *device);
3435
3436       Show all the devices where the filesystems in "device" is spanned over.
3437
3438       If not all the devices for the filesystems are present, then this
3439       function fails and the "errno" is set to "ENODEV".
3440
3441       This function returns a NULL-terminated array of strings (like
3442       environ(3)), or NULL if there was an error.  The caller must free the
3443       strings and the array after use.
3444
3445       This function depends on the feature "btrfs".  See also
3446       "guestfs_feature_available".
3447
3448       (Added in 1.33.29)
3449
3450   guestfs_btrfs_filesystem_sync
3451        int
3452        guestfs_btrfs_filesystem_sync (guestfs_h *g,
3453                                       const char *fs);
3454
3455       Force sync on the btrfs filesystem mounted at "fs".
3456
3457       This function returns 0 on success or -1 on error.
3458
3459       This function depends on the feature "btrfs".  See also
3460       "guestfs_feature_available".
3461
3462       (Added in 1.17.35)
3463
3464   guestfs_btrfs_fsck
3465        int
3466        guestfs_btrfs_fsck (guestfs_h *g,
3467                            const char *device,
3468                            ...);
3469
3470       You may supply a list of optional arguments to this call.  Use zero or
3471       more of the following pairs of parameters, and terminate the list with
3472       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3473
3474        GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3475        GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3476
3477       Used to check a btrfs filesystem, "device" is the device file where the
3478       filesystem is stored.
3479
3480       This function returns 0 on success or -1 on error.
3481
3482       This function depends on the feature "btrfs".  See also
3483       "guestfs_feature_available".
3484
3485       (Added in 1.17.43)
3486
3487   guestfs_btrfs_fsck_va
3488        int
3489        guestfs_btrfs_fsck_va (guestfs_h *g,
3490                               const char *device,
3491                               va_list args);
3492
3493       This is the "va_list variant" of "guestfs_btrfs_fsck".
3494
3495       See "CALLS WITH OPTIONAL ARGUMENTS".
3496
3497   guestfs_btrfs_fsck_argv
3498        int
3499        guestfs_btrfs_fsck_argv (guestfs_h *g,
3500                                 const char *device,
3501                                 const struct guestfs_btrfs_fsck_argv *optargs);
3502
3503       This is the "argv variant" of "guestfs_btrfs_fsck".
3504
3505       See "CALLS WITH OPTIONAL ARGUMENTS".
3506
3507   guestfs_btrfs_image
3508        int
3509        guestfs_btrfs_image (guestfs_h *g,
3510                             char *const *source,
3511                             const char *image,
3512                             ...);
3513
3514       You may supply a list of optional arguments to this call.  Use zero or
3515       more of the following pairs of parameters, and terminate the list with
3516       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3517
3518        GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3519
3520       This is used to create an image of a btrfs filesystem.  All data will
3521       be zeroed, but metadata and the like is preserved.
3522
3523       This function returns 0 on success or -1 on error.
3524
3525       This function depends on the feature "btrfs".  See also
3526       "guestfs_feature_available".
3527
3528       (Added in 1.29.32)
3529
3530   guestfs_btrfs_image_va
3531        int
3532        guestfs_btrfs_image_va (guestfs_h *g,
3533                                char *const *source,
3534                                const char *image,
3535                                va_list args);
3536
3537       This is the "va_list variant" of "guestfs_btrfs_image".
3538
3539       See "CALLS WITH OPTIONAL ARGUMENTS".
3540
3541   guestfs_btrfs_image_argv
3542        int
3543        guestfs_btrfs_image_argv (guestfs_h *g,
3544                                  char *const *source,
3545                                  const char *image,
3546                                  const struct guestfs_btrfs_image_argv *optargs);
3547
3548       This is the "argv variant" of "guestfs_btrfs_image".
3549
3550       See "CALLS WITH OPTIONAL ARGUMENTS".
3551
3552   guestfs_btrfs_qgroup_assign
3553        int
3554        guestfs_btrfs_qgroup_assign (guestfs_h *g,
3555                                     const char *src,
3556                                     const char *dst,
3557                                     const char *path);
3558
3559       Add qgroup "src" to parent qgroup "dst". This command can group several
3560       qgroups into a parent qgroup to share common limit.
3561
3562       This function returns 0 on success or -1 on error.
3563
3564       This function depends on the feature "btrfs".  See also
3565       "guestfs_feature_available".
3566
3567       (Added in 1.29.17)
3568
3569   guestfs_btrfs_qgroup_create
3570        int
3571        guestfs_btrfs_qgroup_create (guestfs_h *g,
3572                                     const char *qgroupid,
3573                                     const char *subvolume);
3574
3575       Create a quota group (qgroup) for subvolume at "subvolume".
3576
3577       This function returns 0 on success or -1 on error.
3578
3579       This function depends on the feature "btrfs".  See also
3580       "guestfs_feature_available".
3581
3582       (Added in 1.29.17)
3583
3584   guestfs_btrfs_qgroup_destroy
3585        int
3586        guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3587                                      const char *qgroupid,
3588                                      const char *subvolume);
3589
3590       Destroy a quota group.
3591
3592       This function returns 0 on success or -1 on error.
3593
3594       This function depends on the feature "btrfs".  See also
3595       "guestfs_feature_available".
3596
3597       (Added in 1.29.17)
3598
3599   guestfs_btrfs_qgroup_limit
3600        int
3601        guestfs_btrfs_qgroup_limit (guestfs_h *g,
3602                                    const char *subvolume,
3603                                    int64_t size);
3604
3605       Limit the size of the subvolume with path "subvolume".
3606
3607       This function returns 0 on success or -1 on error.
3608
3609       This function depends on the feature "btrfs".  See also
3610       "guestfs_feature_available".
3611
3612       (Added in 1.29.17)
3613
3614   guestfs_btrfs_qgroup_remove
3615        int
3616        guestfs_btrfs_qgroup_remove (guestfs_h *g,
3617                                     const char *src,
3618                                     const char *dst,
3619                                     const char *path);
3620
3621       Remove qgroup "src" from the parent qgroup "dst".
3622
3623       This function returns 0 on success or -1 on error.
3624
3625       This function depends on the feature "btrfs".  See also
3626       "guestfs_feature_available".
3627
3628       (Added in 1.29.17)
3629
3630   guestfs_btrfs_qgroup_show
3631        struct guestfs_btrfsqgroup_list *
3632        guestfs_btrfs_qgroup_show (guestfs_h *g,
3633                                   const char *path);
3634
3635       Show all subvolume quota groups in a btrfs filesystem, including their
3636       usages.
3637
3638       This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3639       there was an error.  The caller must call
3640       "guestfs_free_btrfsqgroup_list" after use.
3641
3642       This function depends on the feature "btrfs".  See also
3643       "guestfs_feature_available".
3644
3645       (Added in 1.29.17)
3646
3647   guestfs_btrfs_quota_enable
3648        int
3649        guestfs_btrfs_quota_enable (guestfs_h *g,
3650                                    const char *fs,
3651                                    int enable);
3652
3653       Enable or disable subvolume quota support for filesystem which contains
3654       "path".
3655
3656       This function returns 0 on success or -1 on error.
3657
3658       This function depends on the feature "btrfs".  See also
3659       "guestfs_feature_available".
3660
3661       (Added in 1.29.17)
3662
3663   guestfs_btrfs_quota_rescan
3664        int
3665        guestfs_btrfs_quota_rescan (guestfs_h *g,
3666                                    const char *fs);
3667
3668       Trash all qgroup numbers and scan the metadata again with the current
3669       config.
3670
3671       This function returns 0 on success or -1 on error.
3672
3673       This function depends on the feature "btrfs".  See also
3674       "guestfs_feature_available".
3675
3676       (Added in 1.29.17)
3677
3678   guestfs_btrfs_replace
3679        int
3680        guestfs_btrfs_replace (guestfs_h *g,
3681                               const char *srcdev,
3682                               const char *targetdev,
3683                               const char *mntpoint);
3684
3685       Replace device of a btrfs filesystem. On a live filesystem, duplicate
3686       the data to the target device which is currently stored on the source
3687       device.  After completion of the operation, the source device is wiped
3688       out and removed from the filesystem.
3689
3690       The "targetdev" needs to be same size or larger than the "srcdev".
3691       Devices which are currently mounted are never allowed to be used as the
3692       "targetdev".
3693
3694       This function returns 0 on success or -1 on error.
3695
3696       This function depends on the feature "btrfs".  See also
3697       "guestfs_feature_available".
3698
3699       (Added in 1.29.48)
3700
3701   guestfs_btrfs_rescue_chunk_recover
3702        int
3703        guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3704                                            const char *device);
3705
3706       Recover the chunk tree of btrfs filesystem by scanning the devices one
3707       by one.
3708
3709       This function returns 0 on success or -1 on error.
3710
3711       This function depends on the feature "btrfs".  See also
3712       "guestfs_feature_available".
3713
3714       (Added in 1.29.22)
3715
3716   guestfs_btrfs_rescue_super_recover
3717        int
3718        guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3719                                            const char *device);
3720
3721       Recover bad superblocks from good copies.
3722
3723       This function returns 0 on success or -1 on error.
3724
3725       This function depends on the feature "btrfs".  See also
3726       "guestfs_feature_available".
3727
3728       (Added in 1.29.22)
3729
3730   guestfs_btrfs_scrub_cancel
3731        int
3732        guestfs_btrfs_scrub_cancel (guestfs_h *g,
3733                                    const char *path);
3734
3735       Cancel a running scrub on a btrfs filesystem.
3736
3737       This function returns 0 on success or -1 on error.
3738
3739       This function depends on the feature "btrfs".  See also
3740       "guestfs_feature_available".
3741
3742       (Added in 1.29.22)
3743
3744   guestfs_btrfs_scrub_resume
3745        int
3746        guestfs_btrfs_scrub_resume (guestfs_h *g,
3747                                    const char *path);
3748
3749       Resume a previously canceled or interrupted scrub on a btrfs
3750       filesystem.
3751
3752       This function returns 0 on success or -1 on error.
3753
3754       This function depends on the feature "btrfs".  See also
3755       "guestfs_feature_available".
3756
3757       (Added in 1.29.22)
3758
3759   guestfs_btrfs_scrub_start
3760        int
3761        guestfs_btrfs_scrub_start (guestfs_h *g,
3762                                   const char *path);
3763
3764       Reads all the data and metadata on the filesystem, and uses checksums
3765       and the duplicate copies from RAID storage to identify and repair any
3766       corrupt data.
3767
3768       This function returns 0 on success or -1 on error.
3769
3770       This function depends on the feature "btrfs".  See also
3771       "guestfs_feature_available".
3772
3773       (Added in 1.29.22)
3774
3775   guestfs_btrfs_scrub_status
3776        struct guestfs_btrfsscrub *
3777        guestfs_btrfs_scrub_status (guestfs_h *g,
3778                                    const char *path);
3779
3780       Show status of running or finished scrub on a btrfs filesystem.
3781
3782       This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3783       was an error.  The caller must call "guestfs_free_btrfsscrub" after
3784       use.
3785
3786       This function depends on the feature "btrfs".  See also
3787       "guestfs_feature_available".
3788
3789       (Added in 1.29.26)
3790
3791   guestfs_btrfs_set_seeding
3792        int
3793        guestfs_btrfs_set_seeding (guestfs_h *g,
3794                                   const char *device,
3795                                   int seeding);
3796
3797       Enable or disable the seeding feature of a device that contains a btrfs
3798       filesystem.
3799
3800       This function returns 0 on success or -1 on error.
3801
3802       This function depends on the feature "btrfs".  See also
3803       "guestfs_feature_available".
3804
3805       (Added in 1.17.43)
3806
3807   guestfs_btrfs_subvolume_create
3808        int
3809        guestfs_btrfs_subvolume_create (guestfs_h *g,
3810                                        const char *dest);
3811
3812       This function is provided for backwards compatibility with earlier
3813       versions of libguestfs.  It simply calls
3814       "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3815
3816       (Added in 1.17.35)
3817
3818   guestfs_btrfs_subvolume_create_opts
3819        int
3820        guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3821                                             const char *dest,
3822                                             ...);
3823
3824       You may supply a list of optional arguments to this call.  Use zero or
3825       more of the following pairs of parameters, and terminate the list with
3826       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3827
3828        GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3829
3830       Create a btrfs subvolume.  The "dest" argument is the destination
3831       directory and the name of the subvolume, in the form
3832       /path/to/dest/name.  The optional parameter "qgroupid" represents the
3833       qgroup which the newly created subvolume will be added to.
3834
3835       This function returns 0 on success or -1 on error.
3836
3837       This function depends on the feature "btrfs".  See also
3838       "guestfs_feature_available".
3839
3840       (Added in 1.17.35)
3841
3842   guestfs_btrfs_subvolume_create_opts_va
3843        int
3844        guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3845                                                const char *dest,
3846                                                va_list args);
3847
3848       This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3849
3850       See "CALLS WITH OPTIONAL ARGUMENTS".
3851
3852   guestfs_btrfs_subvolume_create_opts_argv
3853        int
3854        guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3855                                                  const char *dest,
3856                                                  const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3857
3858       This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3859
3860       See "CALLS WITH OPTIONAL ARGUMENTS".
3861
3862   guestfs_btrfs_subvolume_delete
3863        int
3864        guestfs_btrfs_subvolume_delete (guestfs_h *g,
3865                                        const char *subvolume);
3866
3867       Delete the named btrfs subvolume or snapshot.
3868
3869       This function returns 0 on success or -1 on error.
3870
3871       This function depends on the feature "btrfs".  See also
3872       "guestfs_feature_available".
3873
3874       (Added in 1.17.35)
3875
3876   guestfs_btrfs_subvolume_get_default
3877        int64_t
3878        guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3879                                             const char *fs);
3880
3881       Get the default subvolume or snapshot of a filesystem mounted at
3882       "mountpoint".
3883
3884       On error this function returns -1.
3885
3886       This function depends on the feature "btrfs".  See also
3887       "guestfs_feature_available".
3888
3889       (Added in 1.29.17)
3890
3891   guestfs_btrfs_subvolume_list
3892        struct guestfs_btrfssubvolume_list *
3893        guestfs_btrfs_subvolume_list (guestfs_h *g,
3894                                      const char *fs);
3895
3896       List the btrfs snapshots and subvolumes of the btrfs filesystem which
3897       is mounted at "fs".
3898
3899       This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3900       if there was an error.  The caller must call
3901       "guestfs_free_btrfssubvolume_list" after use.
3902
3903       This function depends on the feature "btrfs".  See also
3904       "guestfs_feature_available".
3905
3906       (Added in 1.17.35)
3907
3908   guestfs_btrfs_subvolume_set_default
3909        int
3910        guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3911                                             int64_t id,
3912                                             const char *fs);
3913
3914       Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3915       default.  See "guestfs_btrfs_subvolume_list" to get a list of
3916       subvolumes.
3917
3918       This function returns 0 on success or -1 on error.
3919
3920       This function depends on the feature "btrfs".  See also
3921       "guestfs_feature_available".
3922
3923       (Added in 1.17.35)
3924
3925   guestfs_btrfs_subvolume_show
3926        char **
3927        guestfs_btrfs_subvolume_show (guestfs_h *g,
3928                                      const char *subvolume);
3929
3930       Return detailed information of the subvolume.
3931
3932       This function returns a NULL-terminated array of strings, or NULL if
3933       there was an error.  The array of strings will always have length
3934       "2n+1", where "n" keys and values alternate, followed by the trailing
3935       NULL entry.  The caller must free the strings and the array after use.
3936
3937       This function depends on the feature "btrfs".  See also
3938       "guestfs_feature_available".
3939
3940       (Added in 1.29.17)
3941
3942   guestfs_btrfs_subvolume_snapshot
3943        int
3944        guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3945                                          const char *source,
3946                                          const char *dest);
3947
3948       This function is provided for backwards compatibility with earlier
3949       versions of libguestfs.  It simply calls
3950       "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3951
3952       (Added in 1.17.35)
3953
3954   guestfs_btrfs_subvolume_snapshot_opts
3955        int
3956        guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3957                                               const char *source,
3958                                               const char *dest,
3959                                               ...);
3960
3961       You may supply a list of optional arguments to this call.  Use zero or
3962       more of the following pairs of parameters, and terminate the list with
3963       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3964
3965        GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3966        GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3967
3968       Create a snapshot of the btrfs subvolume "source".  The "dest" argument
3969       is the destination directory and the name of the snapshot, in the form
3970       /path/to/dest/name. By default the newly created snapshot is writable,
3971       if the value of optional parameter "ro" is true, then a readonly
3972       snapshot is created. The optional parameter "qgroupid" represents the
3973       qgroup which the newly created snapshot will be added to.
3974
3975       This function returns 0 on success or -1 on error.
3976
3977       This function depends on the feature "btrfs".  See also
3978       "guestfs_feature_available".
3979
3980       (Added in 1.17.35)
3981
3982   guestfs_btrfs_subvolume_snapshot_opts_va
3983        int
3984        guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
3985                                                  const char *source,
3986                                                  const char *dest,
3987                                                  va_list args);
3988
3989       This is the "va_list variant" of
3990       "guestfs_btrfs_subvolume_snapshot_opts".
3991
3992       See "CALLS WITH OPTIONAL ARGUMENTS".
3993
3994   guestfs_btrfs_subvolume_snapshot_opts_argv
3995        int
3996        guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
3997                                                    const char *source,
3998                                                    const char *dest,
3999                                                    const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
4000
4001       This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
4002
4003       See "CALLS WITH OPTIONAL ARGUMENTS".
4004
4005   guestfs_btrfstune_enable_extended_inode_refs
4006        int
4007        guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
4008                                                      const char *device);
4009
4010       This will Enable extended inode refs.
4011
4012       This function returns 0 on success or -1 on error.
4013
4014       This function depends on the feature "btrfs".  See also
4015       "guestfs_feature_available".
4016
4017       (Added in 1.29.29)
4018
4019   guestfs_btrfstune_enable_skinny_metadata_extent_refs
4020        int
4021        guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
4022                                                              const char *device);
4023
4024       This enable skinny metadata extent refs.
4025
4026       This function returns 0 on success or -1 on error.
4027
4028       This function depends on the feature "btrfs".  See also
4029       "guestfs_feature_available".
4030
4031       (Added in 1.29.29)
4032
4033   guestfs_btrfstune_seeding
4034        int
4035        guestfs_btrfstune_seeding (guestfs_h *g,
4036                                   const char *device,
4037                                   int seeding);
4038
4039       Enable seeding of a btrfs device, this will force a fs readonly so that
4040       you can use it to build other filesystems.
4041
4042       This function returns 0 on success or -1 on error.
4043
4044       This function depends on the feature "btrfs".  See also
4045       "guestfs_feature_available".
4046
4047       (Added in 1.29.29)
4048
4049   guestfs_c_pointer
4050        int64_t
4051        guestfs_c_pointer (guestfs_h *g);
4052
4053       In non-C language bindings, this allows you to retrieve the underlying
4054       C pointer to the handle (ie. "guestfs_h *").  The purpose of this is to
4055       allow other libraries to interwork with libguestfs.
4056
4057       On error this function returns -1.
4058
4059       (Added in 1.29.17)
4060
4061   guestfs_canonical_device_name
4062        char *
4063        guestfs_canonical_device_name (guestfs_h *g,
4064                                       const char *device);
4065
4066       This utility function is useful when displaying device names to the
4067       user.  It takes a number of irregular device names and returns them in
4068       a consistent format:
4069
4070       /dev/hdX
4071       /dev/vdX
4072           These are returned as /dev/sdX.  Note this works for device names
4073           and partition names.  This is approximately the reverse of the
4074           algorithm described in "BLOCK DEVICE NAMING".
4075
4076       /dev/mapper/VG-LV
4077       /dev/dm-N
4078           Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
4079
4080       Other strings are returned unmodified.
4081
4082       This function returns a string, or NULL on error.  The caller must free
4083       the returned string after use.
4084
4085       (Added in 1.19.7)
4086
4087   guestfs_cap_get_file
4088        char *
4089        guestfs_cap_get_file (guestfs_h *g,
4090                              const char *path);
4091
4092       This function returns the Linux capabilities attached to "path".  The
4093       capabilities set is returned in text form (see cap_to_text(3)).
4094
4095       If no capabilities are attached to a file, an empty string is returned.
4096
4097       This function returns a string, or NULL on error.  The caller must free
4098       the returned string after use.
4099
4100       This function depends on the feature "linuxcaps".  See also
4101       "guestfs_feature_available".
4102
4103       (Added in 1.19.63)
4104
4105   guestfs_cap_set_file
4106        int
4107        guestfs_cap_set_file (guestfs_h *g,
4108                              const char *path,
4109                              const char *cap);
4110
4111       This function sets the Linux capabilities attached to "path".  The
4112       capabilities set "cap" should be passed in text form (see
4113       cap_from_text(3)).
4114
4115       This function returns 0 on success or -1 on error.
4116
4117       This function depends on the feature "linuxcaps".  See also
4118       "guestfs_feature_available".
4119
4120       (Added in 1.19.63)
4121
4122   guestfs_case_sensitive_path
4123        char *
4124        guestfs_case_sensitive_path (guestfs_h *g,
4125                                     const char *path);
4126
4127       This can be used to resolve case insensitive paths on a filesystem
4128       which is case sensitive.  The use case is to resolve paths which you
4129       have read from Windows configuration files or the Windows Registry, to
4130       the true path.
4131
4132       The command handles a peculiarity of the Linux ntfs-3g filesystem
4133       driver (and probably others), which is that although the underlying
4134       filesystem is case-insensitive, the driver exports the filesystem to
4135       Linux as case-sensitive.
4136
4137       One consequence of this is that special directories such as C:\windows
4138       may appear as /WINDOWS or /windows (or other things) depending on the
4139       precise details of how they were created.  In Windows itself this would
4140       not be a problem.
4141
4142       Bug or feature?  You decide:
4143       http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4144
4145       "guestfs_case_sensitive_path" attempts to resolve the true case of each
4146       element in the path. It will return a resolved path if either the full
4147       path or its parent directory exists. If the parent directory exists but
4148       the full path does not, the case of the parent directory will be
4149       correctly resolved, and the remainder appended unmodified. For example,
4150       if the file "/Windows/System32/netkvm.sys" exists:
4151
4152       "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4153           "Windows/System32/netkvm.sys"
4154
4155       "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4156           "Windows/System32/NoSuchFile"
4157
4158       "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4159           ERROR
4160
4161       Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4162       cannot be used to check for the existence of a file.
4163
4164       Note: This function does not handle drive names, backslashes etc.
4165
4166       See also "guestfs_realpath".
4167
4168       This function returns a string, or NULL on error.  The caller must free
4169       the returned string after use.
4170
4171       (Added in 1.0.75)
4172
4173   guestfs_cat
4174        char *
4175        guestfs_cat (guestfs_h *g,
4176                     const char *path);
4177
4178       Return the contents of the file named "path".
4179
4180       Because, in C, this function returns a "char *", there is no way to
4181       differentiate between a "\0" character in a file and end of string.  To
4182       handle binary files, use the "guestfs_read_file" or "guestfs_download"
4183       functions.
4184
4185       This function returns a string, or NULL on error.  The caller must free
4186       the returned string after use.
4187
4188       (Added in 0.4)
4189
4190   guestfs_checksum
4191        char *
4192        guestfs_checksum (guestfs_h *g,
4193                          const char *csumtype,
4194                          const char *path);
4195
4196       This call computes the MD5, SHAx or CRC checksum of the file named
4197       "path".
4198
4199       The type of checksum to compute is given by the "csumtype" parameter
4200       which must have one of the following values:
4201
4202       "crc"
4203           Compute the cyclic redundancy check (CRC) specified by POSIX for
4204           the "cksum" command.
4205
4206       "md5"
4207           Compute the MD5 hash (using the "md5sum" program).
4208
4209       "sha1"
4210           Compute the SHA1 hash (using the "sha1sum" program).
4211
4212       "sha224"
4213           Compute the SHA224 hash (using the "sha224sum" program).
4214
4215       "sha256"
4216           Compute the SHA256 hash (using the "sha256sum" program).
4217
4218       "sha384"
4219           Compute the SHA384 hash (using the "sha384sum" program).
4220
4221       "sha512"
4222           Compute the SHA512 hash (using the "sha512sum" program).
4223
4224       The checksum is returned as a printable string.
4225
4226       To get the checksum for a device, use "guestfs_checksum_device".
4227
4228       To get the checksums for many files, use "guestfs_checksums_out".
4229
4230       This function returns a string, or NULL on error.  The caller must free
4231       the returned string after use.
4232
4233       (Added in 1.0.2)
4234
4235   guestfs_checksum_device
4236        char *
4237        guestfs_checksum_device (guestfs_h *g,
4238                                 const char *csumtype,
4239                                 const char *device);
4240
4241       This call computes the MD5, SHAx or CRC checksum of the contents of the
4242       device named "device".  For the types of checksums supported see the
4243       "guestfs_checksum" command.
4244
4245       This function returns a string, or NULL on error.  The caller must free
4246       the returned string after use.
4247
4248       (Added in 1.3.2)
4249
4250   guestfs_checksums_out
4251        int
4252        guestfs_checksums_out (guestfs_h *g,
4253                               const char *csumtype,
4254                               const char *directory,
4255                               const char *sumsfile);
4256
4257       This command computes the checksums of all regular files in directory
4258       and then emits a list of those checksums to the local output file
4259       "sumsfile".
4260
4261       This can be used for verifying the integrity of a virtual machine.
4262       However to be properly secure you should pay attention to the output of
4263       the checksum command (it uses the ones from GNU coreutils).  In
4264       particular when the filename is not printable, coreutils uses a special
4265       backslash syntax.  For more information, see the GNU coreutils info
4266       file.
4267
4268       This function returns 0 on success or -1 on error.
4269
4270       (Added in 1.3.7)
4271
4272   guestfs_chmod
4273        int
4274        guestfs_chmod (guestfs_h *g,
4275                       int mode,
4276                       const char *path);
4277
4278       Change the mode (permissions) of "path" to "mode".  Only numeric modes
4279       are supported.
4280
4281       Note: When using this command from guestfish, "mode" by default would
4282       be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4283       700.
4284
4285       The mode actually set is affected by the umask.
4286
4287       This function returns 0 on success or -1 on error.
4288
4289       (Added in 0.8)
4290
4291   guestfs_chown
4292        int
4293        guestfs_chown (guestfs_h *g,
4294                       int owner,
4295                       int group,
4296                       const char *path);
4297
4298       Change the file owner to "owner" and group to "group".
4299
4300       Only numeric uid and gid are supported.  If you want to use names, you
4301       will need to locate and parse the password file yourself (Augeas
4302       support makes this relatively easy).
4303
4304       This function returns 0 on success or -1 on error.
4305
4306       (Added in 0.8)
4307
4308   guestfs_clear_backend_setting
4309        int
4310        guestfs_clear_backend_setting (guestfs_h *g,
4311                                       const char *name);
4312
4313       If there is a backend setting string matching "name" or beginning with
4314       "name=", then that string is removed from the backend settings.
4315
4316       This call returns the number of strings which were removed (which may
4317       be 0, 1 or greater than 1).
4318
4319       See "BACKEND", "BACKEND SETTINGS".
4320
4321       On error this function returns -1.
4322
4323       (Added in 1.27.2)
4324
4325   guestfs_command
4326        char *
4327        guestfs_command (guestfs_h *g,
4328                         char *const *arguments);
4329
4330       This call runs a command from the guest filesystem.  The filesystem
4331       must be mounted, and must contain a compatible operating system (ie.
4332       something Linux, with the same or compatible processor architecture).
4333
4334       The single parameter is an argv-style list of arguments.  The first
4335       element is the name of the program to run.  Subsequent elements are
4336       parameters.  The list must be non-empty (ie. must contain a program
4337       name).  Note that the command runs directly, and is not invoked via the
4338       shell (see "guestfs_sh").
4339
4340       The return value is anything printed to stdout by the command.
4341
4342       If the command returns a non-zero exit status, then this function
4343       returns an error message.  The error message string is the content of
4344       stderr from the command.
4345
4346       The $PATH environment variable will contain at least /usr/bin and /bin.
4347       If you require a program from another location, you should provide the
4348       full path in the first parameter.
4349
4350       Shared libraries and data files required by the program must be
4351       available on filesystems which are mounted in the correct places.  It
4352       is the caller’s responsibility to ensure all filesystems that are
4353       needed are mounted at the right locations.
4354
4355       This function returns a string, or NULL on error.  The caller must free
4356       the returned string after use.
4357
4358       Because of the message protocol, there is a transfer limit of somewhere
4359       between 2MB and 4MB.  See "PROTOCOL LIMITS".
4360
4361       (Added in 1.9.1)
4362
4363   guestfs_command_lines
4364        char **
4365        guestfs_command_lines (guestfs_h *g,
4366                               char *const *arguments);
4367
4368       This is the same as "guestfs_command", but splits the result into a
4369       list of lines.
4370
4371       See also: "guestfs_sh_lines"
4372
4373       This function returns a NULL-terminated array of strings (like
4374       environ(3)), or NULL if there was an error.  The caller must free the
4375       strings and the array after use.
4376
4377       Because of the message protocol, there is a transfer limit of somewhere
4378       between 2MB and 4MB.  See "PROTOCOL LIMITS".
4379
4380       (Added in 1.9.1)
4381
4382   guestfs_compress_device_out
4383        int
4384        guestfs_compress_device_out (guestfs_h *g,
4385                                     const char *ctype,
4386                                     const char *device,
4387                                     const char *zdevice,
4388                                     ...);
4389
4390       You may supply a list of optional arguments to this call.  Use zero or
4391       more of the following pairs of parameters, and terminate the list with
4392       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4393
4394        GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4395
4396       This command compresses "device" and writes it out to the local file
4397       "zdevice".
4398
4399       The "ctype" and optional "level" parameters have the same meaning as in
4400       "guestfs_compress_out".
4401
4402       This function returns 0 on success or -1 on error.
4403
4404       (Added in 1.13.15)
4405
4406   guestfs_compress_device_out_va
4407        int
4408        guestfs_compress_device_out_va (guestfs_h *g,
4409                                        const char *ctype,
4410                                        const char *device,
4411                                        const char *zdevice,
4412                                        va_list args);
4413
4414       This is the "va_list variant" of "guestfs_compress_device_out".
4415
4416       See "CALLS WITH OPTIONAL ARGUMENTS".
4417
4418   guestfs_compress_device_out_argv
4419        int
4420        guestfs_compress_device_out_argv (guestfs_h *g,
4421                                          const char *ctype,
4422                                          const char *device,
4423                                          const char *zdevice,
4424                                          const struct guestfs_compress_device_out_argv *optargs);
4425
4426       This is the "argv variant" of "guestfs_compress_device_out".
4427
4428       See "CALLS WITH OPTIONAL ARGUMENTS".
4429
4430   guestfs_compress_out
4431        int
4432        guestfs_compress_out (guestfs_h *g,
4433                              const char *ctype,
4434                              const char *file,
4435                              const char *zfile,
4436                              ...);
4437
4438       You may supply a list of optional arguments to this call.  Use zero or
4439       more of the following pairs of parameters, and terminate the list with
4440       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4441
4442        GUESTFS_COMPRESS_OUT_LEVEL, int level,
4443
4444       This command compresses file and writes it out to the local file zfile.
4445
4446       The compression program used is controlled by the "ctype" parameter.
4447       Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4448       Some compression types may not be supported by particular builds of
4449       libguestfs, in which case you will get an error containing the
4450       substring "not supported".
4451
4452       The optional "level" parameter controls compression level.  The meaning
4453       and default for this parameter depends on the compression program being
4454       used.
4455
4456       This function returns 0 on success or -1 on error.
4457
4458       (Added in 1.13.15)
4459
4460   guestfs_compress_out_va
4461        int
4462        guestfs_compress_out_va (guestfs_h *g,
4463                                 const char *ctype,
4464                                 const char *file,
4465                                 const char *zfile,
4466                                 va_list args);
4467
4468       This is the "va_list variant" of "guestfs_compress_out".
4469
4470       See "CALLS WITH OPTIONAL ARGUMENTS".
4471
4472   guestfs_compress_out_argv
4473        int
4474        guestfs_compress_out_argv (guestfs_h *g,
4475                                   const char *ctype,
4476                                   const char *file,
4477                                   const char *zfile,
4478                                   const struct guestfs_compress_out_argv *optargs);
4479
4480       This is the "argv variant" of "guestfs_compress_out".
4481
4482       See "CALLS WITH OPTIONAL ARGUMENTS".
4483
4484   guestfs_config
4485        int
4486        guestfs_config (guestfs_h *g,
4487                        const char *hvparam,
4488                        const char *hvvalue);
4489
4490       This can be used to add arbitrary hypervisor parameters of the form
4491       -param value.  Actually it’s not quite arbitrary - we prevent you from
4492       setting some parameters which would interfere with parameters that we
4493       use.
4494
4495       The first character of "hvparam" string must be a "-" (dash).
4496
4497       "hvvalue" can be NULL.
4498
4499       This function returns 0 on success or -1 on error.
4500
4501       (Added in 0.3)
4502
4503   guestfs_copy_attributes
4504        int
4505        guestfs_copy_attributes (guestfs_h *g,
4506                                 const char *src,
4507                                 const char *dest,
4508                                 ...);
4509
4510       You may supply a list of optional arguments to this call.  Use zero or
4511       more of the following pairs of parameters, and terminate the list with
4512       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4513
4514        GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4515        GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4516        GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4517        GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4518
4519       Copy the attributes of a path (which can be a file or a directory) to
4520       another path.
4521
4522       By default "no" attribute is copied, so make sure to specify any (or
4523       "all" to copy everything).
4524
4525       The optional arguments specify which attributes can be copied:
4526
4527       "mode"
4528           Copy part of the file mode from "source" to "destination". Only the
4529           UNIX permissions and the sticky/setuid/setgid bits can be copied.
4530
4531       "xattributes"
4532           Copy the Linux extended attributes (xattrs) from "source" to
4533           "destination".  This flag does nothing if the linuxxattrs feature
4534           is not available (see "guestfs_feature_available").
4535
4536       "ownership"
4537           Copy the owner uid and the group gid of "source" to "destination".
4538
4539       "all"
4540           Copy all the attributes from "source" to "destination". Enabling it
4541           enables all the other flags, if they are not specified already.
4542
4543       This function returns 0 on success or -1 on error.
4544
4545       (Added in 1.25.21)
4546
4547   guestfs_copy_attributes_va
4548        int
4549        guestfs_copy_attributes_va (guestfs_h *g,
4550                                    const char *src,
4551                                    const char *dest,
4552                                    va_list args);
4553
4554       This is the "va_list variant" of "guestfs_copy_attributes".
4555
4556       See "CALLS WITH OPTIONAL ARGUMENTS".
4557
4558   guestfs_copy_attributes_argv
4559        int
4560        guestfs_copy_attributes_argv (guestfs_h *g,
4561                                      const char *src,
4562                                      const char *dest,
4563                                      const struct guestfs_copy_attributes_argv *optargs);
4564
4565       This is the "argv variant" of "guestfs_copy_attributes".
4566
4567       See "CALLS WITH OPTIONAL ARGUMENTS".
4568
4569   guestfs_copy_device_to_device
4570        int
4571        guestfs_copy_device_to_device (guestfs_h *g,
4572                                       const char *src,
4573                                       const char *dest,
4574                                       ...);
4575
4576       You may supply a list of optional arguments to this call.  Use zero or
4577       more of the following pairs of parameters, and terminate the list with
4578       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4579
4580        GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4581        GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4582        GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4583        GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4584        GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4585
4586       The four calls "guestfs_copy_device_to_device",
4587       "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4588       "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4589       a destination (device|file).
4590
4591       Partial copies can be made since you can specify optionally the source
4592       offset, destination offset and size to copy.  These values are all
4593       specified in bytes.  If not given, the offsets both default to zero,
4594       and the size defaults to copying as much as possible until we hit the
4595       end of the source.
4596
4597       The source and destination may be the same object.  However overlapping
4598       regions may not be copied correctly.
4599
4600       If the destination is a file, it is created if required.  If the
4601       destination file is not large enough, it is extended.
4602
4603       If the destination is a file and the "append" flag is not set, then the
4604       destination file is truncated.  If the "append" flag is set, then the
4605       copy appends to the destination file.  The "append" flag currently
4606       cannot be set for devices.
4607
4608       If the "sparse" flag is true then the call avoids writing blocks that
4609       contain only zeroes, which can help in some situations where the
4610       backing disk is thin-provisioned.  Note that unless the target is
4611       already zeroed, using this option will result in incorrect copying.
4612
4613       This function returns 0 on success or -1 on error.
4614
4615       This long-running command can generate progress notification messages
4616       so that the caller can display a progress bar or indicator.  To receive
4617       these messages, the caller must register a progress event callback.
4618       See "GUESTFS_EVENT_PROGRESS".
4619
4620       (Added in 1.13.25)
4621
4622   guestfs_copy_device_to_device_va
4623        int
4624        guestfs_copy_device_to_device_va (guestfs_h *g,
4625                                          const char *src,
4626                                          const char *dest,
4627                                          va_list args);
4628
4629       This is the "va_list variant" of "guestfs_copy_device_to_device".
4630
4631       See "CALLS WITH OPTIONAL ARGUMENTS".
4632
4633   guestfs_copy_device_to_device_argv
4634        int
4635        guestfs_copy_device_to_device_argv (guestfs_h *g,
4636                                            const char *src,
4637                                            const char *dest,
4638                                            const struct guestfs_copy_device_to_device_argv *optargs);
4639
4640       This is the "argv variant" of "guestfs_copy_device_to_device".
4641
4642       See "CALLS WITH OPTIONAL ARGUMENTS".
4643
4644   guestfs_copy_device_to_file
4645        int
4646        guestfs_copy_device_to_file (guestfs_h *g,
4647                                     const char *src,
4648                                     const char *dest,
4649                                     ...);
4650
4651       You may supply a list of optional arguments to this call.  Use zero or
4652       more of the following pairs of parameters, and terminate the list with
4653       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4654
4655        GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4656        GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4657        GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4658        GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4659        GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4660
4661       See "guestfs_copy_device_to_device" for a general overview of this
4662       call.
4663
4664       This function returns 0 on success or -1 on error.
4665
4666       This long-running command can generate progress notification messages
4667       so that the caller can display a progress bar or indicator.  To receive
4668       these messages, the caller must register a progress event callback.
4669       See "GUESTFS_EVENT_PROGRESS".
4670
4671       (Added in 1.13.25)
4672
4673   guestfs_copy_device_to_file_va
4674        int
4675        guestfs_copy_device_to_file_va (guestfs_h *g,
4676                                        const char *src,
4677                                        const char *dest,
4678                                        va_list args);
4679
4680       This is the "va_list variant" of "guestfs_copy_device_to_file".
4681
4682       See "CALLS WITH OPTIONAL ARGUMENTS".
4683
4684   guestfs_copy_device_to_file_argv
4685        int
4686        guestfs_copy_device_to_file_argv (guestfs_h *g,
4687                                          const char *src,
4688                                          const char *dest,
4689                                          const struct guestfs_copy_device_to_file_argv *optargs);
4690
4691       This is the "argv variant" of "guestfs_copy_device_to_file".
4692
4693       See "CALLS WITH OPTIONAL ARGUMENTS".
4694
4695   guestfs_copy_file_to_device
4696        int
4697        guestfs_copy_file_to_device (guestfs_h *g,
4698                                     const char *src,
4699                                     const char *dest,
4700                                     ...);
4701
4702       You may supply a list of optional arguments to this call.  Use zero or
4703       more of the following pairs of parameters, and terminate the list with
4704       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4705
4706        GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4707        GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4708        GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4709        GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4710        GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4711
4712       See "guestfs_copy_device_to_device" for a general overview of this
4713       call.
4714
4715       This function returns 0 on success or -1 on error.
4716
4717       This long-running command can generate progress notification messages
4718       so that the caller can display a progress bar or indicator.  To receive
4719       these messages, the caller must register a progress event callback.
4720       See "GUESTFS_EVENT_PROGRESS".
4721
4722       (Added in 1.13.25)
4723
4724   guestfs_copy_file_to_device_va
4725        int
4726        guestfs_copy_file_to_device_va (guestfs_h *g,
4727                                        const char *src,
4728                                        const char *dest,
4729                                        va_list args);
4730
4731       This is the "va_list variant" of "guestfs_copy_file_to_device".
4732
4733       See "CALLS WITH OPTIONAL ARGUMENTS".
4734
4735   guestfs_copy_file_to_device_argv
4736        int
4737        guestfs_copy_file_to_device_argv (guestfs_h *g,
4738                                          const char *src,
4739                                          const char *dest,
4740                                          const struct guestfs_copy_file_to_device_argv *optargs);
4741
4742       This is the "argv variant" of "guestfs_copy_file_to_device".
4743
4744       See "CALLS WITH OPTIONAL ARGUMENTS".
4745
4746   guestfs_copy_file_to_file
4747        int
4748        guestfs_copy_file_to_file (guestfs_h *g,
4749                                   const char *src,
4750                                   const char *dest,
4751                                   ...);
4752
4753       You may supply a list of optional arguments to this call.  Use zero or
4754       more of the following pairs of parameters, and terminate the list with
4755       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4756
4757        GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4758        GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4759        GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4760        GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4761        GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4762
4763       See "guestfs_copy_device_to_device" for a general overview of this
4764       call.
4765
4766       This is not the function you want for copying files.  This is for
4767       copying blocks within existing files.  See "guestfs_cp", "guestfs_cp_a"
4768       and "guestfs_mv" for general file copying and moving functions.
4769
4770       This function returns 0 on success or -1 on error.
4771
4772       This long-running command can generate progress notification messages
4773       so that the caller can display a progress bar or indicator.  To receive
4774       these messages, the caller must register a progress event callback.
4775       See "GUESTFS_EVENT_PROGRESS".
4776
4777       (Added in 1.13.25)
4778
4779   guestfs_copy_file_to_file_va
4780        int
4781        guestfs_copy_file_to_file_va (guestfs_h *g,
4782                                      const char *src,
4783                                      const char *dest,
4784                                      va_list args);
4785
4786       This is the "va_list variant" of "guestfs_copy_file_to_file".
4787
4788       See "CALLS WITH OPTIONAL ARGUMENTS".
4789
4790   guestfs_copy_file_to_file_argv
4791        int
4792        guestfs_copy_file_to_file_argv (guestfs_h *g,
4793                                        const char *src,
4794                                        const char *dest,
4795                                        const struct guestfs_copy_file_to_file_argv *optargs);
4796
4797       This is the "argv variant" of "guestfs_copy_file_to_file".
4798
4799       See "CALLS WITH OPTIONAL ARGUMENTS".
4800
4801   guestfs_copy_in
4802        int
4803        guestfs_copy_in (guestfs_h *g,
4804                         const char *localpath,
4805                         const char *remotedir);
4806
4807       "guestfs_copy_in" copies local files or directories recursively into
4808       the disk image, placing them in the directory called "remotedir" (which
4809       must exist).
4810
4811       Wildcards cannot be used.
4812
4813       This function returns 0 on success or -1 on error.
4814
4815       (Added in 1.29.24)
4816
4817   guestfs_copy_out
4818        int
4819        guestfs_copy_out (guestfs_h *g,
4820                          const char *remotepath,
4821                          const char *localdir);
4822
4823       "guestfs_copy_out" copies remote files or directories recursively out
4824       of the disk image, placing them on the host disk in a local directory
4825       called "localdir" (which must exist).
4826
4827       To download to the current directory, use "." as in:
4828
4829        C<guestfs_copy_out> /home .
4830
4831       Wildcards cannot be used.
4832
4833       This function returns 0 on success or -1 on error.
4834
4835       (Added in 1.29.24)
4836
4837   guestfs_copy_size
4838        int
4839        guestfs_copy_size (guestfs_h *g,
4840                           const char *src,
4841                           const char *dest,
4842                           int64_t size);
4843
4844       This function is deprecated.  In new code, use the
4845       "guestfs_copy_device_to_device" call instead.
4846
4847       Deprecated functions will not be removed from the API, but the fact
4848       that they are deprecated indicates that there are problems with correct
4849       use of these functions.
4850
4851       This command copies exactly "size" bytes from one source device or file
4852       "src" to another destination device or file "dest".
4853
4854       Note this will fail if the source is too short or if the destination is
4855       not large enough.
4856
4857       This function returns 0 on success or -1 on error.
4858
4859       This long-running command can generate progress notification messages
4860       so that the caller can display a progress bar or indicator.  To receive
4861       these messages, the caller must register a progress event callback.
4862       See "GUESTFS_EVENT_PROGRESS".
4863
4864       (Added in 1.0.87)
4865
4866   guestfs_cp
4867        int
4868        guestfs_cp (guestfs_h *g,
4869                    const char *src,
4870                    const char *dest);
4871
4872       This copies a file from "src" to "dest" where "dest" is either a
4873       destination filename or destination directory.
4874
4875       This function returns 0 on success or -1 on error.
4876
4877       (Added in 1.0.18)
4878
4879   guestfs_cp_a
4880        int
4881        guestfs_cp_a (guestfs_h *g,
4882                      const char *src,
4883                      const char *dest);
4884
4885       This copies a file or directory from "src" to "dest" recursively using
4886       the "cp -a" command.
4887
4888       This function returns 0 on success or -1 on error.
4889
4890       (Added in 1.0.18)
4891
4892   guestfs_cp_r
4893        int
4894        guestfs_cp_r (guestfs_h *g,
4895                      const char *src,
4896                      const char *dest);
4897
4898       This copies a file or directory from "src" to "dest" recursively using
4899       the "cp -rP" command.
4900
4901       Most users should use "guestfs_cp_a" instead.  This command is useful
4902       when you don't want to preserve permissions, because the target
4903       filesystem does not support it (primarily when writing to DOS FAT
4904       filesystems).
4905
4906       This function returns 0 on success or -1 on error.
4907
4908       (Added in 1.21.38)
4909
4910   guestfs_cpio_out
4911        int
4912        guestfs_cpio_out (guestfs_h *g,
4913                          const char *directory,
4914                          const char *cpiofile,
4915                          ...);
4916
4917       You may supply a list of optional arguments to this call.  Use zero or
4918       more of the following pairs of parameters, and terminate the list with
4919       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4920
4921        GUESTFS_CPIO_OUT_FORMAT, const char *format,
4922
4923       This command packs the contents of directory and downloads it to local
4924       file "cpiofile".
4925
4926       The optional "format" parameter can be used to select the format.  Only
4927       the following formats are currently permitted:
4928
4929       "newc"
4930           New (SVR4) portable format.  This format happens to be compatible
4931           with the cpio-like format used by the Linux kernel for initramfs.
4932
4933           This is the default format.
4934
4935       "crc"
4936           New (SVR4) portable format with a checksum.
4937
4938       This function returns 0 on success or -1 on error.
4939
4940       (Added in 1.27.9)
4941
4942   guestfs_cpio_out_va
4943        int
4944        guestfs_cpio_out_va (guestfs_h *g,
4945                             const char *directory,
4946                             const char *cpiofile,
4947                             va_list args);
4948
4949       This is the "va_list variant" of "guestfs_cpio_out".
4950
4951       See "CALLS WITH OPTIONAL ARGUMENTS".
4952
4953   guestfs_cpio_out_argv
4954        int
4955        guestfs_cpio_out_argv (guestfs_h *g,
4956                               const char *directory,
4957                               const char *cpiofile,
4958                               const struct guestfs_cpio_out_argv *optargs);
4959
4960       This is the "argv variant" of "guestfs_cpio_out".
4961
4962       See "CALLS WITH OPTIONAL ARGUMENTS".
4963
4964   guestfs_dd
4965        int
4966        guestfs_dd (guestfs_h *g,
4967                    const char *src,
4968                    const char *dest);
4969
4970       This function is deprecated.  In new code, use the
4971       "guestfs_copy_device_to_device" call instead.
4972
4973       Deprecated functions will not be removed from the API, but the fact
4974       that they are deprecated indicates that there are problems with correct
4975       use of these functions.
4976
4977       This command copies from one source device or file "src" to another
4978       destination device or file "dest".  Normally you would use this to copy
4979       to or from a device or partition, for example to duplicate a
4980       filesystem.
4981
4982       If the destination is a device, it must be as large or larger than the
4983       source file or device, otherwise the copy will fail.  This command
4984       cannot do partial copies (see "guestfs_copy_device_to_device").
4985
4986       This function returns 0 on success or -1 on error.
4987
4988       (Added in 1.0.80)
4989
4990   guestfs_device_index
4991        int
4992        guestfs_device_index (guestfs_h *g,
4993                              const char *device);
4994
4995       This function takes a device name (eg. "/dev/sdb") and returns the
4996       index of the device in the list of devices.
4997
4998       Index numbers start from 0.  The named device must exist, for example
4999       as a string returned from "guestfs_list_devices".
5000
5001       See also "guestfs_list_devices", "guestfs_part_to_dev".
5002
5003       On error this function returns -1.
5004
5005       (Added in 1.19.7)
5006
5007   guestfs_df
5008        char *
5009        guestfs_df (guestfs_h *g);
5010
5011       This command runs the "df" command to report disk space used.
5012
5013       This command is mostly useful for interactive sessions.  It is not
5014       intended that you try to parse the output string.  Use
5015       "guestfs_statvfs" from programs.
5016
5017       This function returns a string, or NULL on error.  The caller must free
5018       the returned string after use.
5019
5020       (Added in 1.0.54)
5021
5022   guestfs_df_h
5023        char *
5024        guestfs_df_h (guestfs_h *g);
5025
5026       This command runs the "df -h" command to report disk space used in
5027       human-readable format.
5028
5029       This command is mostly useful for interactive sessions.  It is not
5030       intended that you try to parse the output string.  Use
5031       "guestfs_statvfs" from programs.
5032
5033       This function returns a string, or NULL on error.  The caller must free
5034       the returned string after use.
5035
5036       (Added in 1.0.54)
5037
5038   guestfs_disk_create
5039        int
5040        guestfs_disk_create (guestfs_h *g,
5041                             const char *filename,
5042                             const char *format,
5043                             int64_t size,
5044                             ...);
5045
5046       You may supply a list of optional arguments to this call.  Use zero or
5047       more of the following pairs of parameters, and terminate the list with
5048       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
5049
5050        GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
5051        GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
5052        GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
5053        GUESTFS_DISK_CREATE_COMPAT, const char *compat,
5054        GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
5055
5056       Create a blank disk image called filename (a host file) with format
5057       "format" (usually "raw" or "qcow2").  The size is "size" bytes.
5058
5059       If used with the optional "backingfile" parameter, then a snapshot is
5060       created on top of the backing file.  In this case, "size" must be
5061       passed as "-1".  The size of the snapshot is the same as the size of
5062       the backing file, which is discovered automatically.  You are
5063       encouraged to also pass "backingformat" to describe the format of
5064       "backingfile".
5065
5066       If filename refers to a block device, then the device is formatted.
5067       The "size" is ignored since block devices have an intrinsic size.
5068
5069       The other optional parameters are:
5070
5071       "preallocation"
5072           If format is "raw", then this can be either "off" (or "sparse") or
5073           "full" to create a sparse or fully allocated file respectively.
5074           The default is "off".
5075
5076           If format is "qcow2", then this can be "off" (or "sparse"),
5077           "metadata" or "full".  Preallocating metadata can be faster when
5078           doing lots of writes, but uses more space.  The default is "off".
5079
5080       "compat"
5081           "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5082           supported by qemu ≥ 1.1.
5083
5084       "clustersize"
5085           "qcow2" only: Change the qcow2 cluster size.  The default is 65536
5086           (bytes) and this setting may be any power of two between 512 and
5087           2097152.
5088
5089       Note that this call does not add the new disk to the handle.  You may
5090       need to call "guestfs_add_drive_opts" separately.
5091
5092       This function returns 0 on success or -1 on error.
5093
5094       (Added in 1.25.31)
5095
5096   guestfs_disk_create_va
5097        int
5098        guestfs_disk_create_va (guestfs_h *g,
5099                                const char *filename,
5100                                const char *format,
5101                                int64_t size,
5102                                va_list args);
5103
5104       This is the "va_list variant" of "guestfs_disk_create".
5105
5106       See "CALLS WITH OPTIONAL ARGUMENTS".
5107
5108   guestfs_disk_create_argv
5109        int
5110        guestfs_disk_create_argv (guestfs_h *g,
5111                                  const char *filename,
5112                                  const char *format,
5113                                  int64_t size,
5114                                  const struct guestfs_disk_create_argv *optargs);
5115
5116       This is the "argv variant" of "guestfs_disk_create".
5117
5118       See "CALLS WITH OPTIONAL ARGUMENTS".
5119
5120   guestfs_disk_format
5121        char *
5122        guestfs_disk_format (guestfs_h *g,
5123                             const char *filename);
5124
5125       Detect and return the format of the disk image called filename.
5126       filename can also be a host device, etc.  If the format of the image
5127       could not be detected, then "unknown" is returned.
5128
5129       Note that detecting the disk format can be insecure under some
5130       circumstances.  See "CVE-2010-3851".
5131
5132       See also: "DISK IMAGE FORMATS"
5133
5134       This function returns a string, or NULL on error.  The caller must free
5135       the returned string after use.
5136
5137       (Added in 1.19.38)
5138
5139   guestfs_disk_has_backing_file
5140        int
5141        guestfs_disk_has_backing_file (guestfs_h *g,
5142                                       const char *filename);
5143
5144       Detect and return whether the disk image filename has a backing file.
5145
5146       Note that detecting disk features can be insecure under some
5147       circumstances.  See "CVE-2010-3851".
5148
5149       This function returns a C truth value on success or -1 on error.
5150
5151       (Added in 1.19.39)
5152
5153   guestfs_disk_virtual_size
5154        int64_t
5155        guestfs_disk_virtual_size (guestfs_h *g,
5156                                   const char *filename);
5157
5158       Detect and return the virtual size in bytes of the disk image called
5159       filename.
5160
5161       Note that detecting disk features can be insecure under some
5162       circumstances.  See "CVE-2010-3851".
5163
5164       On error this function returns -1.
5165
5166       (Added in 1.19.39)
5167
5168   guestfs_dmesg
5169        char *
5170        guestfs_dmesg (guestfs_h *g);
5171
5172       This returns the kernel messages ("dmesg" output) from the guest
5173       kernel.  This is sometimes useful for extended debugging of problems.
5174
5175       Another way to get the same information is to enable verbose messages
5176       with "guestfs_set_verbose" or by setting the environment variable
5177       "LIBGUESTFS_DEBUG=1" before running the program.
5178
5179       This function returns a string, or NULL on error.  The caller must free
5180       the returned string after use.
5181
5182       (Added in 1.0.18)
5183
5184   guestfs_download
5185        int
5186        guestfs_download (guestfs_h *g,
5187                          const char *remotefilename,
5188                          const char *filename);
5189
5190       Download file remotefilename and save it as filename on the local
5191       machine.
5192
5193       filename can also be a named pipe.
5194
5195       See also "guestfs_upload", "guestfs_cat".
5196
5197       This function returns 0 on success or -1 on error.
5198
5199       This long-running command can generate progress notification messages
5200       so that the caller can display a progress bar or indicator.  To receive
5201       these messages, the caller must register a progress event callback.
5202       See "GUESTFS_EVENT_PROGRESS".
5203
5204       (Added in 1.0.2)
5205
5206   guestfs_download_blocks
5207        int
5208        guestfs_download_blocks (guestfs_h *g,
5209                                 const char *device,
5210                                 int64_t start,
5211                                 int64_t stop,
5212                                 const char *filename,
5213                                 ...);
5214
5215       You may supply a list of optional arguments to this call.  Use zero or
5216       more of the following pairs of parameters, and terminate the list with
5217       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
5218
5219        GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5220
5221       Download the data units from start address to stop from the disk
5222       partition (eg. /dev/sda1) and save them as filename on the local
5223       machine.
5224
5225       The use of this API on sparse disk image formats such as QCOW, may
5226       result in large zero-filled files downloaded on the host.
5227
5228       The size of a data unit varies across filesystem implementations.  On
5229       NTFS filesystems data units are referred as clusters while on ExtX ones
5230       they are referred as fragments.
5231
5232       If the optional "unallocated" flag is true (default is false), only the
5233       unallocated blocks will be extracted.  This is useful to detect hidden
5234       data or to retrieve deleted files which data units have not been
5235       overwritten yet.
5236
5237       This function returns 0 on success or -1 on error.
5238
5239       This long-running command can generate progress notification messages
5240       so that the caller can display a progress bar or indicator.  To receive
5241       these messages, the caller must register a progress event callback.
5242       See "GUESTFS_EVENT_PROGRESS".
5243
5244       This function depends on the feature "sleuthkit".  See also
5245       "guestfs_feature_available".
5246
5247       (Added in 1.33.45)
5248
5249   guestfs_download_blocks_va
5250        int
5251        guestfs_download_blocks_va (guestfs_h *g,
5252                                    const char *device,
5253                                    int64_t start,
5254                                    int64_t stop,
5255                                    const char *filename,
5256                                    va_list args);
5257
5258       This is the "va_list variant" of "guestfs_download_blocks".
5259
5260       See "CALLS WITH OPTIONAL ARGUMENTS".
5261
5262   guestfs_download_blocks_argv
5263        int
5264        guestfs_download_blocks_argv (guestfs_h *g,
5265                                      const char *device,
5266                                      int64_t start,
5267                                      int64_t stop,
5268                                      const char *filename,
5269                                      const struct guestfs_download_blocks_argv *optargs);
5270
5271       This is the "argv variant" of "guestfs_download_blocks".
5272
5273       See "CALLS WITH OPTIONAL ARGUMENTS".
5274
5275   guestfs_download_inode
5276        int
5277        guestfs_download_inode (guestfs_h *g,
5278                                const char *device,
5279                                int64_t inode,
5280                                const char *filename);
5281
5282       Download a file given its inode from the disk partition (eg. /dev/sda1)
5283       and save it as filename on the local machine.
5284
5285       It is not required to mount the disk to run this command.
5286
5287       The command is capable of downloading deleted or inaccessible files.
5288
5289       This function returns 0 on success or -1 on error.
5290
5291       This long-running command can generate progress notification messages
5292       so that the caller can display a progress bar or indicator.  To receive
5293       these messages, the caller must register a progress event callback.
5294       See "GUESTFS_EVENT_PROGRESS".
5295
5296       This function depends on the feature "sleuthkit".  See also
5297       "guestfs_feature_available".
5298
5299       (Added in 1.33.14)
5300
5301   guestfs_download_offset
5302        int
5303        guestfs_download_offset (guestfs_h *g,
5304                                 const char *remotefilename,
5305                                 const char *filename,
5306                                 int64_t offset,
5307                                 int64_t size);
5308
5309       Download file remotefilename and save it as filename on the local
5310       machine.
5311
5312       remotefilename is read for "size" bytes starting at "offset" (this
5313       region must be within the file or device).
5314
5315       Note that there is no limit on the amount of data that can be
5316       downloaded with this call, unlike with "guestfs_pread", and this call
5317       always reads the full amount unless an error occurs.
5318
5319       See also "guestfs_download", "guestfs_pread".
5320
5321       This function returns 0 on success or -1 on error.
5322
5323       This long-running command can generate progress notification messages
5324       so that the caller can display a progress bar or indicator.  To receive
5325       these messages, the caller must register a progress event callback.
5326       See "GUESTFS_EVENT_PROGRESS".
5327
5328       (Added in 1.5.17)
5329
5330   guestfs_drop_caches
5331        int
5332        guestfs_drop_caches (guestfs_h *g,
5333                             int whattodrop);
5334
5335       This instructs the guest kernel to drop its page cache, and/or dentries
5336       and inode caches.  The parameter "whattodrop" tells the kernel what
5337       precisely to drop, see http://linux-mm.org/Drop_Caches
5338
5339       Setting "whattodrop" to 3 should drop everything.
5340
5341       This automatically calls sync(2) before the operation, so that the
5342       maximum guest memory is freed.
5343
5344       This function returns 0 on success or -1 on error.
5345
5346       (Added in 1.0.18)
5347
5348   guestfs_du
5349        int64_t
5350        guestfs_du (guestfs_h *g,
5351                    const char *path);
5352
5353       This command runs the "du -s" command to estimate file space usage for
5354       "path".
5355
5356       "path" can be a file or a directory.  If "path" is a directory then the
5357       estimate includes the contents of the directory and all subdirectories
5358       (recursively).
5359
5360       The result is the estimated size in kilobytes (ie. units of 1024
5361       bytes).
5362
5363       On error this function returns -1.
5364
5365       This long-running command can generate progress notification messages
5366       so that the caller can display a progress bar or indicator.  To receive
5367       these messages, the caller must register a progress event callback.
5368       See "GUESTFS_EVENT_PROGRESS".
5369
5370       (Added in 1.0.54)
5371
5372   guestfs_e2fsck
5373        int
5374        guestfs_e2fsck (guestfs_h *g,
5375                        const char *device,
5376                        ...);
5377
5378       You may supply a list of optional arguments to this call.  Use zero or
5379       more of the following pairs of parameters, and terminate the list with
5380       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
5381
5382        GUESTFS_E2FSCK_CORRECT, int correct,
5383        GUESTFS_E2FSCK_FORCEALL, int forceall,
5384
5385       This runs the ext2/ext3 filesystem checker on "device".  It can take
5386       the following optional arguments:
5387
5388       "correct"
5389           Automatically repair the file system. This option will cause e2fsck
5390           to automatically fix any filesystem problems that can be safely
5391           fixed without human intervention.
5392
5393           This option may not be specified at the same time as the "forceall"
5394           option.
5395
5396       "forceall"
5397           Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5398           used non-interactively.
5399
5400           This option may not be specified at the same time as the "correct"
5401           option.
5402
5403       This function returns 0 on success or -1 on error.
5404
5405       (Added in 1.15.17)
5406
5407   guestfs_e2fsck_va
5408        int
5409        guestfs_e2fsck_va (guestfs_h *g,
5410                           const char *device,
5411                           va_list args);
5412
5413       This is the "va_list variant" of "guestfs_e2fsck".
5414
5415       See "CALLS WITH OPTIONAL ARGUMENTS".
5416
5417   guestfs_e2fsck_argv
5418        int
5419        guestfs_e2fsck_argv (guestfs_h *g,
5420                             const char *device,
5421                             const struct guestfs_e2fsck_argv *optargs);
5422
5423       This is the "argv variant" of "guestfs_e2fsck".
5424
5425       See "CALLS WITH OPTIONAL ARGUMENTS".
5426
5427   guestfs_e2fsck_f
5428        int
5429        guestfs_e2fsck_f (guestfs_h *g,
5430                          const char *device);
5431
5432       This function is deprecated.  In new code, use the "guestfs_e2fsck"
5433       call instead.
5434
5435       Deprecated functions will not be removed from the API, but the fact
5436       that they are deprecated indicates that there are problems with correct
5437       use of these functions.
5438
5439       This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5440       checker on "device", noninteractively (-p), even if the filesystem
5441       appears to be clean (-f).
5442
5443       This function returns 0 on success or -1 on error.
5444
5445       (Added in 1.0.29)
5446
5447   guestfs_echo_daemon
5448        char *
5449        guestfs_echo_daemon (guestfs_h *g,
5450                             char *const *words);
5451
5452       This command concatenates the list of "words" passed with single spaces
5453       between them and returns the resulting string.
5454
5455       You can use this command to test the connection through to the daemon.
5456
5457       See also "guestfs_ping_daemon".
5458
5459       This function returns a string, or NULL on error.  The caller must free
5460       the returned string after use.
5461
5462       (Added in 1.0.69)
5463
5464   guestfs_egrep
5465        char **
5466        guestfs_egrep (guestfs_h *g,
5467                       const char *regex,
5468                       const char *path);
5469
5470       This function is deprecated.  In new code, use the "guestfs_grep" call
5471       instead.
5472
5473       Deprecated functions will not be removed from the API, but the fact
5474       that they are deprecated indicates that there are problems with correct
5475       use of these functions.
5476
5477       This calls the external "egrep" program and returns the matching lines.
5478
5479       This function returns a NULL-terminated array of strings (like
5480       environ(3)), or NULL if there was an error.  The caller must free the
5481       strings and the array after use.
5482
5483       Because of the message protocol, there is a transfer limit of somewhere
5484       between 2MB and 4MB.  See "PROTOCOL LIMITS".
5485
5486       (Added in 1.0.66)
5487
5488   guestfs_egrepi
5489        char **
5490        guestfs_egrepi (guestfs_h *g,
5491                        const char *regex,
5492                        const char *path);
5493
5494       This function is deprecated.  In new code, use the "guestfs_grep" call
5495       instead.
5496
5497       Deprecated functions will not be removed from the API, but the fact
5498       that they are deprecated indicates that there are problems with correct
5499       use of these functions.
5500
5501       This calls the external "egrep -i" program and returns the matching
5502       lines.
5503
5504       This function returns a NULL-terminated array of strings (like
5505       environ(3)), or NULL if there was an error.  The caller must free the
5506       strings and the array after use.
5507
5508       Because of the message protocol, there is a transfer limit of somewhere
5509       between 2MB and 4MB.  See "PROTOCOL LIMITS".
5510
5511       (Added in 1.0.66)
5512
5513   guestfs_equal
5514        int
5515        guestfs_equal (guestfs_h *g,
5516                       const char *file1,
5517                       const char *file2);
5518
5519       This compares the two files file1 and file2 and returns true if their
5520       content is exactly equal, or false otherwise.
5521
5522       The external cmp(1) program is used for the comparison.
5523
5524       This function returns a C truth value on success or -1 on error.
5525
5526       (Added in 1.0.18)
5527
5528   guestfs_exists
5529        int
5530        guestfs_exists (guestfs_h *g,
5531                        const char *path);
5532
5533       This returns "true" if and only if there is a file, directory (or
5534       anything) with the given "path" name.
5535
5536       See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5537
5538       This function returns a C truth value on success or -1 on error.
5539
5540       (Added in 0.8)
5541
5542   guestfs_extlinux
5543        int
5544        guestfs_extlinux (guestfs_h *g,
5545                          const char *directory);
5546
5547       Install the SYSLINUX bootloader on the device mounted at directory.
5548       Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5549       used on an ext2/3/4 or btrfs filesystem.
5550
5551       The directory parameter can be either a mountpoint, or a directory
5552       within the mountpoint.
5553
5554       You also have to mark the partition as "active"
5555       ("guestfs_part_set_bootable") and a Master Boot Record must be
5556       installed (eg. using "guestfs_pwrite_device") on the first sector of
5557       the whole disk.  The SYSLINUX package comes with some suitable Master
5558       Boot Records.  See the extlinux(1) man page for further information.
5559
5560       Additional configuration can be supplied to SYSLINUX by placing a file
5561       called extlinux.conf on the filesystem under directory.  For further
5562       information about the contents of this file, see extlinux(1).
5563
5564       See also "guestfs_syslinux".
5565
5566       This function returns 0 on success or -1 on error.
5567
5568       This function depends on the feature "extlinux".  See also
5569       "guestfs_feature_available".
5570
5571       (Added in 1.21.27)
5572
5573   guestfs_f2fs_expand
5574        int
5575        guestfs_f2fs_expand (guestfs_h *g,
5576                             const char *device);
5577
5578       This expands a f2fs filesystem to match the size of the underlying
5579       device.
5580
5581       This function returns 0 on success or -1 on error.
5582
5583       This function depends on the feature "f2fs".  See also
5584       "guestfs_feature_available".
5585
5586       (Added in 1.39.3)
5587
5588   guestfs_fallocate
5589        int
5590        guestfs_fallocate (guestfs_h *g,
5591                           const char *path,
5592                           int len);
5593
5594       This function is deprecated.  In new code, use the
5595       "guestfs_fallocate64" call instead.
5596
5597       Deprecated functions will not be removed from the API, but the fact
5598       that they are deprecated indicates that there are problems with correct
5599       use of these functions.
5600
5601       This command preallocates a file (containing zero bytes) named "path"
5602       of size "len" bytes.  If the file exists already, it is overwritten.
5603
5604       Do not confuse this with the guestfish-specific "alloc" command which
5605       allocates a file in the host and attaches it as a device.
5606
5607       This function returns 0 on success or -1 on error.
5608
5609       (Added in 1.0.66)
5610
5611   guestfs_fallocate64
5612        int
5613        guestfs_fallocate64 (guestfs_h *g,
5614                             const char *path,
5615                             int64_t len);
5616
5617       This command preallocates a file (containing zero bytes) named "path"
5618       of size "len" bytes.  If the file exists already, it is overwritten.
5619
5620       Note that this call allocates disk blocks for the file.  To create a
5621       sparse file use "guestfs_truncate_size" instead.
5622
5623       The deprecated call "guestfs_fallocate" does the same, but owing to an
5624       oversight it only allowed 30 bit lengths to be specified, effectively
5625       limiting the maximum size of files created through that call to 1GB.
5626
5627       Do not confuse this with the guestfish-specific "alloc" and "sparse"
5628       commands which create a file in the host and attach it as a device.
5629
5630       This function returns 0 on success or -1 on error.
5631
5632       (Added in 1.3.17)
5633
5634   guestfs_feature_available
5635        int
5636        guestfs_feature_available (guestfs_h *g,
5637                                   char *const *groups);
5638
5639       This is the same as "guestfs_available", but unlike that call it
5640       returns a simple true/false boolean result, instead of throwing an
5641       exception if a feature is not found.  For other documentation see
5642       "guestfs_available".
5643
5644       This function returns a C truth value on success or -1 on error.
5645
5646       (Added in 1.21.26)
5647
5648   guestfs_fgrep
5649        char **
5650        guestfs_fgrep (guestfs_h *g,
5651                       const char *pattern,
5652                       const char *path);
5653
5654       This function is deprecated.  In new code, use the "guestfs_grep" call
5655       instead.
5656
5657       Deprecated functions will not be removed from the API, but the fact
5658       that they are deprecated indicates that there are problems with correct
5659       use of these functions.
5660
5661       This calls the external "fgrep" program and returns the matching lines.
5662
5663       This function returns a NULL-terminated array of strings (like
5664       environ(3)), or NULL if there was an error.  The caller must free the
5665       strings and the array after use.
5666
5667       Because of the message protocol, there is a transfer limit of somewhere
5668       between 2MB and 4MB.  See "PROTOCOL LIMITS".
5669
5670       (Added in 1.0.66)
5671
5672   guestfs_fgrepi
5673        char **
5674        guestfs_fgrepi (guestfs_h *g,
5675                        const char *pattern,
5676                        const char *path);
5677
5678       This function is deprecated.  In new code, use the "guestfs_grep" call
5679       instead.
5680
5681       Deprecated functions will not be removed from the API, but the fact
5682       that they are deprecated indicates that there are problems with correct
5683       use of these functions.
5684
5685       This calls the external "fgrep -i" program and returns the matching
5686       lines.
5687
5688       This function returns a NULL-terminated array of strings (like
5689       environ(3)), or NULL if there was an error.  The caller must free the
5690       strings and the array after use.
5691
5692       Because of the message protocol, there is a transfer limit of somewhere
5693       between 2MB and 4MB.  See "PROTOCOL LIMITS".
5694
5695       (Added in 1.0.66)
5696
5697   guestfs_file
5698        char *
5699        guestfs_file (guestfs_h *g,
5700                      const char *path);
5701
5702       This call uses the standard file(1) command to determine the type or
5703       contents of the file.
5704
5705       This call will also transparently look inside various types of
5706       compressed file.
5707
5708       The exact command which runs is "file -zb path".  Note in particular
5709       that the filename is not prepended to the output (the -b option).
5710
5711       The output depends on the output of the underlying file(1) command and
5712       it can change in future in ways beyond our control.  In other words,
5713       the output is not guaranteed by the ABI.
5714
5715       See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5716       "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5717
5718       This function returns a string, or NULL on error.  The caller must free
5719       the returned string after use.
5720
5721       (Added in 1.9.1)
5722
5723   guestfs_file_architecture
5724        char *
5725        guestfs_file_architecture (guestfs_h *g,
5726                                   const char *filename);
5727
5728       This detects the architecture of the binary filename, and returns it if
5729       known.
5730
5731       Currently defined architectures are:
5732
5733       "aarch64"
5734           64 bit ARM.
5735
5736       "arm"
5737           32 bit ARM.
5738
5739       "i386"
5740           This string is returned for all 32 bit i386, i486, i586, i686
5741           binaries irrespective of the precise processor requirements of the
5742           binary.
5743
5744       "ia64"
5745           Intel Itanium.
5746
5747       "ppc"
5748           32 bit Power PC.
5749
5750       "ppc64"
5751           64 bit Power PC (big endian).
5752
5753       "ppc64le"
5754           64 bit Power PC (little endian).
5755
5756       "riscv32"
5757       "riscv64"
5758       "riscv128"
5759           RISC-V 32-, 64- or 128-bit variants.
5760
5761       "s390"
5762           31 bit IBM S/390.
5763
5764       "s390x"
5765           64 bit IBM S/390.
5766
5767       "sparc"
5768           32 bit SPARC.
5769
5770       "sparc64"
5771           64 bit SPARC V9 and above.
5772
5773       "x86_64"
5774           64 bit x86-64.
5775
5776       Libguestfs may return other architecture strings in future.
5777
5778       The function works on at least the following types of files:
5779
5780       ·   many types of Un*x and Linux binary
5781
5782       ·   many types of Un*x and Linux shared library
5783
5784       ·   Windows Win32 and Win64 binaries
5785
5786       ·   Windows Win32 and Win64 DLLs
5787
5788           Win32 binaries and DLLs return "i386".
5789
5790           Win64 binaries and DLLs return "x86_64".
5791
5792       ·   Linux kernel modules
5793
5794       ·   Linux new-style initrd images
5795
5796       ·   some non-x86 Linux vmlinuz kernels
5797
5798       What it can't do currently:
5799
5800       ·   static libraries (libfoo.a)
5801
5802       ·   Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5803
5804       ·   x86 Linux vmlinuz kernels
5805
5806           x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5807           and compressed code, and are horribly hard to unpack.  If you want
5808           to find the architecture of a kernel, use the architecture of the
5809           associated initrd or kernel module(s) instead.
5810
5811       This function returns a string, or NULL on error.  The caller must free
5812       the returned string after use.
5813
5814       (Added in 1.5.3)
5815
5816   guestfs_filesize
5817        int64_t
5818        guestfs_filesize (guestfs_h *g,
5819                          const char *file);
5820
5821       This command returns the size of file in bytes.
5822
5823       To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5824       "guestfs_is_dir", "guestfs_is_file" etc.  To get the size of block
5825       devices, use "guestfs_blockdev_getsize64".
5826
5827       On error this function returns -1.
5828
5829       (Added in 1.0.82)
5830
5831   guestfs_filesystem_available
5832        int
5833        guestfs_filesystem_available (guestfs_h *g,
5834                                      const char *filesystem);
5835
5836       Check whether libguestfs supports the named filesystem.  The argument
5837       "filesystem" is a filesystem name, such as "ext3".
5838
5839       You must call "guestfs_launch" before using this command.
5840
5841       This is mainly useful as a negative test.  If this returns true, it
5842       doesn't mean that a particular filesystem can be created or mounted,
5843       since filesystems can fail for other reasons such as it being a later
5844       version of the filesystem, or having incompatible features, or lacking
5845       the right mkfs.<fs> tool.
5846
5847       See also "guestfs_available", "guestfs_feature_available",
5848       "AVAILABILITY".
5849
5850       This function returns a C truth value on success or -1 on error.
5851
5852       (Added in 1.19.5)
5853
5854   guestfs_filesystem_walk
5855        struct guestfs_tsk_dirent_list *
5856        guestfs_filesystem_walk (guestfs_h *g,
5857                                 const char *device);
5858
5859       Walk through the internal structures of a disk partition (eg.
5860       /dev/sda1) in order to return a list of all the files and directories
5861       stored within.
5862
5863       It is not necessary to mount the disk partition to run this command.
5864
5865       All entries in the filesystem are returned. This function can list
5866       deleted or unaccessible files. The entries are not sorted.
5867
5868       The "tsk_dirent" structure contains the following fields.
5869
5870       "tsk_inode"
5871           Filesystem reference number of the node. It might be 0 if the node
5872           has been deleted.
5873
5874       "tsk_type"
5875           Basic file type information.  See below for a detailed list of
5876           values.
5877
5878       "tsk_size"
5879           File size in bytes. It might be "-1" if the node has been deleted.
5880
5881       "tsk_name"
5882           The file path relative to its directory.
5883
5884       "tsk_flags"
5885           Bitfield containing extra information regarding the entry.  It
5886           contains the logical OR of the following values:
5887
5888           0x0001
5889               If set to 1, the file is allocated and visible within the
5890               filesystem.  Otherwise, the file has been deleted.  Under
5891               certain circumstances, the function "download_inode" can be
5892               used to recover deleted files.
5893
5894           0x0002
5895               Filesystem such as NTFS and Ext2 or greater, separate the file
5896               name from the metadata structure.  The bit is set to 1 when the
5897               file name is in an unallocated state and the metadata structure
5898               is in an allocated one.  This generally implies the metadata
5899               has been reallocated to a new file.  Therefore, information
5900               such as file type, file size, timestamps, number of links and
5901               symlink target might not correspond with the ones of the
5902               original deleted entry.
5903
5904           0x0004
5905               The bit is set to 1 when the file is compressed using
5906               filesystem native compression support (NTFS). The API is not
5907               able to detect application level compression.
5908
5909       "tsk_atime_sec"
5910       "tsk_atime_nsec"
5911       "tsk_mtime_sec"
5912       "tsk_mtime_nsec"
5913       "tsk_ctime_sec"
5914       "tsk_ctime_nsec"
5915       "tsk_crtime_sec"
5916       "tsk_crtime_nsec"
5917           Respectively, access, modification, last status change and creation
5918           time in Unix format in seconds and nanoseconds.
5919
5920       "tsk_nlink"
5921           Number of file names pointing to this entry.
5922
5923       "tsk_link"
5924           If the entry is a symbolic link, this field will contain the path
5925           to the target file.
5926
5927       The "tsk_type" field will contain one of the following characters:
5928
5929       'b' Block special
5930
5931       'c' Char special
5932
5933       'd' Directory
5934
5935       'f' FIFO (named pipe)
5936
5937       'l' Symbolic link
5938
5939       'r' Regular file
5940
5941       's' Socket
5942
5943       'h' Shadow inode (Solaris)
5944
5945       'w' Whiteout inode (BSD)
5946
5947       'u' Unknown file type
5948
5949       This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
5950       there was an error.  The caller must call
5951       "guestfs_free_tsk_dirent_list" after use.
5952
5953       This long-running command can generate progress notification messages
5954       so that the caller can display a progress bar or indicator.  To receive
5955       these messages, the caller must register a progress event callback.
5956       See "GUESTFS_EVENT_PROGRESS".
5957
5958       This function depends on the feature "libtsk".  See also
5959       "guestfs_feature_available".
5960
5961       (Added in 1.33.39)
5962
5963   guestfs_fill
5964        int
5965        guestfs_fill (guestfs_h *g,
5966                      int c,
5967                      int len,
5968                      const char *path);
5969
5970       This command creates a new file called "path".  The initial content of
5971       the file is "len" octets of "c", where "c" must be a number in the
5972       range "[0..255]".
5973
5974       To fill a file with zero bytes (sparsely), it is much more efficient to
5975       use "guestfs_truncate_size".  To create a file with a pattern of
5976       repeating bytes use "guestfs_fill_pattern".
5977
5978       This function returns 0 on success or -1 on error.
5979
5980       This long-running command can generate progress notification messages
5981       so that the caller can display a progress bar or indicator.  To receive
5982       these messages, the caller must register a progress event callback.
5983       See "GUESTFS_EVENT_PROGRESS".
5984
5985       (Added in 1.0.79)
5986
5987   guestfs_fill_dir
5988        int
5989        guestfs_fill_dir (guestfs_h *g,
5990                          const char *dir,
5991                          int nr);
5992
5993       This function, useful for testing filesystems, creates "nr" empty files
5994       in the directory "dir" with names 00000000 through "nr-1" (ie. each
5995       file name is 8 digits long padded with zeroes).
5996
5997       This function returns 0 on success or -1 on error.
5998
5999       (Added in 1.19.32)
6000
6001   guestfs_fill_pattern
6002        int
6003        guestfs_fill_pattern (guestfs_h *g,
6004                              const char *pattern,
6005                              int len,
6006                              const char *path);
6007
6008       This function is like "guestfs_fill" except that it creates a new file
6009       of length "len" containing the repeating pattern of bytes in "pattern".
6010       The pattern is truncated if necessary to ensure the length of the file
6011       is exactly "len" bytes.
6012
6013       This function returns 0 on success or -1 on error.
6014
6015       This long-running command can generate progress notification messages
6016       so that the caller can display a progress bar or indicator.  To receive
6017       these messages, the caller must register a progress event callback.
6018       See "GUESTFS_EVENT_PROGRESS".
6019
6020       (Added in 1.3.12)
6021
6022   guestfs_find
6023        char **
6024        guestfs_find (guestfs_h *g,
6025                      const char *directory);
6026
6027       This command lists out all files and directories, recursively, starting
6028       at directory.  It is essentially equivalent to running the shell
6029       command "find directory -print" but some post-processing happens on the
6030       output, described below.
6031
6032       This returns a list of strings without any prefix.  Thus if the
6033       directory structure was:
6034
6035        /tmp/a
6036        /tmp/b
6037        /tmp/c/d
6038
6039       then the returned list from "guestfs_find" /tmp would be 4 elements:
6040
6041        a
6042        b
6043        c
6044        c/d
6045
6046       If directory is not a directory, then this command returns an error.
6047
6048       The returned list is sorted.
6049
6050       This function returns a NULL-terminated array of strings (like
6051       environ(3)), or NULL if there was an error.  The caller must free the
6052       strings and the array after use.
6053
6054       (Added in 1.0.27)
6055
6056   guestfs_find0
6057        int
6058        guestfs_find0 (guestfs_h *g,
6059                       const char *directory,
6060                       const char *files);
6061
6062       This command lists out all files and directories, recursively, starting
6063       at directory, placing the resulting list in the external file called
6064       files.
6065
6066       This command works the same way as "guestfs_find" with the following
6067       exceptions:
6068
6069       ·   The resulting list is written to an external file.
6070
6071       ·   Items (filenames) in the result are separated by "\0" characters.
6072           See find(1) option -print0.
6073
6074       ·   The result list is not sorted.
6075
6076       This function returns 0 on success or -1 on error.
6077
6078       (Added in 1.0.74)
6079
6080   guestfs_find_inode
6081        struct guestfs_tsk_dirent_list *
6082        guestfs_find_inode (guestfs_h *g,
6083                            const char *device,
6084                            int64_t inode);
6085
6086       Searches all the entries associated with the given inode.
6087
6088       For each entry, a "tsk_dirent" structure is returned.  See
6089       "filesystem_walk" for more information about "tsk_dirent" structures.
6090
6091       This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6092       there was an error.  The caller must call
6093       "guestfs_free_tsk_dirent_list" after use.
6094
6095       This long-running command can generate progress notification messages
6096       so that the caller can display a progress bar or indicator.  To receive
6097       these messages, the caller must register a progress event callback.
6098       See "GUESTFS_EVENT_PROGRESS".
6099
6100       This function depends on the feature "libtsk".  See also
6101       "guestfs_feature_available".
6102
6103       (Added in 1.35.6)
6104
6105   guestfs_findfs_label
6106        char *
6107        guestfs_findfs_label (guestfs_h *g,
6108                              const char *label);
6109
6110       This command searches the filesystems and returns the one which has the
6111       given label.  An error is returned if no such filesystem can be found.
6112
6113       To find the label of a filesystem, use "guestfs_vfs_label".
6114
6115       This function returns a string, or NULL on error.  The caller must free
6116       the returned string after use.
6117
6118       (Added in 1.5.3)
6119
6120   guestfs_findfs_uuid
6121        char *
6122        guestfs_findfs_uuid (guestfs_h *g,
6123                             const char *uuid);
6124
6125       This command searches the filesystems and returns the one which has the
6126       given UUID.  An error is returned if no such filesystem can be found.
6127
6128       To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6129
6130       This function returns a string, or NULL on error.  The caller must free
6131       the returned string after use.
6132
6133       (Added in 1.5.3)
6134
6135   guestfs_fsck
6136        int
6137        guestfs_fsck (guestfs_h *g,
6138                      const char *fstype,
6139                      const char *device);
6140
6141       This runs the filesystem checker (fsck) on "device" which should have
6142       filesystem type "fstype".
6143
6144       The returned integer is the status.  See fsck(8) for the list of status
6145       codes from "fsck".
6146
6147       Notes:
6148
6149       ·   Multiple status codes can be summed together.
6150
6151       ·   A non-zero return code can mean "success", for example if errors
6152           have been corrected on the filesystem.
6153
6154       ·   Checking or repairing NTFS volumes is not supported (by linux-
6155           ntfs).
6156
6157       This command is entirely equivalent to running "fsck -a -t fstype
6158       device".
6159
6160       On error this function returns -1.
6161
6162       (Added in 1.0.16)
6163
6164   guestfs_fstrim
6165        int
6166        guestfs_fstrim (guestfs_h *g,
6167                        const char *mountpoint,
6168                        ...);
6169
6170       You may supply a list of optional arguments to this call.  Use zero or
6171       more of the following pairs of parameters, and terminate the list with
6172       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
6173
6174        GUESTFS_FSTRIM_OFFSET, int64_t offset,
6175        GUESTFS_FSTRIM_LENGTH, int64_t length,
6176        GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6177
6178       Trim the free space in the filesystem mounted on "mountpoint".  The
6179       filesystem must be mounted read-write.
6180
6181       The filesystem contents are not affected, but any free space in the
6182       filesystem is "trimmed", that is, given back to the host device, thus
6183       making disk images more sparse, allowing unused space in qcow2 files to
6184       be reused, etc.
6185
6186       This operation requires support in libguestfs, the mounted filesystem,
6187       the host filesystem, qemu and the host kernel.  If this support isn't
6188       present it may give an error or even appear to run but do nothing.
6189
6190       In the case where the kernel vfs driver does not support trimming, this
6191       call will fail with errno set to "ENOTSUP".  Currently this happens
6192       when trying to trim FAT filesystems.
6193
6194       See also "guestfs_zero_free_space".  That is a slightly different
6195       operation that turns free space in the filesystem into zeroes.  It is
6196       valid to call "guestfs_fstrim" either instead of, or after calling
6197       "guestfs_zero_free_space".
6198
6199       This function returns 0 on success or -1 on error.
6200
6201       This function depends on the feature "fstrim".  See also
6202       "guestfs_feature_available".
6203
6204       (Added in 1.19.6)
6205
6206   guestfs_fstrim_va
6207        int
6208        guestfs_fstrim_va (guestfs_h *g,
6209                           const char *mountpoint,
6210                           va_list args);
6211
6212       This is the "va_list variant" of "guestfs_fstrim".
6213
6214       See "CALLS WITH OPTIONAL ARGUMENTS".
6215
6216   guestfs_fstrim_argv
6217        int
6218        guestfs_fstrim_argv (guestfs_h *g,
6219                             const char *mountpoint,
6220                             const struct guestfs_fstrim_argv *optargs);
6221
6222       This is the "argv variant" of "guestfs_fstrim".
6223
6224       See "CALLS WITH OPTIONAL ARGUMENTS".
6225
6226   guestfs_get_append
6227        const char *
6228        guestfs_get_append (guestfs_h *g);
6229
6230       Return the additional kernel options which are added to the libguestfs
6231       appliance kernel command line.
6232
6233       If "NULL" then no options are added.
6234
6235       This function returns a string which may be NULL.  There is no way to
6236       return an error from this function.  The string is owned by the guest
6237       handle and must not be freed.
6238
6239       (Added in 1.0.26)
6240
6241   guestfs_get_attach_method
6242        char *
6243        guestfs_get_attach_method (guestfs_h *g);
6244
6245       This function is deprecated.  In new code, use the
6246       "guestfs_get_backend" call instead.
6247
6248       Deprecated functions will not be removed from the API, but the fact
6249       that they are deprecated indicates that there are problems with correct
6250       use of these functions.
6251
6252       Return the current backend.
6253
6254       See "guestfs_set_backend" and "BACKEND".
6255
6256       This function returns a string, or NULL on error.  The caller must free
6257       the returned string after use.
6258
6259       (Added in 1.9.8)
6260
6261   guestfs_get_autosync
6262        int
6263        guestfs_get_autosync (guestfs_h *g);
6264
6265       Get the autosync flag.
6266
6267       This function returns a C truth value on success or -1 on error.
6268
6269       (Added in 0.3)
6270
6271   guestfs_get_backend
6272        char *
6273        guestfs_get_backend (guestfs_h *g);
6274
6275       Return the current backend.
6276
6277       This handle property was previously called the "attach method".
6278
6279       See "guestfs_set_backend" and "BACKEND".
6280
6281       This function returns a string, or NULL on error.  The caller must free
6282       the returned string after use.
6283
6284       (Added in 1.21.26)
6285
6286   guestfs_get_backend_setting
6287        char *
6288        guestfs_get_backend_setting (guestfs_h *g,
6289                                     const char *name);
6290
6291       Find a backend setting string which is either "name" or begins with
6292       "name=".  If "name", this returns the string "1".  If "name=", this
6293       returns the part after the equals sign (which may be an empty string).
6294
6295       If no such setting is found, this function throws an error.  The errno
6296       (see "guestfs_last_errno") will be "ESRCH" in this case.
6297
6298       See "BACKEND", "BACKEND SETTINGS".
6299
6300       This function returns a string, or NULL on error.  The caller must free
6301       the returned string after use.
6302
6303       (Added in 1.27.2)
6304
6305   guestfs_get_backend_settings
6306        char **
6307        guestfs_get_backend_settings (guestfs_h *g);
6308
6309       Return the current backend settings.
6310
6311       This call returns all backend settings strings.  If you want to find a
6312       single backend setting, see "guestfs_get_backend_setting".
6313
6314       See "BACKEND", "BACKEND SETTINGS".
6315
6316       This function returns a NULL-terminated array of strings (like
6317       environ(3)), or NULL if there was an error.  The caller must free the
6318       strings and the array after use.
6319
6320       (Added in 1.25.24)
6321
6322   guestfs_get_cachedir
6323        char *
6324        guestfs_get_cachedir (guestfs_h *g);
6325
6326       Get the directory used by the handle to store the appliance cache.
6327
6328       This function returns a string, or NULL on error.  The caller must free
6329       the returned string after use.
6330
6331       (Added in 1.19.58)
6332
6333   guestfs_get_direct
6334        int
6335        guestfs_get_direct (guestfs_h *g);
6336
6337       This function is deprecated.  In new code, use the
6338       "guestfs_internal_get_console_socket" call instead.
6339
6340       Deprecated functions will not be removed from the API, but the fact
6341       that they are deprecated indicates that there are problems with correct
6342       use of these functions.
6343
6344       Return the direct appliance mode flag.
6345
6346       This function returns a C truth value on success or -1 on error.
6347
6348       (Added in 1.0.72)
6349
6350   guestfs_get_e2attrs
6351        char *
6352        guestfs_get_e2attrs (guestfs_h *g,
6353                             const char *file);
6354
6355       This returns the file attributes associated with file.
6356
6357       The attributes are a set of bits associated with each inode which
6358       affect the behaviour of the file.  The attributes are returned as a
6359       string of letters (described below).  The string may be empty,
6360       indicating that no file attributes are set for this file.
6361
6362       These attributes are only present when the file is located on an
6363       ext2/3/4 filesystem.  Using this call on other filesystem types will
6364       result in an error.
6365
6366       The characters (file attributes) in the returned string are currently:
6367
6368       'A' When the file is accessed, its atime is not modified.
6369
6370       'a' The file is append-only.
6371
6372       'c' The file is compressed on-disk.
6373
6374       'D' (Directories only.)  Changes to this directory are written
6375           synchronously to disk.
6376
6377       'd' The file is not a candidate for backup (see dump(8)).
6378
6379       'E' The file has compression errors.
6380
6381       'e' The file is using extents.
6382
6383       'h' The file is storing its blocks in units of the filesystem blocksize
6384           instead of sectors.
6385
6386       'I' (Directories only.)  The directory is using hashed trees.
6387
6388       'i' The file is immutable.  It cannot be modified, deleted or renamed.
6389           No link can be created to this file.
6390
6391       'j' The file is data-journaled.
6392
6393       's' When the file is deleted, all its blocks will be zeroed.
6394
6395       'S' Changes to this file are written synchronously to disk.
6396
6397       'T' (Directories only.)  This is a hint to the block allocator that
6398           subdirectories contained in this directory should be spread across
6399           blocks.  If not present, the block allocator will try to group
6400           subdirectories together.
6401
6402       't' For a file, this disables tail-merging.  (Not used by upstream
6403           implementations of ext2.)
6404
6405       'u' When the file is deleted, its blocks will be saved, allowing the
6406           file to be undeleted.
6407
6408       'X' The raw contents of the compressed file may be accessed.
6409
6410       'Z' The compressed file is dirty.
6411
6412       More file attributes may be added to this list later.  Not all file
6413       attributes may be set for all kinds of files.  For detailed
6414       information, consult the chattr(1) man page.
6415
6416       See also "guestfs_set_e2attrs".
6417
6418       Don't confuse these attributes with extended attributes (see
6419       "guestfs_getxattr").
6420
6421       This function returns a string, or NULL on error.  The caller must free
6422       the returned string after use.
6423
6424       (Added in 1.17.31)
6425
6426   guestfs_get_e2generation
6427        int64_t
6428        guestfs_get_e2generation (guestfs_h *g,
6429                                  const char *file);
6430
6431       This returns the ext2 file generation of a file.  The generation (which
6432       used to be called the "version") is a number associated with an inode.
6433       This is most commonly used by NFS servers.
6434
6435       The generation is only present when the file is located on an ext2/3/4
6436       filesystem.  Using this call on other filesystem types will result in
6437       an error.
6438
6439       See "guestfs_set_e2generation".
6440
6441       On error this function returns -1.
6442
6443       (Added in 1.17.31)
6444
6445   guestfs_get_e2label
6446        char *
6447        guestfs_get_e2label (guestfs_h *g,
6448                             const char *device);
6449
6450       This function is deprecated.  In new code, use the "guestfs_vfs_label"
6451       call instead.
6452
6453       Deprecated functions will not be removed from the API, but the fact
6454       that they are deprecated indicates that there are problems with correct
6455       use of these functions.
6456
6457       This returns the ext2/3/4 filesystem label of the filesystem on
6458       "device".
6459
6460       This function returns a string, or NULL on error.  The caller must free
6461       the returned string after use.
6462
6463       (Added in 1.0.15)
6464
6465   guestfs_get_e2uuid
6466        char *
6467        guestfs_get_e2uuid (guestfs_h *g,
6468                            const char *device);
6469
6470       This function is deprecated.  In new code, use the "guestfs_vfs_uuid"
6471       call instead.
6472
6473       Deprecated functions will not be removed from the API, but the fact
6474       that they are deprecated indicates that there are problems with correct
6475       use of these functions.
6476
6477       This returns the ext2/3/4 filesystem UUID of the filesystem on
6478       "device".
6479
6480       This function returns a string, or NULL on error.  The caller must free
6481       the returned string after use.
6482
6483       (Added in 1.0.15)
6484
6485   guestfs_get_hv
6486        char *
6487        guestfs_get_hv (guestfs_h *g);
6488
6489       Return the current hypervisor binary.
6490
6491       This is always non-NULL.  If it wasn't set already, then this will
6492       return the default qemu binary name.
6493
6494       This function returns a string, or NULL on error.  The caller must free
6495       the returned string after use.
6496
6497       (Added in 1.23.17)
6498
6499   guestfs_get_identifier
6500        const char *
6501        guestfs_get_identifier (guestfs_h *g);
6502
6503       Get the handle identifier.  See "guestfs_set_identifier".
6504
6505       This function returns a string, or NULL on error.  The string is owned
6506       by the guest handle and must not be freed.
6507
6508       (Added in 1.31.14)
6509
6510   guestfs_get_libvirt_requested_credential_challenge
6511        char *
6512        guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6513                                                            int index);
6514
6515       Get the challenge (provided by libvirt) for the "index"'th requested
6516       credential.  If libvirt did not provide a challenge, this returns the
6517       empty string "".
6518
6519       See "LIBVIRT AUTHENTICATION" for documentation and example code.
6520
6521       This function returns a string, or NULL on error.  The caller must free
6522       the returned string after use.
6523
6524       (Added in 1.19.52)
6525
6526   guestfs_get_libvirt_requested_credential_defresult
6527        char *
6528        guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6529                                                            int index);
6530
6531       Get the default result (provided by libvirt) for the "index"'th
6532       requested credential.  If libvirt did not provide a default result,
6533       this returns the empty string "".
6534
6535       See "LIBVIRT AUTHENTICATION" for documentation and example code.
6536
6537       This function returns a string, or NULL on error.  The caller must free
6538       the returned string after use.
6539
6540       (Added in 1.19.52)
6541
6542   guestfs_get_libvirt_requested_credential_prompt
6543        char *
6544        guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6545                                                         int index);
6546
6547       Get the prompt (provided by libvirt) for the "index"'th requested
6548       credential.  If libvirt did not provide a prompt, this returns the
6549       empty string "".
6550
6551       See "LIBVIRT AUTHENTICATION" for documentation and example code.
6552
6553       This function returns a string, or NULL on error.  The caller must free
6554       the returned string after use.
6555
6556       (Added in 1.19.52)
6557
6558   guestfs_get_libvirt_requested_credentials
6559        char **
6560        guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6561
6562       This should only be called during the event callback for events of type
6563       "GUESTFS_EVENT_LIBVIRT_AUTH".
6564
6565       Return the list of credentials requested by libvirt.  Possible values
6566       are a subset of the strings provided when you called
6567       "guestfs_set_libvirt_supported_credentials".
6568
6569       See "LIBVIRT AUTHENTICATION" for documentation and example code.
6570
6571       This function returns a NULL-terminated array of strings (like
6572       environ(3)), or NULL if there was an error.  The caller must free the
6573       strings and the array after use.
6574
6575       (Added in 1.19.52)
6576
6577   guestfs_get_memsize
6578        int
6579        guestfs_get_memsize (guestfs_h *g);
6580
6581       This gets the memory size in megabytes allocated to the hypervisor.
6582
6583       If "guestfs_set_memsize" was not called on this handle, and if
6584       "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6585       default value for memsize.
6586
6587       For more information on the architecture of libguestfs, see guestfs(3).
6588
6589       On error this function returns -1.
6590
6591       (Added in 1.0.55)
6592
6593   guestfs_get_network
6594        int
6595        guestfs_get_network (guestfs_h *g);
6596
6597       This returns the enable network flag.
6598
6599       This function returns a C truth value on success or -1 on error.
6600
6601       (Added in 1.5.4)
6602
6603   guestfs_get_path
6604        const char *
6605        guestfs_get_path (guestfs_h *g);
6606
6607       Return the current search path.
6608
6609       This is always non-NULL.  If it wasn't set already, then this will
6610       return the default path.
6611
6612       This function returns a string, or NULL on error.  The string is owned
6613       by the guest handle and must not be freed.
6614
6615       (Added in 0.3)
6616
6617   guestfs_get_pgroup
6618        int
6619        guestfs_get_pgroup (guestfs_h *g);
6620
6621       This returns the process group flag.
6622
6623       This function returns a C truth value on success or -1 on error.
6624
6625       (Added in 1.11.18)
6626
6627   guestfs_get_pid
6628        int
6629        guestfs_get_pid (guestfs_h *g);
6630
6631       Return the process ID of the hypervisor.  If there is no hypervisor
6632       running, then this will return an error.
6633
6634       This is an internal call used for debugging and testing.
6635
6636       On error this function returns -1.
6637
6638       (Added in 1.0.56)
6639
6640   guestfs_get_program
6641        const char *
6642        guestfs_get_program (guestfs_h *g);
6643
6644       Get the program name.  See "guestfs_set_program".
6645
6646       This function returns a string, or NULL on error.  The string is owned
6647       by the guest handle and must not be freed.
6648
6649       (Added in 1.21.29)
6650
6651   guestfs_get_qemu
6652        const char *
6653        guestfs_get_qemu (guestfs_h *g);
6654
6655       This function is deprecated.  In new code, use the "guestfs_get_hv"
6656       call instead.
6657
6658       Deprecated functions will not be removed from the API, but the fact
6659       that they are deprecated indicates that there are problems with correct
6660       use of these functions.
6661
6662       Return the current hypervisor binary (usually qemu).
6663
6664       This is always non-NULL.  If it wasn't set already, then this will
6665       return the default qemu binary name.
6666
6667       This function returns a string, or NULL on error.  The string is owned
6668       by the guest handle and must not be freed.
6669
6670       (Added in 1.0.6)
6671
6672   guestfs_get_recovery_proc
6673        int
6674        guestfs_get_recovery_proc (guestfs_h *g);
6675
6676       Return the recovery process enabled flag.
6677
6678       This function returns a C truth value on success or -1 on error.
6679
6680       (Added in 1.0.77)
6681
6682   guestfs_get_selinux
6683        int
6684        guestfs_get_selinux (guestfs_h *g);
6685
6686       This function is deprecated.  In new code, use the
6687       "guestfs_selinux_relabel" call instead.
6688
6689       Deprecated functions will not be removed from the API, but the fact
6690       that they are deprecated indicates that there are problems with correct
6691       use of these functions.
6692
6693       This returns the current setting of the selinux flag which is passed to
6694       the appliance at boot time.  See "guestfs_set_selinux".
6695
6696       For more information on the architecture of libguestfs, see guestfs(3).
6697
6698       This function returns a C truth value on success or -1 on error.
6699
6700       (Added in 1.0.67)
6701
6702   guestfs_get_smp
6703        int
6704        guestfs_get_smp (guestfs_h *g);
6705
6706       This returns the number of virtual CPUs assigned to the appliance.
6707
6708       On error this function returns -1.
6709
6710       (Added in 1.13.15)
6711
6712   guestfs_get_sockdir
6713        char *
6714        guestfs_get_sockdir (guestfs_h *g);
6715
6716       Get the directory used by the handle to store temporary socket files.
6717
6718       This is different from "guestfs_tmpdir", as we need shorter paths for
6719       sockets (due to the limited buffers of filenames for UNIX sockets), and
6720       "guestfs_tmpdir" may be too long for them.
6721
6722       The environment variable "XDG_RUNTIME_DIR" controls the default value:
6723       If "XDG_RUNTIME_DIR" is set, then that is the default.  Else /tmp is
6724       the default.
6725
6726       This function returns a string, or NULL on error.  The caller must free
6727       the returned string after use.
6728
6729       (Added in 1.33.8)
6730
6731   guestfs_get_state
6732        int
6733        guestfs_get_state (guestfs_h *g);
6734
6735       This returns the current state as an opaque integer.  This is only
6736       useful for printing debug and internal error messages.
6737
6738       For more information on states, see guestfs(3).
6739
6740       On error this function returns -1.
6741
6742       (Added in 1.0.2)
6743
6744   guestfs_get_tmpdir
6745        char *
6746        guestfs_get_tmpdir (guestfs_h *g);
6747
6748       Get the directory used by the handle to store temporary files.
6749
6750       This function returns a string, or NULL on error.  The caller must free
6751       the returned string after use.
6752
6753       (Added in 1.19.58)
6754
6755   guestfs_get_trace
6756        int
6757        guestfs_get_trace (guestfs_h *g);
6758
6759       Return the command trace flag.
6760
6761       This function returns a C truth value on success or -1 on error.
6762
6763       (Added in 1.0.69)
6764
6765   guestfs_get_umask
6766        int
6767        guestfs_get_umask (guestfs_h *g);
6768
6769       Return the current umask.  By default the umask is 022 unless it has
6770       been set by calling "guestfs_umask".
6771
6772       On error this function returns -1.
6773
6774       (Added in 1.3.4)
6775
6776   guestfs_get_verbose
6777        int
6778        guestfs_get_verbose (guestfs_h *g);
6779
6780       This returns the verbose messages flag.
6781
6782       This function returns a C truth value on success or -1 on error.
6783
6784       (Added in 0.3)
6785
6786   guestfs_getcon
6787        char *
6788        guestfs_getcon (guestfs_h *g);
6789
6790       This function is deprecated.  In new code, use the
6791       "guestfs_selinux_relabel" call instead.
6792
6793       Deprecated functions will not be removed from the API, but the fact
6794       that they are deprecated indicates that there are problems with correct
6795       use of these functions.
6796
6797       This gets the SELinux security context of the daemon.
6798
6799       See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6800
6801       This function returns a string, or NULL on error.  The caller must free
6802       the returned string after use.
6803
6804       This function depends on the feature "selinux".  See also
6805       "guestfs_feature_available".
6806
6807       (Added in 1.0.67)
6808
6809   guestfs_getxattr
6810        char *
6811        guestfs_getxattr (guestfs_h *g,
6812                          const char *path,
6813                          const char *name,
6814                          size_t *size_r);
6815
6816       Get a single extended attribute from file "path" named "name".  This
6817       call follows symlinks.  If you want to lookup an extended attribute for
6818       the symlink itself, use "guestfs_lgetxattr".
6819
6820       Normally it is better to get all extended attributes from a file in one
6821       go by calling "guestfs_getxattrs".  However some Linux filesystem
6822       implementations are buggy and do not provide a way to list out
6823       attributes.  For these filesystems (notably ntfs-3g) you have to know
6824       the names of the extended attributes you want in advance and call this
6825       function.
6826
6827       Extended attribute values are blobs of binary data.  If there is no
6828       extended attribute named "name", this returns an error.
6829
6830       See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6831
6832       This function returns a buffer, or NULL on error.  The size of the
6833       returned buffer is written to *size_r.  The caller must free the
6834       returned buffer after use.
6835
6836       This function depends on the feature "linuxxattrs".  See also
6837       "guestfs_feature_available".
6838
6839       (Added in 1.7.24)
6840
6841   guestfs_getxattrs
6842        struct guestfs_xattr_list *
6843        guestfs_getxattrs (guestfs_h *g,
6844                           const char *path);
6845
6846       This call lists the extended attributes of the file or directory
6847       "path".
6848
6849       At the system call level, this is a combination of the listxattr(2) and
6850       getxattr(2) calls.
6851
6852       See also: "guestfs_lgetxattrs", attr(5).
6853
6854       This function returns a "struct guestfs_xattr_list *", or NULL if there
6855       was an error.  The caller must call "guestfs_free_xattr_list" after
6856       use.
6857
6858       This function depends on the feature "linuxxattrs".  See also
6859       "guestfs_feature_available".
6860
6861       (Added in 1.0.59)
6862
6863   guestfs_glob_expand
6864        char **
6865        guestfs_glob_expand (guestfs_h *g,
6866                             const char *pattern);
6867
6868       This function is provided for backwards compatibility with earlier
6869       versions of libguestfs.  It simply calls "guestfs_glob_expand_opts"
6870       with no optional arguments.
6871
6872       (Added in 1.0.50)
6873
6874   guestfs_glob_expand_opts
6875        char **
6876        guestfs_glob_expand_opts (guestfs_h *g,
6877                                  const char *pattern,
6878                                  ...);
6879
6880       You may supply a list of optional arguments to this call.  Use zero or
6881       more of the following pairs of parameters, and terminate the list with
6882       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
6883
6884        GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
6885
6886       This command searches for all the pathnames matching "pattern"
6887       according to the wildcard expansion rules used by the shell.
6888
6889       If no paths match, then this returns an empty list (note: not an
6890       error).
6891
6892       It is just a wrapper around the C glob(3) function with flags
6893       "GLOB_MARK|GLOB_BRACE".  See that manual page for more details.
6894
6895       "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
6896       and it defaults to true.  It can be explicitly set as off to return no
6897       trailing slashes in filenames of directories.
6898
6899       Notice that there is no equivalent command for expanding a device name
6900       (eg. /dev/sd*).  Use "guestfs_list_devices", "guestfs_list_partitions"
6901       etc functions instead.
6902
6903       This function returns a NULL-terminated array of strings (like
6904       environ(3)), or NULL if there was an error.  The caller must free the
6905       strings and the array after use.
6906
6907       (Added in 1.0.50)
6908
6909   guestfs_glob_expand_opts_va
6910        char **
6911        guestfs_glob_expand_opts_va (guestfs_h *g,
6912                                     const char *pattern,
6913                                     va_list args);
6914
6915       This is the "va_list variant" of "guestfs_glob_expand_opts".
6916
6917       See "CALLS WITH OPTIONAL ARGUMENTS".
6918
6919   guestfs_glob_expand_opts_argv
6920        char **
6921        guestfs_glob_expand_opts_argv (guestfs_h *g,
6922                                       const char *pattern,
6923                                       const struct guestfs_glob_expand_opts_argv *optargs);
6924
6925       This is the "argv variant" of "guestfs_glob_expand_opts".
6926
6927       See "CALLS WITH OPTIONAL ARGUMENTS".
6928
6929   guestfs_grep
6930        char **
6931        guestfs_grep (guestfs_h *g,
6932                      const char *regex,
6933                      const char *path);
6934
6935       This function is provided for backwards compatibility with earlier
6936       versions of libguestfs.  It simply calls "guestfs_grep_opts" with no
6937       optional arguments.
6938
6939       (Added in 1.0.66)
6940
6941   guestfs_grep_opts
6942        char **
6943        guestfs_grep_opts (guestfs_h *g,
6944                           const char *regex,
6945                           const char *path,
6946                           ...);
6947
6948       You may supply a list of optional arguments to this call.  Use zero or
6949       more of the following pairs of parameters, and terminate the list with
6950       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
6951
6952        GUESTFS_GREP_OPTS_EXTENDED, int extended,
6953        GUESTFS_GREP_OPTS_FIXED, int fixed,
6954        GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
6955        GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
6956
6957       This calls the external "grep" program and returns the matching lines.
6958
6959       The optional flags are:
6960
6961       "extended"
6962           Use extended regular expressions.  This is the same as using the -E
6963           flag.
6964
6965       "fixed"
6966           Match fixed (don't use regular expressions).  This is the same as
6967           using the -F flag.
6968
6969       "insensitive"
6970           Match case-insensitive.  This is the same as using the -i flag.
6971
6972       "compressed"
6973           Use "zgrep" instead of "grep".  This allows the input to be
6974           compress- or gzip-compressed.
6975
6976       This function returns a NULL-terminated array of strings (like
6977       environ(3)), or NULL if there was an error.  The caller must free the
6978       strings and the array after use.
6979
6980       Because of the message protocol, there is a transfer limit of somewhere
6981       between 2MB and 4MB.  See "PROTOCOL LIMITS".
6982
6983       (Added in 1.0.66)
6984
6985   guestfs_grep_opts_va
6986        char **
6987        guestfs_grep_opts_va (guestfs_h *g,
6988                              const char *regex,
6989                              const char *path,
6990                              va_list args);
6991
6992       This is the "va_list variant" of "guestfs_grep_opts".
6993
6994       See "CALLS WITH OPTIONAL ARGUMENTS".
6995
6996   guestfs_grep_opts_argv
6997        char **
6998        guestfs_grep_opts_argv (guestfs_h *g,
6999                                const char *regex,
7000                                const char *path,
7001                                const struct guestfs_grep_opts_argv *optargs);
7002
7003       This is the "argv variant" of "guestfs_grep_opts".
7004
7005       See "CALLS WITH OPTIONAL ARGUMENTS".
7006
7007   guestfs_grepi
7008        char **
7009        guestfs_grepi (guestfs_h *g,
7010                       const char *regex,
7011                       const char *path);
7012
7013       This function is deprecated.  In new code, use the "guestfs_grep" call
7014       instead.
7015
7016       Deprecated functions will not be removed from the API, but the fact
7017       that they are deprecated indicates that there are problems with correct
7018       use of these functions.
7019
7020       This calls the external "grep -i" program and returns the matching
7021       lines.
7022
7023       This function returns a NULL-terminated array of strings (like
7024       environ(3)), or NULL if there was an error.  The caller must free the
7025       strings and the array after use.
7026
7027       Because of the message protocol, there is a transfer limit of somewhere
7028       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7029
7030       (Added in 1.0.66)
7031
7032   guestfs_grub_install
7033        int
7034        guestfs_grub_install (guestfs_h *g,
7035                              const char *root,
7036                              const char *device);
7037
7038       This command installs GRUB 1 (the Grand Unified Bootloader) on
7039       "device", with the root directory being "root".
7040
7041       Notes:
7042
7043       ·   There is currently no way in the API to install grub2, which is
7044           used by most modern Linux guests.  It is possible to run the grub2
7045           command from the guest, although see the caveats in "RUNNING
7046           COMMANDS".
7047
7048       ·   This uses "grub-install" from the host.  Unfortunately grub is not
7049           always compatible with itself, so this only works in rather narrow
7050           circumstances.  Careful testing with each guest version is
7051           advisable.
7052
7053       ·   If grub-install reports the error "No suitable drive was found in
7054           the generated device map."  it may be that you need to create a
7055           /boot/grub/device.map file first that contains the mapping between
7056           grub device names and Linux device names.  It is usually sufficient
7057           to create a file containing:
7058
7059            (hd0) /dev/vda
7060
7061           replacing /dev/vda with the name of the installation device.
7062
7063       This function returns 0 on success or -1 on error.
7064
7065       This function depends on the feature "grub".  See also
7066       "guestfs_feature_available".
7067
7068       (Added in 1.0.17)
7069
7070   guestfs_head
7071        char **
7072        guestfs_head (guestfs_h *g,
7073                      const char *path);
7074
7075       This command returns up to the first 10 lines of a file as a list of
7076       strings.
7077
7078       This function returns a NULL-terminated array of strings (like
7079       environ(3)), or NULL if there was an error.  The caller must free the
7080       strings and the array after use.
7081
7082       Because of the message protocol, there is a transfer limit of somewhere
7083       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7084
7085       (Added in 1.0.54)
7086
7087   guestfs_head_n
7088        char **
7089        guestfs_head_n (guestfs_h *g,
7090                        int nrlines,
7091                        const char *path);
7092
7093       If the parameter "nrlines" is a positive number, this returns the first
7094       "nrlines" lines of the file "path".
7095
7096       If the parameter "nrlines" is a negative number, this returns lines
7097       from the file "path", excluding the last "nrlines" lines.
7098
7099       If the parameter "nrlines" is zero, this returns an empty list.
7100
7101       This function returns a NULL-terminated array of strings (like
7102       environ(3)), or NULL if there was an error.  The caller must free the
7103       strings and the array after use.
7104
7105       Because of the message protocol, there is a transfer limit of somewhere
7106       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7107
7108       (Added in 1.0.54)
7109
7110   guestfs_hexdump
7111        char *
7112        guestfs_hexdump (guestfs_h *g,
7113                         const char *path);
7114
7115       This runs "hexdump -C" on the given "path".  The result is the human-
7116       readable, canonical hex dump of the file.
7117
7118       This function returns a string, or NULL on error.  The caller must free
7119       the returned string after use.
7120
7121       Because of the message protocol, there is a transfer limit of somewhere
7122       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7123
7124       (Added in 1.0.22)
7125
7126   guestfs_hivex_close
7127        int
7128        guestfs_hivex_close (guestfs_h *g);
7129
7130       Close the current hivex handle.
7131
7132       This is a wrapper around the hivex(3) call of the same name.
7133
7134       This function returns 0 on success or -1 on error.
7135
7136       This function depends on the feature "hivex".  See also
7137       "guestfs_feature_available".
7138
7139       (Added in 1.19.35)
7140
7141   guestfs_hivex_commit
7142        int
7143        guestfs_hivex_commit (guestfs_h *g,
7144                              const char *filename);
7145
7146       Commit (write) changes to the hive.
7147
7148       If the optional filename parameter is null, then the changes are
7149       written back to the same hive that was opened.  If this is not null
7150       then they are written to the alternate filename given and the original
7151       hive is left untouched.
7152
7153       This is a wrapper around the hivex(3) call of the same name.
7154
7155       This function returns 0 on success or -1 on error.
7156
7157       This function depends on the feature "hivex".  See also
7158       "guestfs_feature_available".
7159
7160       (Added in 1.19.35)
7161
7162   guestfs_hivex_node_add_child
7163        int64_t
7164        guestfs_hivex_node_add_child (guestfs_h *g,
7165                                      int64_t parent,
7166                                      const char *name);
7167
7168       Add a child node to "parent" named "name".
7169
7170       This is a wrapper around the hivex(3) call of the same name.
7171
7172       On error this function returns -1.
7173
7174       This function depends on the feature "hivex".  See also
7175       "guestfs_feature_available".
7176
7177       (Added in 1.19.35)
7178
7179   guestfs_hivex_node_children
7180        struct guestfs_hivex_node_list *
7181        guestfs_hivex_node_children (guestfs_h *g,
7182                                     int64_t nodeh);
7183
7184       Return the list of nodes which are subkeys of "nodeh".
7185
7186       This is a wrapper around the hivex(3) call of the same name.
7187
7188       This function returns a "struct guestfs_hivex_node_list *", or NULL if
7189       there was an error.  The caller must call
7190       "guestfs_free_hivex_node_list" after use.
7191
7192       This function depends on the feature "hivex".  See also
7193       "guestfs_feature_available".
7194
7195       (Added in 1.19.35)
7196
7197   guestfs_hivex_node_delete_child
7198        int
7199        guestfs_hivex_node_delete_child (guestfs_h *g,
7200                                         int64_t nodeh);
7201
7202       Delete "nodeh", recursively if necessary.
7203
7204       This is a wrapper around the hivex(3) call of the same name.
7205
7206       This function returns 0 on success or -1 on error.
7207
7208       This function depends on the feature "hivex".  See also
7209       "guestfs_feature_available".
7210
7211       (Added in 1.19.35)
7212
7213   guestfs_hivex_node_get_child
7214        int64_t
7215        guestfs_hivex_node_get_child (guestfs_h *g,
7216                                      int64_t nodeh,
7217                                      const char *name);
7218
7219       Return the child of "nodeh" with the name "name", if it exists.  This
7220       can return 0 meaning the name was not found.
7221
7222       This is a wrapper around the hivex(3) call of the same name.
7223
7224       On error this function returns -1.
7225
7226       This function depends on the feature "hivex".  See also
7227       "guestfs_feature_available".
7228
7229       (Added in 1.19.35)
7230
7231   guestfs_hivex_node_get_value
7232        int64_t
7233        guestfs_hivex_node_get_value (guestfs_h *g,
7234                                      int64_t nodeh,
7235                                      const char *key);
7236
7237       Return the value attached to "nodeh" which has the name "key", if it
7238       exists.  This can return 0 meaning the key was not found.
7239
7240       This is a wrapper around the hivex(3) call of the same name.
7241
7242       On error this function returns -1.
7243
7244       This function depends on the feature "hivex".  See also
7245       "guestfs_feature_available".
7246
7247       (Added in 1.19.35)
7248
7249   guestfs_hivex_node_name
7250        char *
7251        guestfs_hivex_node_name (guestfs_h *g,
7252                                 int64_t nodeh);
7253
7254       Return the name of "nodeh".
7255
7256       This is a wrapper around the hivex(3) call of the same name.
7257
7258       This function returns a string, or NULL on error.  The caller must free
7259       the returned string after use.
7260
7261       This function depends on the feature "hivex".  See also
7262       "guestfs_feature_available".
7263
7264       (Added in 1.19.35)
7265
7266   guestfs_hivex_node_parent
7267        int64_t
7268        guestfs_hivex_node_parent (guestfs_h *g,
7269                                   int64_t nodeh);
7270
7271       Return the parent node of "nodeh".
7272
7273       This is a wrapper around the hivex(3) call of the same name.
7274
7275       On error this function returns -1.
7276
7277       This function depends on the feature "hivex".  See also
7278       "guestfs_feature_available".
7279
7280       (Added in 1.19.35)
7281
7282   guestfs_hivex_node_set_value
7283        int
7284        guestfs_hivex_node_set_value (guestfs_h *g,
7285                                      int64_t nodeh,
7286                                      const char *key,
7287                                      int64_t t,
7288                                      const char *val,
7289                                      size_t val_size);
7290
7291       Set or replace a single value under the node "nodeh".  The "key" is the
7292       name, "t" is the type, and "val" is the data.
7293
7294       This is a wrapper around the hivex(3) call of the same name.
7295
7296       This function returns 0 on success or -1 on error.
7297
7298       This function depends on the feature "hivex".  See also
7299       "guestfs_feature_available".
7300
7301       (Added in 1.19.35)
7302
7303   guestfs_hivex_node_values
7304        struct guestfs_hivex_value_list *
7305        guestfs_hivex_node_values (guestfs_h *g,
7306                                   int64_t nodeh);
7307
7308       Return the array of (key, datatype, data) tuples attached to "nodeh".
7309
7310       This is a wrapper around the hivex(3) call of the same name.
7311
7312       This function returns a "struct guestfs_hivex_value_list *", or NULL if
7313       there was an error.  The caller must call
7314       "guestfs_free_hivex_value_list" after use.
7315
7316       This function depends on the feature "hivex".  See also
7317       "guestfs_feature_available".
7318
7319       (Added in 1.19.35)
7320
7321   guestfs_hivex_open
7322        int
7323        guestfs_hivex_open (guestfs_h *g,
7324                            const char *filename,
7325                            ...);
7326
7327       You may supply a list of optional arguments to this call.  Use zero or
7328       more of the following pairs of parameters, and terminate the list with
7329       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
7330
7331        GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7332        GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7333        GUESTFS_HIVEX_OPEN_WRITE, int write,
7334        GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7335
7336       Open the Windows Registry hive file named filename.  If there was any
7337       previous hivex handle associated with this guestfs session, then it is
7338       closed.
7339
7340       This is a wrapper around the hivex(3) call of the same name.
7341
7342       This function returns 0 on success or -1 on error.
7343
7344       This function depends on the feature "hivex".  See also
7345       "guestfs_feature_available".
7346
7347       (Added in 1.19.35)
7348
7349   guestfs_hivex_open_va
7350        int
7351        guestfs_hivex_open_va (guestfs_h *g,
7352                               const char *filename,
7353                               va_list args);
7354
7355       This is the "va_list variant" of "guestfs_hivex_open".
7356
7357       See "CALLS WITH OPTIONAL ARGUMENTS".
7358
7359   guestfs_hivex_open_argv
7360        int
7361        guestfs_hivex_open_argv (guestfs_h *g,
7362                                 const char *filename,
7363                                 const struct guestfs_hivex_open_argv *optargs);
7364
7365       This is the "argv variant" of "guestfs_hivex_open".
7366
7367       See "CALLS WITH OPTIONAL ARGUMENTS".
7368
7369   guestfs_hivex_root
7370        int64_t
7371        guestfs_hivex_root (guestfs_h *g);
7372
7373       Return the root node of the hive.
7374
7375       This is a wrapper around the hivex(3) call of the same name.
7376
7377       On error this function returns -1.
7378
7379       This function depends on the feature "hivex".  See also
7380       "guestfs_feature_available".
7381
7382       (Added in 1.19.35)
7383
7384   guestfs_hivex_value_key
7385        char *
7386        guestfs_hivex_value_key (guestfs_h *g,
7387                                 int64_t valueh);
7388
7389       Return the key (name) field of a (key, datatype, data) tuple.
7390
7391       This is a wrapper around the hivex(3) call of the same name.
7392
7393       This function returns a string, or NULL on error.  The caller must free
7394       the returned string after use.
7395
7396       This function depends on the feature "hivex".  See also
7397       "guestfs_feature_available".
7398
7399       (Added in 1.19.35)
7400
7401   guestfs_hivex_value_string
7402        char *
7403        guestfs_hivex_value_string (guestfs_h *g,
7404                                    int64_t valueh);
7405
7406       This calls "guestfs_hivex_value_value" (which returns the data field
7407       from a hivex value tuple).  It then assumes that the field is a
7408       UTF-16LE string and converts the result to UTF-8 (or if this is not
7409       possible, it returns an error).
7410
7411       This is useful for reading strings out of the Windows registry.
7412       However it is not foolproof because the registry is not strongly-typed
7413       and fields can contain arbitrary or unexpected data.
7414
7415       This function returns a string, or NULL on error.  The caller must free
7416       the returned string after use.
7417
7418       This function depends on the feature "hivex".  See also
7419       "guestfs_feature_available".
7420
7421       (Added in 1.37.22)
7422
7423   guestfs_hivex_value_type
7424        int64_t
7425        guestfs_hivex_value_type (guestfs_h *g,
7426                                  int64_t valueh);
7427
7428       Return the data type field from a (key, datatype, data) tuple.
7429
7430       This is a wrapper around the hivex(3) call of the same name.
7431
7432       On error this function returns -1.
7433
7434       This function depends on the feature "hivex".  See also
7435       "guestfs_feature_available".
7436
7437       (Added in 1.19.35)
7438
7439   guestfs_hivex_value_utf8
7440        char *
7441        guestfs_hivex_value_utf8 (guestfs_h *g,
7442                                  int64_t valueh);
7443
7444       This function is deprecated.  In new code, use the
7445       "guestfs_hivex_value_string" call instead.
7446
7447       Deprecated functions will not be removed from the API, but the fact
7448       that they are deprecated indicates that there are problems with correct
7449       use of these functions.
7450
7451       This calls "guestfs_hivex_value_value" (which returns the data field
7452       from a hivex value tuple).  It then assumes that the field is a
7453       UTF-16LE string and converts the result to UTF-8 (or if this is not
7454       possible, it returns an error).
7455
7456       This is useful for reading strings out of the Windows registry.
7457       However it is not foolproof because the registry is not strongly-typed
7458       and fields can contain arbitrary or unexpected data.
7459
7460       This function returns a string, or NULL on error.  The caller must free
7461       the returned string after use.
7462
7463       This function depends on the feature "hivex".  See also
7464       "guestfs_feature_available".
7465
7466       (Added in 1.19.35)
7467
7468   guestfs_hivex_value_value
7469        char *
7470        guestfs_hivex_value_value (guestfs_h *g,
7471                                   int64_t valueh,
7472                                   size_t *size_r);
7473
7474       Return the data field of a (key, datatype, data) tuple.
7475
7476       This is a wrapper around the hivex(3) call of the same name.
7477
7478       See also: "guestfs_hivex_value_utf8".
7479
7480       This function returns a buffer, or NULL on error.  The size of the
7481       returned buffer is written to *size_r.  The caller must free the
7482       returned buffer after use.
7483
7484       This function depends on the feature "hivex".  See also
7485       "guestfs_feature_available".
7486
7487       (Added in 1.19.35)
7488
7489   guestfs_initrd_cat
7490        char *
7491        guestfs_initrd_cat (guestfs_h *g,
7492                            const char *initrdpath,
7493                            const char *filename,
7494                            size_t *size_r);
7495
7496       This command unpacks the file filename from the initrd file called
7497       initrdpath.  The filename must be given without the initial /
7498       character.
7499
7500       For example, in guestfish you could use the following command to
7501       examine the boot script (usually called /init) contained in a Linux
7502       initrd or initramfs image:
7503
7504        initrd-cat /boot/initrd-<version>.img init
7505
7506       See also "guestfs_initrd_list".
7507
7508       This function returns a buffer, or NULL on error.  The size of the
7509       returned buffer is written to *size_r.  The caller must free the
7510       returned buffer after use.
7511
7512       Because of the message protocol, there is a transfer limit of somewhere
7513       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7514
7515       (Added in 1.0.84)
7516
7517   guestfs_initrd_list
7518        char **
7519        guestfs_initrd_list (guestfs_h *g,
7520                             const char *path);
7521
7522       This command lists out files contained in an initrd.
7523
7524       The files are listed without any initial / character.  The files are
7525       listed in the order they appear (not necessarily alphabetical).
7526       Directory names are listed as separate items.
7527
7528       Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7529       as initrd.  We only support the newer initramfs format (compressed cpio
7530       files).
7531
7532       This function returns a NULL-terminated array of strings (like
7533       environ(3)), or NULL if there was an error.  The caller must free the
7534       strings and the array after use.
7535
7536       (Added in 1.0.54)
7537
7538   guestfs_inotify_add_watch
7539        int64_t
7540        guestfs_inotify_add_watch (guestfs_h *g,
7541                                   const char *path,
7542                                   int mask);
7543
7544       Watch "path" for the events listed in "mask".
7545
7546       Note that if "path" is a directory then events within that directory
7547       are watched, but this does not happen recursively (in subdirectories).
7548
7549       Note for non-C or non-Linux callers: the inotify events are defined by
7550       the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7551
7552       On error this function returns -1.
7553
7554       This function depends on the feature "inotify".  See also
7555       "guestfs_feature_available".
7556
7557       (Added in 1.0.66)
7558
7559   guestfs_inotify_close
7560        int
7561        guestfs_inotify_close (guestfs_h *g);
7562
7563       This closes the inotify handle which was previously opened by
7564       inotify_init.  It removes all watches, throws away any pending events,
7565       and deallocates all resources.
7566
7567       This function returns 0 on success or -1 on error.
7568
7569       This function depends on the feature "inotify".  See also
7570       "guestfs_feature_available".
7571
7572       (Added in 1.0.66)
7573
7574   guestfs_inotify_files
7575        char **
7576        guestfs_inotify_files (guestfs_h *g);
7577
7578       This function is a helpful wrapper around "guestfs_inotify_read" which
7579       just returns a list of pathnames of objects that were touched.  The
7580       returned pathnames are sorted and deduplicated.
7581
7582       This function returns a NULL-terminated array of strings (like
7583       environ(3)), or NULL if there was an error.  The caller must free the
7584       strings and the array after use.
7585
7586       This function depends on the feature "inotify".  See also
7587       "guestfs_feature_available".
7588
7589       (Added in 1.0.66)
7590
7591   guestfs_inotify_init
7592        int
7593        guestfs_inotify_init (guestfs_h *g,
7594                              int maxevents);
7595
7596       This command creates a new inotify handle.  The inotify subsystem can
7597       be used to notify events which happen to objects in the guest
7598       filesystem.
7599
7600       "maxevents" is the maximum number of events which will be queued up
7601       between calls to "guestfs_inotify_read" or "guestfs_inotify_files".  If
7602       this is passed as 0, then the kernel (or previously set) default is
7603       used.  For Linux 2.6.29 the default was 16384 events.  Beyond this
7604       limit, the kernel throws away events, but records the fact that it
7605       threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7606       structure list (see "guestfs_inotify_read").
7607
7608       Before any events are generated, you have to add some watches to the
7609       internal watch list.  See: "guestfs_inotify_add_watch" and
7610       "guestfs_inotify_rm_watch".
7611
7612       Queued up events should be read periodically by calling
7613       "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7614       helpful wrapper around "guestfs_inotify_read").  If you don't read the
7615       events out often enough then you risk the internal queue overflowing.
7616
7617       The handle should be closed after use by calling
7618       "guestfs_inotify_close".  This also removes any watches automatically.
7619
7620       See also inotify(7) for an overview of the inotify interface as exposed
7621       by the Linux kernel, which is roughly what we expose via libguestfs.
7622       Note that there is one global inotify handle per libguestfs instance.
7623
7624       This function returns 0 on success or -1 on error.
7625
7626       This function depends on the feature "inotify".  See also
7627       "guestfs_feature_available".
7628
7629       (Added in 1.0.66)
7630
7631   guestfs_inotify_read
7632        struct guestfs_inotify_event_list *
7633        guestfs_inotify_read (guestfs_h *g);
7634
7635       Return the complete queue of events that have happened since the
7636       previous read call.
7637
7638       If no events have happened, this returns an empty list.
7639
7640       Note: In order to make sure that all events have been read, you must
7641       call this function repeatedly until it returns an empty list.  The
7642       reason is that the call will read events up to the maximum appliance-
7643       to-host message size and leave remaining events in the queue.
7644
7645       This function returns a "struct guestfs_inotify_event_list *", or NULL
7646       if there was an error.  The caller must call
7647       "guestfs_free_inotify_event_list" after use.
7648
7649       This function depends on the feature "inotify".  See also
7650       "guestfs_feature_available".
7651
7652       (Added in 1.0.66)
7653
7654   guestfs_inotify_rm_watch
7655        int
7656        guestfs_inotify_rm_watch (guestfs_h *g,
7657                                  int wd);
7658
7659       Remove a previously defined inotify watch.  See
7660       "guestfs_inotify_add_watch".
7661
7662       This function returns 0 on success or -1 on error.
7663
7664       This function depends on the feature "inotify".  See also
7665       "guestfs_feature_available".
7666
7667       (Added in 1.0.66)
7668
7669   guestfs_inspect_get_arch
7670        char *
7671        guestfs_inspect_get_arch (guestfs_h *g,
7672                                  const char *root);
7673
7674       This returns the architecture of the inspected operating system.  The
7675       possible return values are listed under "guestfs_file_architecture".
7676
7677       If the architecture could not be determined, then the string "unknown"
7678       is returned.
7679
7680       Please read "INSPECTION" for more details.
7681
7682       This function returns a string, or NULL on error.  The caller must free
7683       the returned string after use.
7684
7685       (Added in 1.5.3)
7686
7687   guestfs_inspect_get_distro
7688        char *
7689        guestfs_inspect_get_distro (guestfs_h *g,
7690                                    const char *root);
7691
7692       This returns the distro (distribution) of the inspected operating
7693       system.
7694
7695       Currently defined distros are:
7696
7697       "alpinelinux"
7698           Alpine Linux.
7699
7700       "altlinux"
7701           ALT Linux.
7702
7703       "archlinux"
7704           Arch Linux.
7705
7706       "buildroot"
7707           Buildroot-derived distro, but not one we specifically recognize.
7708
7709       "centos"
7710           CentOS.
7711
7712       "cirros"
7713           Cirros.
7714
7715       "coreos"
7716           CoreOS.
7717
7718       "debian"
7719           Debian.
7720
7721       "fedora"
7722           Fedora.
7723
7724       "freebsd"
7725           FreeBSD.
7726
7727       "freedos"
7728           FreeDOS.
7729
7730       "frugalware"
7731           Frugalware.
7732
7733       "gentoo"
7734           Gentoo.
7735
7736       "kalilinux"
7737           Kali Linux.
7738
7739       "linuxmint"
7740           Linux Mint.
7741
7742       "mageia"
7743           Mageia.
7744
7745       "mandriva"
7746           Mandriva.
7747
7748       "meego"
7749           MeeGo.
7750
7751       "msdos"
7752           Microsoft DOS.
7753
7754       "neokylin"
7755           NeoKylin.
7756
7757       "netbsd"
7758           NetBSD.
7759
7760       "openbsd"
7761           OpenBSD.
7762
7763       "opensuse"
7764           OpenSUSE.
7765
7766       "oraclelinux"
7767           Oracle Linux.
7768
7769       "pardus"
7770           Pardus.
7771
7772       "pldlinux"
7773           PLD Linux.
7774
7775       "redhat-based"
7776           Some Red Hat-derived distro.
7777
7778       "rhel"
7779           Red Hat Enterprise Linux.
7780
7781       "scientificlinux"
7782           Scientific Linux.
7783
7784       "slackware"
7785           Slackware.
7786
7787       "sles"
7788           SuSE Linux Enterprise Server or Desktop.
7789
7790       "suse-based"
7791           Some openSuSE-derived distro.
7792
7793       "ttylinux"
7794           ttylinux.
7795
7796       "ubuntu"
7797           Ubuntu.
7798
7799       "unknown"
7800           The distro could not be determined.
7801
7802       "voidlinux"
7803           Void Linux.
7804
7805       "windows"
7806           Windows does not have distributions.  This string is returned if
7807           the OS type is Windows.
7808
7809       Future versions of libguestfs may return other strings here.  The
7810       caller should be prepared to handle any string.
7811
7812       Please read "INSPECTION" for more details.
7813
7814       This function returns a string, or NULL on error.  The caller must free
7815       the returned string after use.
7816
7817       (Added in 1.5.3)
7818
7819   guestfs_inspect_get_drive_mappings
7820        char **
7821        guestfs_inspect_get_drive_mappings (guestfs_h *g,
7822                                            const char *root);
7823
7824       This call is useful for Windows which uses a primitive system of
7825       assigning drive letters (like C:\) to partitions.  This inspection API
7826       examines the Windows Registry to find out how disks/partitions are
7827       mapped to drive letters, and returns a hash table as in the example
7828       below:
7829
7830        C      =>     /dev/vda2
7831        E      =>     /dev/vdb1
7832        F      =>     /dev/vdc1
7833
7834       Note that keys are drive letters.  For Windows, the key is case
7835       insensitive and just contains the drive letter, without the customary
7836       colon separator character.
7837
7838       In future we may support other operating systems that also used drive
7839       letters, but the keys for those might not be case insensitive and might
7840       be longer than 1 character.  For example in OS-9, hard drives were
7841       named "h0", "h1" etc.
7842
7843       For Windows guests, currently only hard drive mappings are returned.
7844       Removable disks (eg. DVD-ROMs) are ignored.
7845
7846       For guests that do not use drive mappings, or if the drive mappings
7847       could not be determined, this returns an empty hash table.
7848
7849       Please read "INSPECTION" for more details.  See also
7850       "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7851
7852       This function returns a NULL-terminated array of strings, or NULL if
7853       there was an error.  The array of strings will always have length
7854       "2n+1", where "n" keys and values alternate, followed by the trailing
7855       NULL entry.  The caller must free the strings and the array after use.
7856
7857       (Added in 1.9.17)
7858
7859   guestfs_inspect_get_filesystems
7860        char **
7861        guestfs_inspect_get_filesystems (guestfs_h *g,
7862                                         const char *root);
7863
7864       This returns a list of all the filesystems that we think are associated
7865       with this operating system.  This includes the root filesystem, other
7866       ordinary filesystems, and non-mounted devices like swap partitions.
7867
7868       In the case of a multi-boot virtual machine, it is possible for a
7869       filesystem to be shared between operating systems.
7870
7871       Please read "INSPECTION" for more details.  See also
7872       "guestfs_inspect_get_mountpoints".
7873
7874       This function returns a NULL-terminated array of strings (like
7875       environ(3)), or NULL if there was an error.  The caller must free the
7876       strings and the array after use.
7877
7878       (Added in 1.5.3)
7879
7880   guestfs_inspect_get_format
7881        char *
7882        guestfs_inspect_get_format (guestfs_h *g,
7883                                    const char *root);
7884
7885       This function is deprecated.  There is no replacement.  Consult the API
7886       documentation in guestfs(3) for further information.
7887
7888       Deprecated functions will not be removed from the API, but the fact
7889       that they are deprecated indicates that there are problems with correct
7890       use of these functions.
7891
7892       Before libguestfs 1.38, there was some unreliable support for detecting
7893       installer CDs.  This API would return:
7894
7895       "installed"
7896           This is an installed operating system.
7897
7898       "installer"
7899           The disk image being inspected is not an installed operating
7900           system, but a bootable install disk, live CD, or similar.
7901
7902       "unknown"
7903           The format of this disk image is not known.
7904
7905       In libguestfs ≥ 1.38, this only returns "installed".  Use libosinfo
7906       directly to detect installer CDs.
7907
7908       Please read "INSPECTION" for more details.
7909
7910       This function returns a string, or NULL on error.  The caller must free
7911       the returned string after use.
7912
7913       (Added in 1.9.4)
7914
7915   guestfs_inspect_get_hostname
7916        char *
7917        guestfs_inspect_get_hostname (guestfs_h *g,
7918                                      const char *root);
7919
7920       This function returns the hostname of the operating system as found by
7921       inspection of the guest’s configuration files.
7922
7923       If the hostname could not be determined, then the string "unknown" is
7924       returned.
7925
7926       Please read "INSPECTION" for more details.
7927
7928       This function returns a string, or NULL on error.  The caller must free
7929       the returned string after use.
7930
7931       (Added in 1.7.9)
7932
7933   guestfs_inspect_get_icon
7934        char *
7935        guestfs_inspect_get_icon (guestfs_h *g,
7936                                  const char *root,
7937                                  size_t *size_r,
7938                                  ...);
7939
7940       You may supply a list of optional arguments to this call.  Use zero or
7941       more of the following pairs of parameters, and terminate the list with
7942       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
7943
7944        GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
7945        GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
7946
7947       This function returns an icon corresponding to the inspected operating
7948       system.  The icon is returned as a buffer containing a PNG image (re-
7949       encoded to PNG if necessary).
7950
7951       If it was not possible to get an icon this function returns a zero-
7952       length (non-NULL) buffer.  Callers must check for this case.
7953
7954       Libguestfs will start by looking for a file called /etc/favicon.png or
7955       C:\etc\favicon.png and if it has the correct format, the contents of
7956       this file will be returned.  You can disable favicons by passing the
7957       optional "favicon" boolean as false (default is true).
7958
7959       If finding the favicon fails, then we look in other places in the guest
7960       for a suitable icon.
7961
7962       If the optional "highquality" boolean is true then only high quality
7963       icons are returned, which means only icons of high resolution with an
7964       alpha channel.  The default (false) is to return any icon we can, even
7965       if it is of substandard quality.
7966
7967       Notes:
7968
7969       ·   Unlike most other inspection API calls, the guest’s disks must be
7970           mounted up before you call this, since it needs to read information
7971           from the guest filesystem during the call.
7972
7973       ·   Security: The icon data comes from the untrusted guest, and should
7974           be treated with caution.  PNG files have been known to contain
7975           exploits.  Ensure that libpng (or other relevant libraries) are
7976           fully up to date before trying to process or display the icon.
7977
7978       ·   The PNG image returned can be any size.  It might not be square.
7979           Libguestfs tries to return the largest, highest quality icon
7980           available.  The application must scale the icon to the required
7981           size.
7982
7983       ·   Extracting icons from Windows guests requires the external
7984           "wrestool" program from the "icoutils" package, and several
7985           programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
7986           package.  These must be installed separately.
7987
7988       ·   Operating system icons are usually trademarks.  Seek legal advice
7989           before using trademarks in applications.
7990
7991       This function returns a buffer, or NULL on error.  The size of the
7992       returned buffer is written to *size_r.  The caller must free the
7993       returned buffer after use.
7994
7995       (Added in 1.11.12)
7996
7997   guestfs_inspect_get_icon_va
7998        char *
7999        guestfs_inspect_get_icon_va (guestfs_h *g,
8000                                     const char *root,
8001                                     size_t *size_r,
8002                                     va_list args);
8003
8004       This is the "va_list variant" of "guestfs_inspect_get_icon".
8005
8006       See "CALLS WITH OPTIONAL ARGUMENTS".
8007
8008   guestfs_inspect_get_icon_argv
8009        char *
8010        guestfs_inspect_get_icon_argv (guestfs_h *g,
8011                                       const char *root,
8012                                       size_t *size_r,
8013                                       const struct guestfs_inspect_get_icon_argv *optargs);
8014
8015       This is the "argv variant" of "guestfs_inspect_get_icon".
8016
8017       See "CALLS WITH OPTIONAL ARGUMENTS".
8018
8019   guestfs_inspect_get_major_version
8020        int
8021        guestfs_inspect_get_major_version (guestfs_h *g,
8022                                           const char *root);
8023
8024       This returns the major version number of the inspected operating
8025       system.
8026
8027       Windows uses a consistent versioning scheme which is not reflected in
8028       the popular public names used by the operating system.  Notably the
8029       operating system known as "Windows 7" is really version 6.1 (ie. major
8030       = 6, minor = 1).  You can find out the real versions corresponding to
8031       releases of Windows by consulting Wikipedia or MSDN.
8032
8033       If the version could not be determined, then 0 is returned.
8034
8035       Please read "INSPECTION" for more details.
8036
8037       On error this function returns -1.
8038
8039       (Added in 1.5.3)
8040
8041   guestfs_inspect_get_minor_version
8042        int
8043        guestfs_inspect_get_minor_version (guestfs_h *g,
8044                                           const char *root);
8045
8046       This returns the minor version number of the inspected operating
8047       system.
8048
8049       If the version could not be determined, then 0 is returned.
8050
8051       Please read "INSPECTION" for more details.  See also
8052       "guestfs_inspect_get_major_version".
8053
8054       On error this function returns -1.
8055
8056       (Added in 1.5.3)
8057
8058   guestfs_inspect_get_mountpoints
8059        char **
8060        guestfs_inspect_get_mountpoints (guestfs_h *g,
8061                                         const char *root);
8062
8063       This returns a hash of where we think the filesystems associated with
8064       this operating system should be mounted.  Callers should note that this
8065       is at best an educated guess made by reading configuration files such
8066       as /etc/fstab.  In particular note that this may return filesystems
8067       which are non-existent or not mountable and callers should be prepared
8068       to handle or ignore failures if they try to mount them.
8069
8070       Each element in the returned hashtable has a key which is the path of
8071       the mountpoint (eg. /boot) and a value which is the filesystem that
8072       would be mounted there (eg. /dev/sda1).
8073
8074       Non-mounted devices such as swap devices are not returned in this list.
8075
8076       For operating systems like Windows which still use drive letters, this
8077       call will only return an entry for the first drive "mounted on" /.  For
8078       information about the mapping of drive letters to partitions, see
8079       "guestfs_inspect_get_drive_mappings".
8080
8081       Please read "INSPECTION" for more details.  See also
8082       "guestfs_inspect_get_filesystems".
8083
8084       This function returns a NULL-terminated array of strings, or NULL if
8085       there was an error.  The array of strings will always have length
8086       "2n+1", where "n" keys and values alternate, followed by the trailing
8087       NULL entry.  The caller must free the strings and the array after use.
8088
8089       (Added in 1.5.3)
8090
8091   guestfs_inspect_get_osinfo
8092        char *
8093        guestfs_inspect_get_osinfo (guestfs_h *g,
8094                                    const char *root);
8095
8096       This function returns a possible short ID for libosinfo corresponding
8097       to the guest.
8098
8099       Note: The returned ID is only a guess by libguestfs, and nothing
8100       ensures that it actually exists in osinfo-db.
8101
8102       If no ID could not be determined, then the string "unknown" is
8103       returned.
8104
8105       This function returns a string, or NULL on error.  The caller must free
8106       the returned string after use.
8107
8108       (Added in 1.39.1)
8109
8110   guestfs_inspect_get_package_format
8111        char *
8112        guestfs_inspect_get_package_format (guestfs_h *g,
8113                                            const char *root);
8114
8115       This function and "guestfs_inspect_get_package_management" return the
8116       package format and package management tool used by the inspected
8117       operating system.  For example for Fedora these functions would return
8118       "rpm" (package format), and "yum" or "dnf" (package management).
8119
8120       This returns the string "unknown" if we could not determine the package
8121       format or if the operating system does not have a real packaging system
8122       (eg. Windows).
8123
8124       Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8125       "pkgsrc", "apk", "xbps".  Future versions of libguestfs may return
8126       other strings.
8127
8128       Please read "INSPECTION" for more details.
8129
8130       This function returns a string, or NULL on error.  The caller must free
8131       the returned string after use.
8132
8133       (Added in 1.7.5)
8134
8135   guestfs_inspect_get_package_management
8136        char *
8137        guestfs_inspect_get_package_management (guestfs_h *g,
8138                                                const char *root);
8139
8140       "guestfs_inspect_get_package_format" and this function return the
8141       package format and package management tool used by the inspected
8142       operating system.  For example for Fedora these functions would return
8143       "rpm" (package format), and "yum" or "dnf" (package management).
8144
8145       This returns the string "unknown" if we could not determine the package
8146       management tool or if the operating system does not have a real
8147       packaging system (eg. Windows).
8148
8149       Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8150       Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8151       "apk", "xbps".  Future versions of libguestfs may return other strings.
8152
8153       Please read "INSPECTION" for more details.
8154
8155       This function returns a string, or NULL on error.  The caller must free
8156       the returned string after use.
8157
8158       (Added in 1.7.5)
8159
8160   guestfs_inspect_get_product_name
8161        char *
8162        guestfs_inspect_get_product_name (guestfs_h *g,
8163                                          const char *root);
8164
8165       This returns the product name of the inspected operating system.  The
8166       product name is generally some freeform string which can be displayed
8167       to the user, but should not be parsed by programs.
8168
8169       If the product name could not be determined, then the string "unknown"
8170       is returned.
8171
8172       Please read "INSPECTION" for more details.
8173
8174       This function returns a string, or NULL on error.  The caller must free
8175       the returned string after use.
8176
8177       (Added in 1.5.3)
8178
8179   guestfs_inspect_get_product_variant
8180        char *
8181        guestfs_inspect_get_product_variant (guestfs_h *g,
8182                                             const char *root);
8183
8184       This returns the product variant of the inspected operating system.
8185
8186       For Windows guests, this returns the contents of the Registry key
8187       "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8188       which is usually a string such as "Client" or "Server" (other values
8189       are possible).  This can be used to distinguish consumer and enterprise
8190       versions of Windows that have the same version number (for example,
8191       Windows 7 and Windows 2008 Server are both version 6.1, but the former
8192       is "Client" and the latter is "Server").
8193
8194       For enterprise Linux guests, in future we intend this to return the
8195       product variant such as "Desktop", "Server" and so on.  But this is not
8196       implemented at present.
8197
8198       If the product variant could not be determined, then the string
8199       "unknown" is returned.
8200
8201       Please read "INSPECTION" for more details.  See also
8202       "guestfs_inspect_get_product_name",
8203       "guestfs_inspect_get_major_version".
8204
8205       This function returns a string, or NULL on error.  The caller must free
8206       the returned string after use.
8207
8208       (Added in 1.9.13)
8209
8210   guestfs_inspect_get_roots
8211        char **
8212        guestfs_inspect_get_roots (guestfs_h *g);
8213
8214       This function is a convenient way to get the list of root devices, as
8215       returned from a previous call to "guestfs_inspect_os", but without
8216       redoing the whole inspection process.
8217
8218       This returns an empty list if either no root devices were found or the
8219       caller has not called "guestfs_inspect_os".
8220
8221       Please read "INSPECTION" for more details.
8222
8223       This function returns a NULL-terminated array of strings (like
8224       environ(3)), or NULL if there was an error.  The caller must free the
8225       strings and the array after use.
8226
8227       (Added in 1.7.3)
8228
8229   guestfs_inspect_get_type
8230        char *
8231        guestfs_inspect_get_type (guestfs_h *g,
8232                                  const char *root);
8233
8234       This returns the type of the inspected operating system.  Currently
8235       defined types are:
8236
8237       "linux"
8238           Any Linux-based operating system.
8239
8240       "windows"
8241           Any Microsoft Windows operating system.
8242
8243       "freebsd"
8244           FreeBSD.
8245
8246       "netbsd"
8247           NetBSD.
8248
8249       "openbsd"
8250           OpenBSD.
8251
8252       "hurd"
8253           GNU/Hurd.
8254
8255       "dos"
8256           MS-DOS, FreeDOS and others.
8257
8258       "minix"
8259           MINIX.
8260
8261       "unknown"
8262           The operating system type could not be determined.
8263
8264       Future versions of libguestfs may return other strings here.  The
8265       caller should be prepared to handle any string.
8266
8267       Please read "INSPECTION" for more details.
8268
8269       This function returns a string, or NULL on error.  The caller must free
8270       the returned string after use.
8271
8272       (Added in 1.5.3)
8273
8274   guestfs_inspect_get_windows_current_control_set
8275        char *
8276        guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8277                                                         const char *root);
8278
8279       This returns the Windows CurrentControlSet of the inspected guest.  The
8280       CurrentControlSet is a registry key name such as "ControlSet001".
8281
8282       This call assumes that the guest is Windows and that the Registry could
8283       be examined by inspection.  If this is not the case then an error is
8284       returned.
8285
8286       Please read "INSPECTION" for more details.
8287
8288       This function returns a string, or NULL on error.  The caller must free
8289       the returned string after use.
8290
8291       (Added in 1.9.17)
8292
8293   guestfs_inspect_get_windows_software_hive
8294        char *
8295        guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8296                                                   const char *root);
8297
8298       This returns the path to the hive (binary Windows Registry file)
8299       corresponding to HKLM\SOFTWARE.
8300
8301       This call assumes that the guest is Windows and that the guest has a
8302       software hive file with the right name.  If this is not the case then
8303       an error is returned.  This call does not check that the hive is a
8304       valid Windows Registry hive.
8305
8306       You can use "guestfs_hivex_open" to read or write to the hive.
8307
8308       Please read "INSPECTION" for more details.
8309
8310       This function returns a string, or NULL on error.  The caller must free
8311       the returned string after use.
8312
8313       (Added in 1.35.26)
8314
8315   guestfs_inspect_get_windows_system_hive
8316        char *
8317        guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8318                                                 const char *root);
8319
8320       This returns the path to the hive (binary Windows Registry file)
8321       corresponding to HKLM\SYSTEM.
8322
8323       This call assumes that the guest is Windows and that the guest has a
8324       system hive file with the right name.  If this is not the case then an
8325       error is returned.  This call does not check that the hive is a valid
8326       Windows Registry hive.
8327
8328       You can use "guestfs_hivex_open" to read or write to the hive.
8329
8330       Please read "INSPECTION" for more details.
8331
8332       This function returns a string, or NULL on error.  The caller must free
8333       the returned string after use.
8334
8335       (Added in 1.35.26)
8336
8337   guestfs_inspect_get_windows_systemroot
8338        char *
8339        guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8340                                                const char *root);
8341
8342       This returns the Windows systemroot of the inspected guest.  The
8343       systemroot is a directory path such as /WINDOWS.
8344
8345       This call assumes that the guest is Windows and that the systemroot
8346       could be determined by inspection.  If this is not the case then an
8347       error is returned.
8348
8349       Please read "INSPECTION" for more details.
8350
8351       This function returns a string, or NULL on error.  The caller must free
8352       the returned string after use.
8353
8354       (Added in 1.5.25)
8355
8356   guestfs_inspect_is_live
8357        int
8358        guestfs_inspect_is_live (guestfs_h *g,
8359                                 const char *root);
8360
8361       This function is deprecated.  There is no replacement.  Consult the API
8362       documentation in guestfs(3) for further information.
8363
8364       Deprecated functions will not be removed from the API, but the fact
8365       that they are deprecated indicates that there are problems with correct
8366       use of these functions.
8367
8368       This is deprecated and always returns "false".
8369
8370       Please read "INSPECTION" for more details.
8371
8372       This function returns a C truth value on success or -1 on error.
8373
8374       (Added in 1.9.4)
8375
8376   guestfs_inspect_is_multipart
8377        int
8378        guestfs_inspect_is_multipart (guestfs_h *g,
8379                                      const char *root);
8380
8381       This function is deprecated.  There is no replacement.  Consult the API
8382       documentation in guestfs(3) for further information.
8383
8384       Deprecated functions will not be removed from the API, but the fact
8385       that they are deprecated indicates that there are problems with correct
8386       use of these functions.
8387
8388       This is deprecated and always returns "false".
8389
8390       Please read "INSPECTION" for more details.
8391
8392       This function returns a C truth value on success or -1 on error.
8393
8394       (Added in 1.9.4)
8395
8396   guestfs_inspect_is_netinst
8397        int
8398        guestfs_inspect_is_netinst (guestfs_h *g,
8399                                    const char *root);
8400
8401       This function is deprecated.  There is no replacement.  Consult the API
8402       documentation in guestfs(3) for further information.
8403
8404       Deprecated functions will not be removed from the API, but the fact
8405       that they are deprecated indicates that there are problems with correct
8406       use of these functions.
8407
8408       This is deprecated and always returns "false".
8409
8410       Please read "INSPECTION" for more details.
8411
8412       This function returns a C truth value on success or -1 on error.
8413
8414       (Added in 1.9.4)
8415
8416   guestfs_inspect_list_applications
8417        struct guestfs_application_list *
8418        guestfs_inspect_list_applications (guestfs_h *g,
8419                                           const char *root);
8420
8421       This function is deprecated.  In new code, use the
8422       "guestfs_inspect_list_applications2" call instead.
8423
8424       Deprecated functions will not be removed from the API, but the fact
8425       that they are deprecated indicates that there are problems with correct
8426       use of these functions.
8427
8428       Return the list of applications installed in the operating system.
8429
8430       Note: This call works differently from other parts of the inspection
8431       API.  You have to call "guestfs_inspect_os", then
8432       "guestfs_inspect_get_mountpoints", then mount up the disks, before
8433       calling this.  Listing applications is a significantly more difficult
8434       operation which requires access to the full filesystem.  Also note that
8435       unlike the other "guestfs_inspect_get_*" calls which are just returning
8436       data cached in the libguestfs handle, this call actually reads parts of
8437       the mounted filesystems during the call.
8438
8439       This returns an empty list if the inspection code was not able to
8440       determine the list of applications.
8441
8442       The application structure contains the following fields:
8443
8444       "app_name"
8445           The name of the application.  For Red Hat-derived and Debian-
8446           derived Linux guests, this is the package name.
8447
8448       "app_display_name"
8449           The display name of the application, sometimes localized to the
8450           install language of the guest operating system.
8451
8452           If unavailable this is returned as an empty string "".  Callers
8453           needing to display something can use "app_name" instead.
8454
8455       "app_epoch"
8456           For package managers which use epochs, this contains the epoch of
8457           the package (an integer).  If unavailable, this is returned as 0.
8458
8459       "app_version"
8460           The version string of the application or package.  If unavailable
8461           this is returned as an empty string "".
8462
8463       "app_release"
8464           The release string of the application or package, for package
8465           managers that use this.  If unavailable this is returned as an
8466           empty string "".
8467
8468       "app_install_path"
8469           The installation path of the application (on operating systems such
8470           as Windows which use installation paths).  This path is in the
8471           format used by the guest operating system, it is not a libguestfs
8472           path.
8473
8474           If unavailable this is returned as an empty string "".
8475
8476       "app_trans_path"
8477           The install path translated into a libguestfs path.  If unavailable
8478           this is returned as an empty string "".
8479
8480       "app_publisher"
8481           The name of the publisher of the application, for package managers
8482           that use this.  If unavailable this is returned as an empty string
8483           "".
8484
8485       "app_url"
8486           The URL (eg. upstream URL) of the application.  If unavailable this
8487           is returned as an empty string "".
8488
8489       "app_source_package"
8490           For packaging systems which support this, the name of the source
8491           package.  If unavailable this is returned as an empty string "".
8492
8493       "app_summary"
8494           A short (usually one line) description of the application or
8495           package.  If unavailable this is returned as an empty string "".
8496
8497       "app_description"
8498           A longer description of the application or package.  If unavailable
8499           this is returned as an empty string "".
8500
8501       Please read "INSPECTION" for more details.
8502
8503       This function returns a "struct guestfs_application_list *", or NULL if
8504       there was an error.  The caller must call
8505       "guestfs_free_application_list" after use.
8506
8507       (Added in 1.7.8)
8508
8509   guestfs_inspect_list_applications2
8510        struct guestfs_application2_list *
8511        guestfs_inspect_list_applications2 (guestfs_h *g,
8512                                            const char *root);
8513
8514       Return the list of applications installed in the operating system.
8515
8516       Note: This call works differently from other parts of the inspection
8517       API.  You have to call "guestfs_inspect_os", then
8518       "guestfs_inspect_get_mountpoints", then mount up the disks, before
8519       calling this.  Listing applications is a significantly more difficult
8520       operation which requires access to the full filesystem.  Also note that
8521       unlike the other "guestfs_inspect_get_*" calls which are just returning
8522       data cached in the libguestfs handle, this call actually reads parts of
8523       the mounted filesystems during the call.
8524
8525       This returns an empty list if the inspection code was not able to
8526       determine the list of applications.
8527
8528       The application structure contains the following fields:
8529
8530       "app2_name"
8531           The name of the application.  For Red Hat-derived and Debian-
8532           derived Linux guests, this is the package name.
8533
8534       "app2_display_name"
8535           The display name of the application, sometimes localized to the
8536           install language of the guest operating system.
8537
8538           If unavailable this is returned as an empty string "".  Callers
8539           needing to display something can use "app2_name" instead.
8540
8541       "app2_epoch"
8542           For package managers which use epochs, this contains the epoch of
8543           the package (an integer).  If unavailable, this is returned as 0.
8544
8545       "app2_version"
8546           The version string of the application or package.  If unavailable
8547           this is returned as an empty string "".
8548
8549       "app2_release"
8550           The release string of the application or package, for package
8551           managers that use this.  If unavailable this is returned as an
8552           empty string "".
8553
8554       "app2_arch"
8555           The architecture string of the application or package, for package
8556           managers that use this.  If unavailable this is returned as an
8557           empty string "".
8558
8559       "app2_install_path"
8560           The installation path of the application (on operating systems such
8561           as Windows which use installation paths).  This path is in the
8562           format used by the guest operating system, it is not a libguestfs
8563           path.
8564
8565           If unavailable this is returned as an empty string "".
8566
8567       "app2_trans_path"
8568           The install path translated into a libguestfs path.  If unavailable
8569           this is returned as an empty string "".
8570
8571       "app2_publisher"
8572           The name of the publisher of the application, for package managers
8573           that use this.  If unavailable this is returned as an empty string
8574           "".
8575
8576       "app2_url"
8577           The URL (eg. upstream URL) of the application.  If unavailable this
8578           is returned as an empty string "".
8579
8580       "app2_source_package"
8581           For packaging systems which support this, the name of the source
8582           package.  If unavailable this is returned as an empty string "".
8583
8584       "app2_summary"
8585           A short (usually one line) description of the application or
8586           package.  If unavailable this is returned as an empty string "".
8587
8588       "app2_description"
8589           A longer description of the application or package.  If unavailable
8590           this is returned as an empty string "".
8591
8592       Please read "INSPECTION" for more details.
8593
8594       This function returns a "struct guestfs_application2_list *", or NULL
8595       if there was an error.  The caller must call
8596       "guestfs_free_application2_list" after use.
8597
8598       (Added in 1.19.56)
8599
8600   guestfs_inspect_os
8601        char **
8602        guestfs_inspect_os (guestfs_h *g);
8603
8604       This function uses other libguestfs functions and certain heuristics to
8605       inspect the disk(s) (usually disks belonging to a virtual machine),
8606       looking for operating systems.
8607
8608       The list returned is empty if no operating systems were found.
8609
8610       If one operating system was found, then this returns a list with a
8611       single element, which is the name of the root filesystem of this
8612       operating system.  It is also possible for this function to return a
8613       list containing more than one element, indicating a dual-boot or multi-
8614       boot virtual machine, with each element being the root filesystem of
8615       one of the operating systems.
8616
8617       You can pass the root string(s) returned to other
8618       "guestfs_inspect_get_*" functions in order to query further information
8619       about each operating system, such as the name and version.
8620
8621       This function uses other libguestfs features such as "guestfs_mount_ro"
8622       and "guestfs_umount_all" in order to mount and unmount filesystems and
8623       look at the contents.  This should be called with no disks currently
8624       mounted.  The function may also use Augeas, so any existing Augeas
8625       handle will be closed.
8626
8627       This function cannot decrypt encrypted disks.  The caller must do that
8628       first (supplying the necessary keys) if the disk is encrypted.
8629
8630       Please read "INSPECTION" for more details.
8631
8632       See also "guestfs_list_filesystems".
8633
8634       This function returns a NULL-terminated array of strings (like
8635       environ(3)), or NULL if there was an error.  The caller must free the
8636       strings and the array after use.
8637
8638       (Added in 1.5.3)
8639
8640   guestfs_is_blockdev
8641        int
8642        guestfs_is_blockdev (guestfs_h *g,
8643                             const char *path);
8644
8645       This function is provided for backwards compatibility with earlier
8646       versions of libguestfs.  It simply calls "guestfs_is_blockdev_opts"
8647       with no optional arguments.
8648
8649       (Added in 1.5.10)
8650
8651   guestfs_is_blockdev_opts
8652        int
8653        guestfs_is_blockdev_opts (guestfs_h *g,
8654                                  const char *path,
8655                                  ...);
8656
8657       You may supply a list of optional arguments to this call.  Use zero or
8658       more of the following pairs of parameters, and terminate the list with
8659       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8660
8661        GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8662
8663       This returns "true" if and only if there is a block device with the
8664       given "path" name.
8665
8666       If the optional flag "followsymlinks" is true, then a symlink (or chain
8667       of symlinks) that ends with a block device also causes the function to
8668       return true.
8669
8670       This call only looks at files within the guest filesystem.  Libguestfs
8671       partitions and block devices (eg. /dev/sda) cannot be used as the
8672       "path" parameter of this call.
8673
8674       See also "guestfs_stat".
8675
8676       This function returns a C truth value on success or -1 on error.
8677
8678       (Added in 1.5.10)
8679
8680   guestfs_is_blockdev_opts_va
8681        int
8682        guestfs_is_blockdev_opts_va (guestfs_h *g,
8683                                     const char *path,
8684                                     va_list args);
8685
8686       This is the "va_list variant" of "guestfs_is_blockdev_opts".
8687
8688       See "CALLS WITH OPTIONAL ARGUMENTS".
8689
8690   guestfs_is_blockdev_opts_argv
8691        int
8692        guestfs_is_blockdev_opts_argv (guestfs_h *g,
8693                                       const char *path,
8694                                       const struct guestfs_is_blockdev_opts_argv *optargs);
8695
8696       This is the "argv variant" of "guestfs_is_blockdev_opts".
8697
8698       See "CALLS WITH OPTIONAL ARGUMENTS".
8699
8700   guestfs_is_busy
8701        int
8702        guestfs_is_busy (guestfs_h *g);
8703
8704       This always returns false.  This function is deprecated with no
8705       replacement.  Do not use this function.
8706
8707       For more information on states, see guestfs(3).
8708
8709       This function returns a C truth value on success or -1 on error.
8710
8711       (Added in 1.0.2)
8712
8713   guestfs_is_chardev
8714        int
8715        guestfs_is_chardev (guestfs_h *g,
8716                            const char *path);
8717
8718       This function is provided for backwards compatibility with earlier
8719       versions of libguestfs.  It simply calls "guestfs_is_chardev_opts" with
8720       no optional arguments.
8721
8722       (Added in 1.5.10)
8723
8724   guestfs_is_chardev_opts
8725        int
8726        guestfs_is_chardev_opts (guestfs_h *g,
8727                                 const char *path,
8728                                 ...);
8729
8730       You may supply a list of optional arguments to this call.  Use zero or
8731       more of the following pairs of parameters, and terminate the list with
8732       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8733
8734        GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8735
8736       This returns "true" if and only if there is a character device with the
8737       given "path" name.
8738
8739       If the optional flag "followsymlinks" is true, then a symlink (or chain
8740       of symlinks) that ends with a chardev also causes the function to
8741       return true.
8742
8743       See also "guestfs_stat".
8744
8745       This function returns a C truth value on success or -1 on error.
8746
8747       (Added in 1.5.10)
8748
8749   guestfs_is_chardev_opts_va
8750        int
8751        guestfs_is_chardev_opts_va (guestfs_h *g,
8752                                    const char *path,
8753                                    va_list args);
8754
8755       This is the "va_list variant" of "guestfs_is_chardev_opts".
8756
8757       See "CALLS WITH OPTIONAL ARGUMENTS".
8758
8759   guestfs_is_chardev_opts_argv
8760        int
8761        guestfs_is_chardev_opts_argv (guestfs_h *g,
8762                                      const char *path,
8763                                      const struct guestfs_is_chardev_opts_argv *optargs);
8764
8765       This is the "argv variant" of "guestfs_is_chardev_opts".
8766
8767       See "CALLS WITH OPTIONAL ARGUMENTS".
8768
8769   guestfs_is_config
8770        int
8771        guestfs_is_config (guestfs_h *g);
8772
8773       This returns true iff this handle is being configured (in the "CONFIG"
8774       state).
8775
8776       For more information on states, see guestfs(3).
8777
8778       This function returns a C truth value on success or -1 on error.
8779
8780       (Added in 1.0.2)
8781
8782   guestfs_is_dir
8783        int
8784        guestfs_is_dir (guestfs_h *g,
8785                        const char *path);
8786
8787       This function is provided for backwards compatibility with earlier
8788       versions of libguestfs.  It simply calls "guestfs_is_dir_opts" with no
8789       optional arguments.
8790
8791       (Added in 0.8)
8792
8793   guestfs_is_dir_opts
8794        int
8795        guestfs_is_dir_opts (guestfs_h *g,
8796                             const char *path,
8797                             ...);
8798
8799       You may supply a list of optional arguments to this call.  Use zero or
8800       more of the following pairs of parameters, and terminate the list with
8801       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8802
8803        GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8804
8805       This returns "true" if and only if there is a directory with the given
8806       "path" name.  Note that it returns false for other objects like files.
8807
8808       If the optional flag "followsymlinks" is true, then a symlink (or chain
8809       of symlinks) that ends with a directory also causes the function to
8810       return true.
8811
8812       See also "guestfs_stat".
8813
8814       This function returns a C truth value on success or -1 on error.
8815
8816       (Added in 0.8)
8817
8818   guestfs_is_dir_opts_va
8819        int
8820        guestfs_is_dir_opts_va (guestfs_h *g,
8821                                const char *path,
8822                                va_list args);
8823
8824       This is the "va_list variant" of "guestfs_is_dir_opts".
8825
8826       See "CALLS WITH OPTIONAL ARGUMENTS".
8827
8828   guestfs_is_dir_opts_argv
8829        int
8830        guestfs_is_dir_opts_argv (guestfs_h *g,
8831                                  const char *path,
8832                                  const struct guestfs_is_dir_opts_argv *optargs);
8833
8834       This is the "argv variant" of "guestfs_is_dir_opts".
8835
8836       See "CALLS WITH OPTIONAL ARGUMENTS".
8837
8838   guestfs_is_fifo
8839        int
8840        guestfs_is_fifo (guestfs_h *g,
8841                         const char *path);
8842
8843       This function is provided for backwards compatibility with earlier
8844       versions of libguestfs.  It simply calls "guestfs_is_fifo_opts" with no
8845       optional arguments.
8846
8847       (Added in 1.5.10)
8848
8849   guestfs_is_fifo_opts
8850        int
8851        guestfs_is_fifo_opts (guestfs_h *g,
8852                              const char *path,
8853                              ...);
8854
8855       You may supply a list of optional arguments to this call.  Use zero or
8856       more of the following pairs of parameters, and terminate the list with
8857       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8858
8859        GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8860
8861       This returns "true" if and only if there is a FIFO (named pipe) with
8862       the given "path" name.
8863
8864       If the optional flag "followsymlinks" is true, then a symlink (or chain
8865       of symlinks) that ends with a FIFO also causes the function to return
8866       true.
8867
8868       See also "guestfs_stat".
8869
8870       This function returns a C truth value on success or -1 on error.
8871
8872       (Added in 1.5.10)
8873
8874   guestfs_is_fifo_opts_va
8875        int
8876        guestfs_is_fifo_opts_va (guestfs_h *g,
8877                                 const char *path,
8878                                 va_list args);
8879
8880       This is the "va_list variant" of "guestfs_is_fifo_opts".
8881
8882       See "CALLS WITH OPTIONAL ARGUMENTS".
8883
8884   guestfs_is_fifo_opts_argv
8885        int
8886        guestfs_is_fifo_opts_argv (guestfs_h *g,
8887                                   const char *path,
8888                                   const struct guestfs_is_fifo_opts_argv *optargs);
8889
8890       This is the "argv variant" of "guestfs_is_fifo_opts".
8891
8892       See "CALLS WITH OPTIONAL ARGUMENTS".
8893
8894   guestfs_is_file
8895        int
8896        guestfs_is_file (guestfs_h *g,
8897                         const char *path);
8898
8899       This function is provided for backwards compatibility with earlier
8900       versions of libguestfs.  It simply calls "guestfs_is_file_opts" with no
8901       optional arguments.
8902
8903       (Added in 0.8)
8904
8905   guestfs_is_file_opts
8906        int
8907        guestfs_is_file_opts (guestfs_h *g,
8908                              const char *path,
8909                              ...);
8910
8911       You may supply a list of optional arguments to this call.  Use zero or
8912       more of the following pairs of parameters, and terminate the list with
8913       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8914
8915        GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8916
8917       This returns "true" if and only if there is a regular file with the
8918       given "path" name.  Note that it returns false for other objects like
8919       directories.
8920
8921       If the optional flag "followsymlinks" is true, then a symlink (or chain
8922       of symlinks) that ends with a file also causes the function to return
8923       true.
8924
8925       See also "guestfs_stat".
8926
8927       This function returns a C truth value on success or -1 on error.
8928
8929       (Added in 0.8)
8930
8931   guestfs_is_file_opts_va
8932        int
8933        guestfs_is_file_opts_va (guestfs_h *g,
8934                                 const char *path,
8935                                 va_list args);
8936
8937       This is the "va_list variant" of "guestfs_is_file_opts".
8938
8939       See "CALLS WITH OPTIONAL ARGUMENTS".
8940
8941   guestfs_is_file_opts_argv
8942        int
8943        guestfs_is_file_opts_argv (guestfs_h *g,
8944                                   const char *path,
8945                                   const struct guestfs_is_file_opts_argv *optargs);
8946
8947       This is the "argv variant" of "guestfs_is_file_opts".
8948
8949       See "CALLS WITH OPTIONAL ARGUMENTS".
8950
8951   guestfs_is_launching
8952        int
8953        guestfs_is_launching (guestfs_h *g);
8954
8955       This returns true iff this handle is launching the subprocess (in the
8956       "LAUNCHING" state).
8957
8958       For more information on states, see guestfs(3).
8959
8960       This function returns a C truth value on success or -1 on error.
8961
8962       (Added in 1.0.2)
8963
8964   guestfs_is_lv
8965        int
8966        guestfs_is_lv (guestfs_h *g,
8967                       const char *mountable);
8968
8969       This command tests whether "mountable" is a logical volume, and returns
8970       true iff this is the case.
8971
8972       This function returns a C truth value on success or -1 on error.
8973
8974       (Added in 1.5.3)
8975
8976   guestfs_is_ready
8977        int
8978        guestfs_is_ready (guestfs_h *g);
8979
8980       This returns true iff this handle is ready to accept commands (in the
8981       "READY" state).
8982
8983       For more information on states, see guestfs(3).
8984
8985       This function returns a C truth value on success or -1 on error.
8986
8987       (Added in 1.0.2)
8988
8989   guestfs_is_socket
8990        int
8991        guestfs_is_socket (guestfs_h *g,
8992                           const char *path);
8993
8994       This function is provided for backwards compatibility with earlier
8995       versions of libguestfs.  It simply calls "guestfs_is_socket_opts" with
8996       no optional arguments.
8997