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
409Security: 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.  Windows BitLocker is also
513       supported.
514
515       Use "guestfs_vfs_type" to identify encrypted block devices.  For LUKS
516       it returns the string "crypto_LUKS".  For Windows BitLocker it returns
517       "BitLocker".
518
519       Then open these devices by calling "guestfs_cryptsetup_open".
520       Obviously you will require the passphrase!
521
522       Opening an encrypted device creates a new device mapper device called
523       /dev/mapper/mapname (where "mapname" is the string you supply to
524       "guestfs_cryptsetup_open").  Reads and writes to this mapper device are
525       decrypted from and encrypted to the underlying block device
526       respectively.
527
528       LVM volume groups on the device can be made visible by calling
529       "guestfs_vgscan" followed by "guestfs_vg_activate_all".  The logical
530       volume(s) can now be mounted in the usual way.
531
532       Use the reverse process to close an encrypted device.  Unmount any
533       logical volumes on it, deactivate the volume groups by calling
534       "guestfs_vg_activate (g, 0, ["/dev/VG"])".  Then close the mapper
535       device by calling "guestfs_cryptsetup_close" on the /dev/mapper/mapname
536       device (not the underlying encrypted block device).
537
538   MOUNT LOCAL
539       In libguestfs ≥ 1.18, it is possible to mount the libguestfs filesystem
540       on a local directory and access it using ordinary POSIX calls and
541       programs.
542
543       Availability of this is subject to a number of restrictions: it
544       requires FUSE (the Filesystem in USErspace), and libfuse must also have
545       been available when libguestfs was compiled.  FUSE may require that a
546       kernel module is loaded, and it may be necessary to add the current
547       user to a special "fuse" group.  See the documentation for your
548       distribution and http://fuse.sf.net for further information.
549
550       The call to mount the libguestfs filesystem on a local directory is
551       "guestfs_mount_local" (q.v.) followed by "guestfs_mount_local_run".
552       The latter does not return until you unmount the filesystem.  The
553       reason is that the call enters the FUSE main loop and processes kernel
554       requests, turning them into libguestfs calls.  An alternative design
555       would have been to create a background thread to do this, but
556       libguestfs doesn't require pthreads.  This way is also more flexible:
557       for example the user can create another thread for
558       "guestfs_mount_local_run".
559
560       "guestfs_mount_local" needs a certain amount of time to set up the
561       mountpoint.  The mountpoint is not ready to use until the call returns.
562       At this point, accesses to the filesystem will block until the main
563       loop is entered (ie. "guestfs_mount_local_run").  So if you need to
564       start another process to access the filesystem, put the fork between
565       "guestfs_mount_local" and "guestfs_mount_local_run".
566
567       MOUNT LOCAL COMPATIBILITY
568
569       Since local mounting was only added in libguestfs 1.18, and may not be
570       available even in these builds, you should consider writing code so
571       that it doesn't depend on this feature, and can fall back to using
572       libguestfs file system calls.
573
574       If libguestfs was compiled without support for "guestfs_mount_local"
575       then calling it will return an error with errno set to "ENOTSUP" (see
576       "guestfs_last_errno").
577
578       MOUNT LOCAL PERFORMANCE
579
580       Libguestfs on top of FUSE performs quite poorly.  For best performance
581       do not use it.  Use ordinary libguestfs filesystem calls, upload,
582       download etc. instead.
583
584   HOTPLUGGING
585       In libguestfs ≥ 1.20, you may add drives and remove after calling
586       "guestfs_launch".  There are some restrictions, see below.  This is
587       called hotplugging.
588
589       Only a subset of the backends support hotplugging (currently only the
590       libvirt backend has support).  It also requires that you use libvirt ≥
591       0.10.3 and qemu ≥ 1.2.
592
593       To hot-add a disk, simply call "guestfs_add_drive_opts" after
594       "guestfs_launch".  It is mandatory to specify the "label" parameter so
595       that the newly added disk has a predictable name.  For example:
596
597        if (guestfs_launch (g) == -1)
598          error ("launch failed");
599
600        if (guestfs_add_drive_opts (g, filename,
601                                    GUESTFS_ADD_DRIVE_OPTS_LABEL, "newdisk",
602                                    -1) == -1)
603          error ("hot-add of disk failed");
604
605        if (guestfs_part_disk ("/dev/disk/guestfs/newdisk", "mbr") == -1)
606          error ("partitioning of hot-added disk failed");
607
608       To hot-remove a disk, call "guestfs_remove_drive".  You can call this
609       before or after "guestfs_launch".  You can only remove disks that were
610       previously added with a label.
611
612       Backends that support hotplugging do not require that you add ≥ 1 disk
613       before calling launch.  When hotplugging is supported you don't need to
614       add any disks.
615
616   REMOTE STORAGE
617       CEPH
618
619       Libguestfs can access Ceph (librbd/RBD) disks.
620
621       To do this, set the optional "protocol" and "server" parameters of
622       "guestfs_add_drive_opts" like this:
623
624        char **servers = { "ceph1.example.org:3000", /* ... */, NULL };
625        guestfs_add_drive_opts (g, "pool/image",
626                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
627                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "rbd",
628                                GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
629                                GUESTFS_ADD_DRIVE_OPTS_USERNAME, "rbduser",
630                                GUESTFS_ADD_DRIVE_OPTS_SECRET, "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
631                                -1);
632
633       "servers" (the "server" parameter) is a list of one or more Ceph
634       servers.  The server string is documented in "guestfs_add_drive_opts".
635       The "username" and "secret" parameters are also optional, and if not
636       given, then no authentication will be used.
637
638       FTP, HTTP AND TFTP
639
640       Libguestfs can access remote disks over FTP, FTPS, HTTP, HTTPS or TFTP
641       protocols.
642
643       To do this, set the optional "protocol" and "server" parameters of
644       "guestfs_add_drive_opts" like this:
645
646        char **servers = { "www.example.org", NULL };
647        guestfs_add_drive_opts (g, "/disk.img",
648                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
649                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "http",
650                                GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
651                                -1);
652
653       The "protocol" can be one of "ftp", "ftps", "http", "https" or "tftp".
654
655       "servers" (the "server" parameter) is a list which must have a single
656       element.  The single element is a string defining the web, FTP or TFTP
657       server.  The format of this string is documented in
658       "guestfs_add_drive_opts".
659
660       GLUSTER
661
662       Libguestfs can access Gluster disks.
663
664       To do this, set the optional "protocol" and "server" parameters of
665       "guestfs_add_drive_opts" like this:
666
667        char **servers = { "gluster.example.org:24007", NULL };
668        guestfs_add_drive_opts (g, "volname/image",
669                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
670                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "gluster",
671                                GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
672                                -1);
673
674       "servers" (the "server" parameter) is a list which must have a single
675       element.  The single element is a string defining the Gluster server.
676       The format of this string is documented in "guestfs_add_drive_opts".
677
678       Note that gluster usually requires the client process (ie. libguestfs)
679       to run as root and will give unfathomable errors if it is not (eg. "No
680       data available").
681
682       ISCSI
683
684       Libguestfs can access iSCSI disks remotely.
685
686       To do this, set the optional "protocol" and "server" parameters like
687       this:
688
689        char **server = { "iscsi.example.org:3000", NULL };
690        guestfs_add_drive_opts (g, "target-iqn-name/lun",
691                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
692                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "iscsi",
693                                GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
694                                -1);
695
696       The "server" parameter is a list which must have a single element.  The
697       single element is a string defining the iSCSI server.  The format of
698       this string is documented in "guestfs_add_drive_opts".
699
700       NETWORK BLOCK DEVICE
701
702       Libguestfs can access Network Block Device (NBD) disks remotely.
703
704       To do this, set the optional "protocol" and "server" parameters of
705       "guestfs_add_drive_opts" like this:
706
707        char **server = { "nbd.example.org:3000", NULL };
708        guestfs_add_drive_opts (g, "" /* export name - see below */,
709                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
710                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
711                                GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
712                                -1);
713
714       Notes:
715
716       •   "server" is in fact a list of servers.  For NBD you must always
717           supply a list with a single element.  (Other remote protocols
718           require zero or more than one server, hence the requirement for
719           this parameter to be a list).
720
721       •   The "server" string is documented in "guestfs_add_drive_opts".  To
722           connect to a local qemu-nbd instance over a Unix domain socket, use
723           "unix:/path/to/socket".
724
725       •   The "filename" parameter is the NBD export name.  Use an empty
726           string to mean the default export.  Many NBD servers, including
727           qemu-nbd, do not support export names.
728
729       •   If using qemu-nbd as your server, you should always specify the
730           "-t" option.  The reason is that libguestfs may open several
731           connections to the server.
732
733       •   The libvirt backend requires that you set the "format" parameter of
734           "guestfs_add_drive_opts" accurately when you use writable NBD
735           disks.
736
737       •   The libvirt backend has a bug that stops Unix domain socket
738           connections from working:
739           https://bugzilla.redhat.com/show_bug.cgi?id=922888
740
741       •   The direct backend does not support readonly connections because of
742           a bug in qemu: https://bugs.launchpad.net/qemu/+bug/1155677
743
744       SHEEPDOG
745
746       Libguestfs can access Sheepdog disks.
747
748       To do this, set the optional "protocol" and "server" parameters of
749       "guestfs_add_drive_opts" like this:
750
751        char **servers = { /* optional servers ... */ NULL };
752        guestfs_add_drive_opts (g, "volume",
753                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
754                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "sheepdog",
755                                GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
756                                -1);
757
758       The optional list of "servers" may be zero or more server addresses
759       ("hostname:port").  The format of the server strings is documented in
760       "guestfs_add_drive_opts".
761
762       SSH
763
764       Libguestfs can access disks over a Secure Shell (SSH) connection.
765
766       To do this, set the "protocol" and "server" and (optionally) "username"
767       parameters of "guestfs_add_drive_opts" like this:
768
769        char **server = { "remote.example.com", NULL };
770        guestfs_add_drive_opts (g, "/path/to/disk.img",
771                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
772                                GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "ssh",
773                                GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
774                                GUESTFS_ADD_DRIVE_OPTS_USERNAME, "remoteuser",
775                                -1);
776
777       The format of the server string is documented in
778       "guestfs_add_drive_opts".
779
780   INSPECTION
781       Libguestfs has APIs for inspecting an unknown disk image to find out if
782       it contains operating systems, an install CD or a live CD.
783
784       Add all disks belonging to the unknown virtual machine and call
785       "guestfs_launch" in the usual way.
786
787       Then call "guestfs_inspect_os".  This function uses other libguestfs
788       calls and certain heuristics, and returns a list of operating systems
789       that were found.  An empty list means none were found.  A single
790       element is the root filesystem of the operating system.  For dual- or
791       multi-boot guests, multiple roots can be returned, each one
792       corresponding to a separate operating system.  (Multi-boot virtual
793       machines are extremely rare in the world of virtualization, but since
794       this scenario can happen, we have built libguestfs to deal with it.)
795
796       For each root, you can then call various "guestfs_inspect_get_*"
797       functions to get additional details about that operating system.  For
798       example, call "guestfs_inspect_get_type" to return the string "windows"
799       or "linux" for Windows and Linux-based operating systems respectively.
800
801       Un*x-like and Linux-based operating systems usually consist of several
802       filesystems which are mounted at boot time (for example, a separate
803       boot partition mounted on /boot).  The inspection rules are able to
804       detect how filesystems correspond to mount points.  Call
805       "guestfs_inspect_get_mountpoints" to get this mapping.  It might return
806       a hash table like this example:
807
808        /boot => /dev/sda1
809        /     => /dev/vg_guest/lv_root
810        /usr  => /dev/vg_guest/lv_usr
811
812       The caller can then make calls to "guestfs_mount" to mount the
813       filesystems as suggested.
814
815       Be careful to mount filesystems in the right order (eg. / before /usr).
816       Sorting the keys of the hash by length, shortest first, should work.
817
818       Inspection currently only works for some common operating systems.
819       Contributors are welcome to send patches for other operating systems
820       that we currently cannot detect.
821
822       Encrypted disks must be opened before inspection.  See "ENCRYPTED
823       DISKS" for more details.  The "guestfs_inspect_os" function just
824       ignores any encrypted devices.
825
826       A note on the implementation: The call "guestfs_inspect_os" performs
827       inspection and caches the results in the guest handle.  Subsequent
828       calls to "guestfs_inspect_get_*" return this cached information, but do
829       not re-read the disks.  If you change the content of the guest disks,
830       you can redo inspection by calling "guestfs_inspect_os" again.
831       ("guestfs_inspect_list_applications2" works a little differently from
832       the other calls and does read the disks.  See documentation for that
833       function for details).
834
835       INSPECTING INSTALL DISKS
836
837       Libguestfs (since 1.9.4) can detect some install disks, install CDs,
838       live CDs and more.
839
840       Further information is available about the operating system that can be
841       installed using the regular inspection APIs like
842       "guestfs_inspect_get_product_name", "guestfs_inspect_get_major_version"
843       etc.
844
845   SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
846       Libguestfs can mount NTFS partitions.  It does this using the
847       http://www.ntfs-3g.org/ driver.
848
849       DRIVE LETTERS AND PATHS
850
851       DOS and Windows still use drive letters, and the filesystems are always
852       treated as case insensitive by Windows itself, and therefore you might
853       find a Windows configuration file referring to a path like
854       "c:\windows\system32".  When the filesystem is mounted in libguestfs,
855       that directory might be referred to as /WINDOWS/System32.
856
857       Drive letter mappings can be found using inspection (see "INSPECTION"
858       and "guestfs_inspect_get_drive_mappings")
859
860       Dealing with separator characters (backslash vs forward slash) is
861       outside the scope of libguestfs, but usually a simple character
862       replacement will work.
863
864       To resolve the case insensitivity of paths, call
865       "guestfs_case_sensitive_path".
866
867       LONG FILENAMES ON NTFS
868
869       NTFS supports filenames up to 255 characters long.  "Character" means a
870       2 byte UTF-16 codepoint which can encode the most common Unicode
871       codepoints.
872
873       Most Linux filesystems support filenames up to 255 bytes.  This means
874       you may get an error:
875
876        File name too long
877
878       when you copy a file from NTFS to a Linux filesystem if the name, when
879       reencoded as UTF-8, would exceed 255 bytes in length.
880
881       This will most often happen when using non-ASCII names that are longer
882       than ~127 characters (eg. Greek, Cyrillic) or longer than ~85
883       characters (Asian languages).
884
885       A workaround is not to try to store such long filenames on Linux native
886       filesystems.  Since the tar(1) format can store unlimited length
887       filenames, keep the files in a tarball.
888
889       ACCESSING THE WINDOWS REGISTRY
890
891       Libguestfs also provides some help for decoding Windows Registry "hive"
892       files, through a separate C library called hivex(3).
893
894       Before libguestfs 1.19.35 you had to download the hive file, operate on
895       it locally using hivex, and upload it again.  Since this version, we
896       have included the major hivex APIs directly in the libguestfs API (see
897       "guestfs_hivex_open").  This means that if you have opened a Windows
898       guest, you can read and write the registry directly.
899
900       See also virt-win-reg(1).
901
902       SYMLINKS ON NTFS-3G FILESYSTEMS
903
904       Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
905       provide something which looks like a Linux symlink.  The way it tries
906       to do the rewriting is described here:
907
908       http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
909
910       The essential problem is that ntfs-3g simply does not have enough
911       information to do a correct job.  NTFS links can contain drive letters
912       and references to external device GUIDs that ntfs-3g has no way of
913       resolving.  It is almost certainly the case that libguestfs callers
914       should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
915       NTFS volumes).
916
917       Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
918       "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
919       attribute, and read the raw reparse data from that (you can find the
920       format documented in various places around the web).
921
922       EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
923
924       There are other useful extended attributes that can be read from
925       ntfs-3g filesystems (using "guestfs_getxattr").  See:
926
927       http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
928
929       WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP
930
931       Windows guests which have been hibernated (instead of fully shut down)
932       cannot be mounted.  This is a limitation of ntfs-3g.  You will see an
933       error like this:
934
935        The disk contains an unclean file system (0, 0).
936        Metadata kept in Windows cache, refused to mount.
937        Failed to mount '/dev/sda2': Operation not permitted
938        The NTFS partition is in an unsafe state. Please resume
939        and shutdown Windows fully (no hibernation or fast
940        restarting), or mount the volume read-only with the
941        'ro' mount option.
942
943       In Windows 8, the shutdown button does not shut down the guest at all.
944       Instead it usually hibernates the guest.  This is known as "fast
945       startup".
946
947       Some suggested workarounds are:
948
949       •   Mount read-only (eg. "guestfs_mount_ro").
950
951       •   On Windows 8, turn off fast startup.  It is in the Control Panel →
952           Power Options → Choose what the power buttons do → Change settings
953           that are currently unavailable → Turn on fast startup.
954
955       •   On Windows 7 and earlier, shut the guest off properly instead of
956           hibernating it.
957
958   RESIZE2FS ERRORS
959       The "guestfs_resize2fs", "guestfs_resize2fs_size" and
960       "guestfs_resize2fs_M" calls are used to resize ext2/3/4 filesystems.
961
962       The underlying program (resize2fs(8)) requires that the filesystem is
963       clean and recently fsck'd before you can resize it.  Also, if the
964       resize operation fails for some reason, then you had to call fsck the
965       filesystem again to fix it.
966
967       In libguestfs "lt" 1.17.14, you usually had to call "guestfs_e2fsck_f"
968       before the resize.  However, in "ge" 1.17.14, e2fsck(8) is called
969       automatically before the resize, so you no longer need to do this.
970
971       The resize2fs(8) program can still fail, in which case it prints an
972       error message similar to:
973
974        Please run 'e2fsck -fy <device>' to fix the filesystem
975        after the aborted resize operation.
976
977       You can do this by calling "guestfs_e2fsck" with the "forceall" option.
978       However in the context of disk images, it is usually better to avoid
979       this situation, eg. by rolling back to an earlier snapshot, or by
980       copying and resizing and on failure going back to the original.
981
982   USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
983       Although we don’t want to discourage you from using the C API, we will
984       mention here that the same API is also available in other languages.
985
986       The API is broadly identical in all supported languages.  This means
987       that the C call "guestfs_add_drive_ro(g,file)" is
988       "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
989       and "g#add_drive_ro file" in OCaml.  In other words, a straightforward,
990       predictable isomorphism between each language.
991
992       Error messages are automatically transformed into exceptions if the
993       language supports it.
994
995       We don’t try to "object orientify" parts of the API in OO languages,
996       although contributors are welcome to write higher level APIs above what
997       we provide in their favourite languages if they wish.
998
999       C++ You can use the guestfs.h header file from C++ programs.  The C++
1000           API is identical to the C API.  C++ classes and exceptions are not
1001           used.
1002
1003       C#  The C# bindings are highly experimental.  Please read the warnings
1004           at the top of csharp/Libguestfs.cs.
1005
1006       Erlang
1007           See guestfs-erlang(3).
1008
1009       GObject
1010           Experimental GObject bindings (with GObject Introspection support)
1011           are available.
1012
1013           See guestfs-gobject(3).
1014
1015       Go  See guestfs-golang(3).
1016
1017       Haskell
1018           This language binding is working but incomplete:
1019
1020           •   Functions with optional arguments are not bound.  Implementing
1021               optional arguments in Haskell seems to be very complex.
1022
1023           •   Events are not bound.
1024
1025           •   Functions with the following return types are not bound:
1026
1027               •   Any function returning a struct.
1028
1029               •   Any function returning a list of structs.
1030
1031               •   A few functions that return fixed length buffers
1032                   (specifically ones declared "RBufferOut" in the generator).
1033
1034               •   A tiny number of obscure functions that return constant
1035                   strings (specifically ones declared "RConstOptString" in
1036                   the generator).
1037
1038       Java
1039           Full documentation is contained in the Javadoc which is distributed
1040           with libguestfs.  For examples, see guestfs-java(3).
1041
1042       Lua See guestfs-lua(3).
1043
1044       OCaml
1045           See guestfs-ocaml(3).
1046
1047       Perl
1048           See guestfs-perl(3) and Sys::Guestfs(3).
1049
1050       PHP For documentation see "README-PHP" supplied with libguestfs sources
1051           or in the php-libguestfs package for your distribution.
1052
1053           The PHP binding only works correctly on 64 bit machines.
1054
1055       Python
1056           See guestfs-python(3).
1057
1058       Ruby
1059           See guestfs-ruby(3).
1060
1061           For JRuby, use the Java bindings.
1062
1063       shell scripts
1064           See guestfish(1).
1065
1066   LIBGUESTFS GOTCHAS
1067       http://en.wikipedia.org/wiki/Gotcha_(programming): "A feature of a
1068       system [...] that works in the way it is documented but is
1069       counterintuitive and almost invites mistakes."
1070
1071       Since we developed libguestfs and the associated tools, there are
1072       several things we would have designed differently, but are now stuck
1073       with for backwards compatibility or other reasons.  If there is ever a
1074       libguestfs 2.0 release, you can expect these to change.  Beware of
1075       them.
1076
1077       Read-only should be the default.
1078           In guestfish(3), --ro should be the default, and you should have to
1079           specify --rw if you want to make changes to the image.
1080
1081           This would reduce the potential to corrupt live VM images.
1082
1083           Note that many filesystems change the disk when you just mount and
1084           unmount, even if you didn't perform any writes.  You need to use
1085           "guestfs_add_drive_ro" to guarantee that the disk is not changed.
1086
1087       guestfish command line is hard to use.
1088           guestfish disk.img doesn't do what people expect (open disk.img for
1089           examination).  It tries to run a guestfish command disk.img which
1090           doesn't exist, so it fails.  In earlier versions of guestfish the
1091           error message was also unintuitive, but we have corrected this
1092           since.  Like the Bourne shell, we should have used "guestfish -c
1093           command" to run commands.
1094
1095       guestfish megabyte modifiers don’t work right on all commands
1096           In recent guestfish you can use "1M" to mean 1 megabyte (and
1097           similarly for other modifiers).  What guestfish actually does is to
1098           multiply the number part by the modifier part and pass the result
1099           to the C API.  However this doesn't work for a few APIs which
1100           aren't expecting bytes, but are already expecting some other unit
1101           (eg. megabytes).
1102
1103           The most common is "guestfs_lvcreate".  The guestfish command:
1104
1105            lvcreate LV VG 100M
1106
1107           does not do what you might expect.  Instead because
1108           "guestfs_lvcreate" is already expecting megabytes, this tries to
1109           create a 100 terabyte (100 megabytes * megabytes) logical volume.
1110           The error message you get from this is also a little obscure.
1111
1112           This could be fixed in the generator by specially marking
1113           parameters and return values which take bytes or other units.
1114
1115       Ambiguity between devices and paths
1116           There is a subtle ambiguity in the API between a device name (eg.
1117           /dev/sdb2) and a similar pathname.  A file might just happen to be
1118           called "sdb2" in the directory /dev (consider some non-Unix VM
1119           image).
1120
1121           In the current API we usually resolve this ambiguity by having two
1122           separate calls, for example "guestfs_checksum" and
1123           "guestfs_checksum_device".  Some API calls are ambiguous and
1124           (incorrectly) resolve the problem by detecting if the path supplied
1125           begins with /dev/.
1126
1127           To avoid both the ambiguity and the need to duplicate some calls,
1128           we could make paths/devices into structured names.  One way to do
1129           this would be to use a notation like grub ("hd(0,0)"), although
1130           nobody really likes this aspect of grub.  Another way would be to
1131           use a structured type, equivalent to this OCaml type:
1132
1133            type path = Path of string | Device of int | Partition of int * int
1134
1135           which would allow you to pass arguments like:
1136
1137            Path "/foo/bar"
1138            Device 1            (* /dev/sdb, or perhaps /dev/sda *)
1139            Partition (1, 2)    (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
1140            Path "/dev/sdb2"    (* not a device *)
1141
1142           As you can see there are still problems to resolve even with this
1143           representation.  Also consider how it might work in guestfish.
1144
1145   KEYS AND PASSPHRASES
1146       Certain libguestfs calls take a parameter that contains sensitive key
1147       material, passed in as a C string.
1148
1149       In the future we would hope to change the libguestfs implementation so
1150       that keys are mlock(2)-ed into physical RAM, and thus can never end up
1151       in swap.  However this is not done at the moment, because of the
1152       complexity of such an implementation.
1153
1154       Therefore you should be aware that any key parameter you pass to
1155       libguestfs might end up being written out to the swap partition.  If
1156       this is a concern, scrub the swap partition or don't use libguestfs on
1157       encrypted devices.
1158
1159   MULTIPLE HANDLES AND MULTIPLE THREADS
1160       All high-level libguestfs actions are synchronous.  If you want to use
1161       libguestfs asynchronously then you must create a thread.
1162
1163       Threads in libguestfs  1.38
1164
1165       In libguestfs ≥ 1.38, each handle ("guestfs_h") contains a lock which
1166       is acquired automatically when you call a libguestfs function.  The
1167       practical effect of this is you can call libguestfs functions with the
1168       same handle from multiple threads without needing to do any locking.
1169
1170       Also in libguestfs ≥ 1.38, the last error on the handle
1171       ("guestfs_last_error", "guestfs_last_errno") is stored in thread-local
1172       storage, so it is safe to write code like:
1173
1174        if (guestfs_add_drive_ro (g, drive) == -1)
1175          fprintf (stderr, "error was: %s\n", guestfs_last_error (g));
1176
1177       even when other threads may be concurrently using the same handle "g".
1178
1179       Threads in libguestfs < 1.38
1180
1181       In libguestfs < 1.38, you must use the handle only from a single
1182       thread.  Either use the handle exclusively from one thread, or provide
1183       your own mutex so that two threads cannot issue calls on the same
1184       handle at the same time.  Even apparently innocent functions like
1185       "guestfs_get_trace" are not safe to be called from multiple threads
1186       without a mutex in libguestfs < 1.38.
1187
1188       Use "guestfs_set_identifier" to make it simpler to identify threads in
1189       trace output.
1190
1191   PATH
1192       Libguestfs needs a supermin appliance, which it finds by looking along
1193       an internal path.
1194
1195       By default it looks for these in the directory "$libdir/guestfs" (eg.
1196       /usr/local/lib/guestfs or /usr/lib64/guestfs).
1197
1198       Use "guestfs_set_path" or set the environment variable
1199       "LIBGUESTFS_PATH" to change the directories that libguestfs will search
1200       in.  The value is a colon-separated list of paths.  The current
1201       directory is not searched unless the path contains an empty element or
1202       ".".  For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
1203       current directory and then /usr/lib/guestfs.
1204
1205   QEMU WRAPPERS
1206       If you want to compile your own qemu, run qemu from a non-standard
1207       location, or pass extra arguments to qemu, then you can write a shell-
1208       script wrapper around qemu.
1209
1210       There is one important rule to remember: you must "exec qemu" as the
1211       last command in the shell script (so that qemu replaces the shell and
1212       becomes the direct child of the libguestfs-using program).  If you
1213       don't do this, then the qemu process won't be cleaned up correctly.
1214
1215       Here is an example of a wrapper, where I have built my own copy of qemu
1216       from source:
1217
1218        #!/bin/sh -
1219        qemudir=/home/rjones/d/qemu
1220        exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1221
1222       Save this script as /tmp/qemu.wrapper (or wherever), "chmod +x", and
1223       then use it by setting the LIBGUESTFS_HV environment variable.  For
1224       example:
1225
1226        LIBGUESTFS_HV=/tmp/qemu.wrapper guestfish
1227
1228       Note that libguestfs also calls qemu with the -help and -version
1229       options in order to determine features.
1230
1231       Wrappers can also be used to edit the options passed to qemu.  In the
1232       following example, the "-machine ..." option ("-machine" and the
1233       following argument) are removed from the command line and replaced with
1234       "-machine pc,accel=tcg".  The while loop iterates over the options
1235       until it finds the right one to remove, putting the remaining options
1236       into the "args" array.
1237
1238        #!/bin/bash -
1239
1240        i=0
1241        while [ $# -gt 0 ]; do
1242            case "$1" in
1243            -machine)
1244                shift 2;;
1245            *)
1246                args[i]="$1"
1247                (( i++ ))
1248                shift ;;
1249            esac
1250        done
1251
1252        exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
1253
1254   BACKEND
1255       The backend (previously known as the "attach method") controls how
1256       libguestfs creates and/or connects to the backend daemon, eg. by
1257       starting qemu directly, or using libvirt to manage an appliance,
1258       running User-Mode Linux, or connecting to an already running daemon.
1259
1260       You can set the backend by calling "guestfs_set_backend", or by setting
1261       the environment variable "LIBGUESTFS_BACKEND".
1262
1263       Possible backends are described below:
1264
1265       "direct"
1266       "appliance"
1267           Run qemu directly to launch an appliance.
1268
1269           "direct" and "appliance" are synonyms.
1270
1271           This is the ordinary method and normally the default, but see the
1272           note below.
1273
1274       "libvirt"
1275       "libvirt:null"
1276       "libvirt:URI"
1277           Use libvirt to launch and manage the appliance.
1278
1279           "libvirt" causes libguestfs to choose a suitable URI for creating
1280           session guests.  If using the libvirt backend, you almost always
1281           should use this.
1282
1283           "libvirt:null" causes libguestfs to use the "NULL" connection URI,
1284           which causes libvirt to try to guess what the user meant.  You
1285           probably don't want to use this.
1286
1287           "libvirt:URI" uses URI as the libvirt connection URI (see
1288           http://libvirt.org/uri.html).  The typical libvirt backend with a
1289           URI would be "libvirt:qemu:///session"
1290
1291           The libvirt backend supports more features, including hotplugging
1292           (see "HOTPLUGGING") and sVirt.
1293
1294       "uml"
1295           Run the User-Mode Linux kernel.  The location of the kernel is set
1296           using $LIBGUESTFS_HV or using the "guestfs_set_qemu" API (note that
1297           qemu is not involved, we just reuse the same variable in the handle
1298           for convenience).
1299
1300           User-Mode Linux can be much faster, simpler and more lightweight
1301           than using a full-blown virtual machine, but it also has some
1302           shortcomings.  See "USER-MODE LINUX BACKEND" below.
1303
1304       "unix:path"
1305           Connect to the Unix domain socket path.
1306
1307           This method lets you connect to an existing daemon or (using
1308           virtio-serial) to a live guest.  For more information, see
1309           "ATTACHING TO RUNNING DAEMONS".
1310
1311       "direct" is usually the default backend.  However since libguestfs ≥
1312       1.19.24, libguestfs can be built with a different default by doing:
1313
1314        ./configure --with-default-backend=...
1315
1316       To find out if libguestfs was compiled with a different default
1317       backend, do:
1318
1319        unset LIBGUESTFS_BACKEND
1320        guestfish get-backend
1321
1322   BACKEND SETTINGS
1323       Each backend can be configured by passing a list of strings.  You can
1324       either call "guestfs_set_backend_settings" with a list of strings, or
1325       set the "LIBGUESTFS_BACKEND_SETTINGS" environment variable to a colon-
1326       separated list of strings (before creating the handle).
1327
1328       force_tcg
1329
1330       Using:
1331
1332        export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
1333
1334       will force the direct and libvirt backends to use TCG (software
1335       emulation) instead of KVM (hardware accelerated virtualization).
1336
1337       force_kvm
1338
1339       Using:
1340
1341        export LIBGUESTFS_BACKEND_SETTINGS=force_kvm
1342
1343       will force the direct and libvirt backends to use KVM (hardware
1344       accelerated virtualization) instead of TCG (software emulation).
1345
1346       gdb
1347
1348       The direct backend supports:
1349
1350        export LIBGUESTFS_BACKEND_SETTINGS=gdb
1351
1352       When this is set, qemu will not start running the appliance
1353       immediately.  It will wait for you to connect to it using gdb:
1354
1355        $ gdb
1356        (gdb) symbol-file /path/to/vmlinux
1357        (gdb) target remote tcp::1234
1358        (gdb) cont
1359
1360       You can then debug the appliance kernel, which is useful to debug boot
1361       failures (especially ones where there are no debug messages printed -
1362       tip: look in the kernel "log_buf").
1363
1364       On Fedora, install "kernel-debuginfo" for the "vmlinux" file
1365       (containing symbols).  Make sure the symbols precisely match the kernel
1366       being used.
1367
1368   ATTACHING TO RUNNING DAEMONS
1369       Note (1): This is highly experimental and has a tendency to eat babies.
1370       Use with caution.
1371
1372       Note (2): This section explains how to attach to a running daemon from
1373       a low level perspective.  For most users, simply using virt tools such
1374       as guestfish(1) with the --live option will "just work".
1375
1376       Using guestfs_set_backend
1377
1378       By calling "guestfs_set_backend" you can change how the library
1379       connects to the "guestfsd" daemon in "guestfs_launch" (read
1380       "ARCHITECTURE" in guestfs-internals(1) for some background).
1381
1382       The normal backend is "direct", where a small appliance is created
1383       containing the daemon, and then the library connects to this.
1384       "libvirt" or "libvirt:URI" are alternatives that use libvirt to start
1385       the appliance.
1386
1387       Setting the backend to "unix:path" (where path is the path of a Unix
1388       domain socket) causes "guestfs_launch" to connect to an existing daemon
1389       over the Unix domain socket.
1390
1391       The normal use for this is to connect to a running virtual machine that
1392       contains a "guestfsd" daemon, and send commands so you can read and
1393       write files inside the live virtual machine.
1394
1395       Using guestfs_add_domain with live flag
1396
1397       "guestfs_add_domain" provides some help for getting the correct
1398       backend.  If you pass the "live" option to this function, then (if the
1399       virtual machine is running) it will examine the libvirt XML looking for
1400       a virtio-serial channel to connect to:
1401
1402        <domain>
1403          ...
1404          <devices>
1405            ...
1406            <channel type='unix'>
1407              <source mode='bind' path='/path/to/socket'/>
1408              <target type='virtio' name='org.libguestfs.channel.0'/>
1409            </channel>
1410            ...
1411          </devices>
1412        </domain>
1413
1414       "guestfs_add_domain" extracts /path/to/socket and sets the backend to
1415       "unix:/path/to/socket".
1416
1417       Some of the libguestfs tools (including guestfish) support a --live
1418       option which is passed through to "guestfs_add_domain" thus allowing
1419       you to attach to and modify live virtual machines.
1420
1421       The virtual machine needs to have been set up beforehand so that it has
1422       the virtio-serial channel and so that guestfsd is running inside it.
1423
1424   USER-MODE LINUX BACKEND
1425       Setting the following environment variables (or the equivalent in the
1426       API) selects the User-Mode Linux backend:
1427
1428        export LIBGUESTFS_BACKEND=uml
1429        export LIBGUESTFS_HV=/path/to/vmlinux
1430
1431       "vmlinux" (or it may be called "linux") is the Linux binary, compiled
1432       to run as a userspace process.  Note that we reuse the qemu variable in
1433       the handle for convenience; qemu is not involved.
1434
1435       User-Mode Linux can be faster and more lightweight than running a full-
1436       blown virtual machine as the backend (especially if you are already
1437       running libguestfs in a virtual machine or cloud instance), but it also
1438       has some shortcomings compared to the usual qemu/KVM-based backend.
1439
1440       BUILDING USER-MODE LINUX FROM SOURCE
1441
1442       Your Linux distro may provide UML in which case you can ignore this
1443       section.
1444
1445       These instructions are adapted from:
1446       http://user-mode-linux.sourceforge.net/source.html
1447
1448       1. Check out Linux sources
1449           Clone the Linux git repository or download the Linux source
1450           tarball.
1451
1452       2. Configure the kernel
1453           Note: All ‘make’ commands must have "ARCH=um" added.
1454
1455            make menuconfig ARCH=um
1456
1457           Make sure any filesystem drivers that you need are compiled into
1458           the kernel.
1459
1460           Currently, it needs a large amount of extra work to get modules
1461           working.  It’s recommended that you disable module support in the
1462           kernel configuration, which will cause everything to be compiled
1463           into the image.
1464
1465       3. Build the kernel
1466            make ARCH=um
1467
1468           This will leave a file called "linux" or "vmlinux" in the top-level
1469           directory.  This is the UML kernel.  You should set "LIBGUESTFS_HV"
1470           to point to this file.
1471
1472       USER-MODE LINUX DIFFERENCES FROM KVM
1473
1474       UML only supports raw-format images
1475           Only plain raw-format images will work.  No qcow2, no backing
1476           files.
1477
1478       UML does not support any remote drives
1479           No NBD, etc.
1480
1481       UML only works on ix86 and x86-64
1482       UML is experimental
1483           In particular, support for UML in libguestfs depends on support for
1484           UML in the upstream kernel.  If UML was ever removed from the
1485           upstream Linux kernel, then we might remove it from libguestfs too.
1486
1487   ABI GUARANTEE
1488       We guarantee the libguestfs ABI (binary interface), for public, high-
1489       level actions as outlined in this section.  Although we will deprecate
1490       some actions, for example if they get replaced by newer calls, we will
1491       keep the old actions forever.  This allows you the developer to program
1492       in confidence against the libguestfs API.
1493
1494   BLOCK DEVICE NAMING
1495       Libguestfs defines /dev/sd* as the standard naming scheme for devices
1496       passed to API calls.  So /dev/sda means "the first device added by
1497       "guestfs_add_drive_opts"", and /dev/sdb3 means "the third partition on
1498       the second device".
1499
1500       Internally device names are sometimes translated, but this should not
1501       be visible at the API level.
1502
1503       DISK LABELS
1504
1505       In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1506       using the optional "label" parameter to "guestfs_add_drive_opts".
1507       (Note that disk labels are different from and not related to filesystem
1508       labels).
1509
1510       Not all versions of libguestfs support setting a disk label, and when
1511       it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1512
1513       When you add a disk with a label, it can either be addressed using
1514       /dev/sd*, or using /dev/disk/guestfs/label.  Partitions on the disk can
1515       be addressed using /dev/disk/guestfs/labelpartnum.
1516
1517       Listing devices ("guestfs_list_devices") and partitions
1518       ("guestfs_list_partitions") returns the block device names.  However
1519       you can use "guestfs_list_disk_labels" to map disk labels to block
1520       device and partition names.
1521
1522   NULL DISKS
1523       When adding a disk using, eg., "guestfs_add_drive", you can set the
1524       filename to "/dev/null".  This string is treated specially by
1525       libguestfs, causing it to add a "null disk".
1526
1527       A null disk has the following properties:
1528
1529       •   A null disk will appear as a normal device, eg. in calls to
1530           "guestfs_list_devices".
1531
1532       •   You may add "/dev/null" multiple times.
1533
1534       •   You should not try to access a null disk in any way.  For example,
1535           you shouldn't try to read it or mount it.
1536
1537       Null disks are used for three main purposes:
1538
1539       1.  Performance testing of libguestfs (see guestfs-performance(1)).
1540
1541       2.  The internal test suite.
1542
1543       3.  If you want to use libguestfs APIs that don’t refer to disks, since
1544           libguestfs requires that at least one disk is added, you should add
1545           a null disk.
1546
1547           For example, to test if a feature is available, use code like this:
1548
1549            guestfs_h *g;
1550            char **groups = [ "btrfs", NULL ];
1551
1552            g = guestfs_create ();
1553            guestfs_add_drive (g, "/dev/null");
1554            guestfs_launch (g);
1555            if (guestfs_available (g, groups) == 0) {
1556              // group(s) are available
1557            } else {
1558              // group(s) are not available
1559            }
1560            guestfs_close (g);
1561
1562   DISK IMAGE FORMATS
1563       Virtual disks come in a variety of formats.  Some common formats are
1564       listed below.
1565
1566       Note that libguestfs itself is not responsible for handling the disk
1567       format: this is done using qemu(1).  If support for a particular format
1568       is missing or broken, this has to be fixed in qemu.
1569
1570       COMMON VIRTUAL DISK IMAGE FORMATS
1571
1572       raw Raw format is simply a dump of the sequential bytes of the virtual
1573           hard disk.  There is no header, container, compression or
1574           processing of any sort.
1575
1576           Since raw format requires no translation to read or write, it is
1577           both fast and very well supported by qemu and all other
1578           hypervisors.  You can consider it to be a universal format that any
1579           hypervisor can access.
1580
1581           Raw format files are not compressed and so take up the full space
1582           of the original disk image even when they are empty.  A variation
1583           (on Linux/Unix at least) is to not store ranges of all-zero bytes
1584           by storing the file as a sparse file.  This "variant format" is
1585           sometimes called raw sparse.  Many utilities, including
1586           virt-sparsify(1), can make raw disk images sparse.
1587
1588       qcow2
1589           Qcow2 is the native disk image format used by qemu.  Internally it
1590           uses a two-level directory structure so that only blocks containing
1591           data are stored in the file.  It also has many other features such
1592           as compression, snapshots and backing files.
1593
1594           There are at least two distinct variants of this format, although
1595           qemu (and hence libguestfs) handles both transparently to the user.
1596
1597       vmdk
1598           VMDK is VMware’s native disk image format.  There are many
1599           variations.  Modern qemu (hence libguestfs) supports most
1600           variations, but you should be aware that older versions of qemu had
1601           some very bad data-corrupting bugs in this area.
1602
1603           Note that VMware ESX exposes files with the name guest-flat.vmdk.
1604           These are not VMDK.  They are raw format files which happen to have
1605           a ".vmdk" extension.
1606
1607       vdi VDI is VirtualBox’s native disk image format.  Qemu (hence
1608           libguestfs) has generally good support for this.
1609
1610       vpc
1611       vhd VPC (old) and VHD (modern) are the native disk image format of
1612           Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1613
1614       Obsolete formats
1615           The following formats are obsolete and should not be used: qcow
1616           (aka qcow1), cow, bochs.
1617
1618       DETECTING THE FORMAT OF A DISK IMAGE
1619
1620       Firstly note there is a security issue with auto-detecting the format
1621       of a disk image.  It may or may not apply in your use case.  Read
1622       "CVE-2010-3851" below.
1623
1624       Libguestfs offers an API to get the format of a disk image
1625       ("guestfs_disk_format"), and it is safest to use this.
1626
1627       Don’t be tempted to try parsing the text / human-readable output of
1628       "qemu-img" since it cannot be parsed reliably and securely.  Also do
1629       not use the "file" command since the output of that changes over time.
1630

CONNECTION MANAGEMENT

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

ERROR HANDLING

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

API CALLS

1915   guestfs_acl_delete_def_file
1916        int
1917        guestfs_acl_delete_def_file (guestfs_h *g,
1918                                     const char *dir);
1919
1920       This function deletes the default POSIX Access Control List (ACL)
1921       attached to directory "dir".
1922
1923       This function returns 0 on success or -1 on error.
1924
1925       This function depends on the feature "acl".  See also
1926       "guestfs_feature_available".
1927
1928       (Added in 1.19.63)
1929
1930   guestfs_acl_get_file
1931        char *
1932        guestfs_acl_get_file (guestfs_h *g,
1933                              const char *path,
1934                              const char *acltype);
1935
1936       This function returns the POSIX Access Control List (ACL) attached to
1937       "path".  The ACL is returned in "long text form" (see acl(5)).
1938
1939       The "acltype" parameter may be:
1940
1941       "access"
1942           Return the ordinary (access) ACL for any file, directory or other
1943           filesystem object.
1944
1945       "default"
1946           Return the default ACL.  Normally this only makes sense if "path"
1947           is a directory.
1948
1949       This function returns a string, or NULL on error.  The caller must free
1950       the returned string after use.
1951
1952       This function depends on the feature "acl".  See also
1953       "guestfs_feature_available".
1954
1955       (Added in 1.19.63)
1956
1957   guestfs_acl_set_file
1958        int
1959        guestfs_acl_set_file (guestfs_h *g,
1960                              const char *path,
1961                              const char *acltype,
1962                              const char *acl);
1963
1964       This function sets the POSIX Access Control List (ACL) attached to
1965       "path".
1966
1967       The "acltype" parameter may be:
1968
1969       "access"
1970           Set the ordinary (access) ACL for any file, directory or other
1971           filesystem object.
1972
1973       "default"
1974           Set the default ACL.  Normally this only makes sense if "path" is a
1975           directory.
1976
1977       The "acl" parameter is the new ACL in either "long text form" or "short
1978       text form" (see acl(5)).  The new ACL completely replaces any previous
1979       ACL on the file.  The ACL must contain the full Unix permissions (eg.
1980       "u::rwx,g::rx,o::rx").
1981
1982       If you are specifying individual users or groups, then the mask field
1983       is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1984       "g:ID:..." field(s).  A full ACL string might therefore look like this:
1985
1986        u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1987        \ Unix permissions / \mask/ \      ACL        /
1988
1989       You should use numeric UIDs and GIDs.  To map usernames and groupnames
1990       to the correct numeric ID in the context of the guest, use the Augeas
1991       functions (see "guestfs_aug_init").
1992
1993       This function returns 0 on success or -1 on error.
1994
1995       This function depends on the feature "acl".  See also
1996       "guestfs_feature_available".
1997
1998       (Added in 1.19.63)
1999
2000   guestfs_add_cdrom
2001        int
2002        guestfs_add_cdrom (guestfs_h *g,
2003                           const char *filename);
2004
2005       This function is deprecated.  In new code, use the
2006       "guestfs_add_drive_ro" call instead.
2007
2008       Deprecated functions will not be removed from the API, but the fact
2009       that they are deprecated indicates that there are problems with correct
2010       use of these functions.
2011
2012       This function adds a virtual CD-ROM disk image to the guest.
2013
2014       The image is added as read-only drive, so this function is equivalent
2015       of "guestfs_add_drive_ro".
2016
2017       This function returns 0 on success or -1 on error.
2018
2019       (Added in 0.3)
2020
2021   guestfs_add_domain
2022        int
2023        guestfs_add_domain (guestfs_h *g,
2024                            const char *dom,
2025                            ...);
2026
2027       You may supply a list of optional arguments to this call.  Use zero or
2028       more of the following pairs of parameters, and terminate the list with
2029       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2030
2031        GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
2032        GUESTFS_ADD_DOMAIN_READONLY, int readonly,
2033        GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
2034        GUESTFS_ADD_DOMAIN_LIVE, int live,
2035        GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
2036        GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
2037        GUESTFS_ADD_DOMAIN_CACHEMODE, const char *cachemode,
2038        GUESTFS_ADD_DOMAIN_DISCARD, const char *discard,
2039        GUESTFS_ADD_DOMAIN_COPYONREAD, int copyonread,
2040
2041       This function adds the disk(s) attached to the named libvirt domain
2042       "dom".  It works by connecting to libvirt, requesting the domain and
2043       domain XML from libvirt, parsing it for disks, and calling
2044       "guestfs_add_drive_opts" on each one.
2045
2046       The number of disks added is returned.  This operation is atomic: if an
2047       error is returned, then no disks are added.
2048
2049       This function does some minimal checks to make sure the libvirt domain
2050       is not running (unless "readonly" is true).  In a future version we
2051       will try to acquire the libvirt lock on each disk.
2052
2053       Disks must be accessible locally.  This often means that adding disks
2054       from a remote libvirt connection (see https://libvirt.org/remote.html)
2055       will fail unless those disks are accessible via the same device path
2056       locally too.
2057
2058       The optional "libvirturi" parameter sets the libvirt URI (see
2059       https://libvirt.org/uri.html).  If this is not set then we connect to
2060       the default libvirt URI (or one set through an environment variable,
2061       see the libvirt documentation for full details).
2062
2063       The optional "live" flag controls whether this call will try to connect
2064       to a running virtual machine "guestfsd" process if it sees a suitable
2065       <channel> element in the libvirt XML definition.  The default (if the
2066       flag is omitted) is never to try.  See "ATTACHING TO RUNNING DAEMONS"
2067       for more information.
2068
2069       If the "allowuuid" flag is true (default is false) then a UUID may be
2070       passed instead of the domain name.  The "dom" string is treated as a
2071       UUID first and looked up, and if that lookup fails then we treat "dom"
2072       as a name as usual.
2073
2074       The optional "readonlydisk" parameter controls what we do for disks
2075       which are marked <readonly/> in the libvirt XML.  Possible values are:
2076
2077       readonlydisk = "error"
2078           If "readonly" is false:
2079
2080           The whole call is aborted with an error if any disk with the
2081           <readonly/> flag is found.
2082
2083           If "readonly" is true:
2084
2085           Disks with the <readonly/> flag are added read-only.
2086
2087       readonlydisk = "read"
2088           If "readonly" is false:
2089
2090           Disks with the <readonly/> flag are added read-only.  Other disks
2091           are added read/write.
2092
2093           If "readonly" is true:
2094
2095           Disks with the <readonly/> flag are added read-only.
2096
2097       readonlydisk = "write" (default)
2098           If "readonly" is false:
2099
2100           Disks with the <readonly/> flag are added read/write.
2101
2102           If "readonly" is true:
2103
2104           Disks with the <readonly/> flag are added read-only.
2105
2106       readonlydisk = "ignore"
2107           If "readonly" is true or false:
2108
2109           Disks with the <readonly/> flag are skipped.
2110
2111       If present, the value of "logical_block_size" attribute of <blockio/>
2112       tag in libvirt XML will be passed as "blocksize" parameter to
2113       "guestfs_add_drive_opts".
2114
2115       The other optional parameters are passed directly through to
2116       "guestfs_add_drive_opts".
2117
2118       On error this function returns -1.
2119
2120       (Added in 1.7.4)
2121
2122   guestfs_add_domain_va
2123        int
2124        guestfs_add_domain_va (guestfs_h *g,
2125                               const char *dom,
2126                               va_list args);
2127
2128       This is the "va_list variant" of "guestfs_add_domain".
2129
2130       See "CALLS WITH OPTIONAL ARGUMENTS".
2131
2132   guestfs_add_domain_argv
2133        int
2134        guestfs_add_domain_argv (guestfs_h *g,
2135                                 const char *dom,
2136                                 const struct guestfs_add_domain_argv *optargs);
2137
2138       This is the "argv variant" of "guestfs_add_domain".
2139
2140       See "CALLS WITH OPTIONAL ARGUMENTS".
2141
2142   guestfs_add_drive
2143        int
2144        guestfs_add_drive (guestfs_h *g,
2145                           const char *filename);
2146
2147       This function is provided for backwards compatibility with earlier
2148       versions of libguestfs.  It simply calls "guestfs_add_drive_opts" with
2149       no optional arguments.
2150
2151       (Added in 0.3)
2152
2153   guestfs_add_drive_opts
2154        int
2155        guestfs_add_drive_opts (guestfs_h *g,
2156                                const char *filename,
2157                                ...);
2158
2159       You may supply a list of optional arguments to this call.  Use zero or
2160       more of the following pairs of parameters, and terminate the list with
2161       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2162
2163        GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2164        GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2165        GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2166        GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2167        GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2168        GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2169        GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2170        GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2171        GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2172        GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2173        GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2174        GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2175        GUESTFS_ADD_DRIVE_OPTS_BLOCKSIZE, int blocksize,
2176
2177       This function adds a disk image called filename to the handle.
2178       filename may be a regular host file or a host device.
2179
2180       When this function is called before "guestfs_launch" (the usual case)
2181       then the first time you call this function, the disk appears in the API
2182       as /dev/sda, the second time as /dev/sdb, and so on.
2183
2184       In libguestfs ≥ 1.20 you can also call this function after launch (with
2185       some restrictions).  This is called "hotplugging".  When hotplugging,
2186       you must specify a "label" so that the new disk gets a predictable
2187       name.  For more information see "HOTPLUGGING".
2188
2189       You don't necessarily need to be root when using libguestfs.  However
2190       you obviously do need sufficient permissions to access the filename for
2191       whatever operations you want to perform (ie. read access if you just
2192       want to read the image or write access if you want to modify the
2193       image).
2194
2195       This call checks that filename exists.
2196
2197       filename may be the special string "/dev/null".  See "NULL DISKS".
2198
2199       The optional arguments are:
2200
2201       "readonly"
2202           If true then the image is treated as read-only.  Writes are still
2203           allowed, but they are stored in a temporary snapshot overlay which
2204           is discarded at the end.  The disk that you add is not modified.
2205
2206       "format"
2207           This forces the image format.  If you omit this (or use
2208           "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2209           automatically detected.  Possible formats include "raw" and
2210           "qcow2".
2211
2212           Automatic detection of the format opens you up to a potential
2213           security hole when dealing with untrusted raw-format images.  See
2214           CVE-2010-3851 and RHBZ#642934.  Specifying the format closes this
2215           security hole.
2216
2217       "iface"
2218           This rarely-used option lets you emulate the behaviour of the
2219           deprecated "guestfs_add_drive_with_if" call (q.v.)
2220
2221       "name"
2222           The name the drive had in the original guest, e.g. /dev/sdb.  This
2223           is used as a hint to the guest inspection process if it is
2224           available.
2225
2226       "label"
2227           Give the disk a label.  The label should be a unique, short string
2228           using only ASCII characters "[a-zA-Z]".  As well as its usual name
2229           in the API (such as /dev/sda), the drive will also be named
2230           /dev/disk/guestfs/label.
2231
2232           See "DISK LABELS".
2233
2234       "protocol"
2235           The optional protocol argument can be used to select an alternate
2236           source protocol.
2237
2238           See also: "REMOTE STORAGE".
2239
2240           "protocol = "file""
2241               filename is interpreted as a local file or device.  This is the
2242               default if the optional protocol parameter is omitted.
2243
2244           "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
2245               Connect to a remote FTP, HTTP or TFTP server.  The "server"
2246               parameter must also be supplied - see below.
2247
2248               See also: "FTP, HTTP AND TFTP"
2249
2250           "protocol = "gluster""
2251               Connect to the GlusterFS server.  The "server" parameter must
2252               also be supplied - see below.
2253
2254               See also: "GLUSTER"
2255
2256           "protocol = "iscsi""
2257               Connect to the iSCSI server.  The "server" parameter must also
2258               be supplied - see below.  The "username" parameter may be
2259               supplied.  See below.  The "secret" parameter may be supplied.
2260               See below.
2261
2262               See also: "ISCSI".
2263
2264           "protocol = "nbd""
2265               Connect to the Network Block Device server.  The "server"
2266               parameter must also be supplied - see below.
2267
2268               See also: "NETWORK BLOCK DEVICE".
2269
2270           "protocol = "rbd""
2271               Connect to the Ceph (librbd/RBD) server.  The "server"
2272               parameter must also be supplied - see below.  The "username"
2273               parameter may be supplied.  See below.  The "secret" parameter
2274               may be supplied.  See below.
2275
2276               See also: "CEPH".
2277
2278           "protocol = "sheepdog""
2279               Connect to the Sheepdog server.  The "server" parameter may
2280               also be supplied - see below.
2281
2282               See also: "SHEEPDOG".
2283
2284           "protocol = "ssh""
2285               Connect to the Secure Shell (ssh) server.
2286
2287               The "server" parameter must be supplied.  The "username"
2288               parameter may be supplied.  See below.
2289
2290               See also: "SSH".
2291
2292       "server"
2293           For protocols which require access to a remote server, this is a
2294           list of server(s).
2295
2296            Protocol       Number of servers required
2297            --------       --------------------------
2298            file           List must be empty or param not used at all
2299            ftp|ftps|http|https|tftp  Exactly one
2300            gluster        Exactly one
2301            iscsi          Exactly one
2302            nbd            Exactly one
2303            rbd            Zero or more
2304            sheepdog       Zero or more
2305            ssh            Exactly one
2306
2307           Each list element is a string specifying a server.  The string must
2308           be in one of the following formats:
2309
2310            hostname
2311            hostname:port
2312            tcp:hostname
2313            tcp:hostname:port
2314            unix:/path/to/socket
2315
2316           If the port number is omitted, then the standard port number for
2317           the protocol is used (see /etc/services).
2318
2319       "username"
2320           For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
2321           "tftp" protocols, this specifies the remote username.
2322
2323           If not given, then the local username is used for "ssh", and no
2324           authentication is attempted for ceph.  But note this sometimes may
2325           give unexpected results, for example if using the libvirt backend
2326           and if the libvirt backend is configured to start the qemu
2327           appliance as a special user such as "qemu.qemu".  If in doubt,
2328           specify the remote username you want.
2329
2330       "secret"
2331           For the "rbd" protocol only, this specifies the ‘secret’ to use
2332           when connecting to the remote device.  It must be base64 encoded.
2333
2334           If not given, then a secret matching the given username will be
2335           looked up in the default keychain locations, or if no username is
2336           given, then no authentication will be used.
2337
2338       "cachemode"
2339           Choose whether or not libguestfs will obey sync operations (safe
2340           but slow) or not (unsafe but fast).  The possible values for this
2341           string are:
2342
2343           "cachemode = "writeback""
2344               This is the default.
2345
2346               Write operations in the API do not return until a write(2) call
2347               has completed in the host [but note this does not imply that
2348               anything gets written to disk].
2349
2350               Sync operations in the API, including implicit syncs caused by
2351               filesystem journalling, will not return until an fdatasync(2)
2352               call has completed in the host, indicating that data has been
2353               committed to disk.
2354
2355           "cachemode = "unsafe""
2356               In this mode, there are no guarantees.  Libguestfs may cache
2357               anything and ignore sync requests.  This is suitable only for
2358               scratch or temporary disks.
2359
2360       "discard"
2361           Enable or disable discard (a.k.a. trim or unmap) support on this
2362           drive.  If enabled, operations such as "guestfs_fstrim" will be
2363           able to discard / make thin / punch holes in the underlying host
2364           file or device.
2365
2366           Possible discard settings are:
2367
2368           "discard = "disable""
2369               Disable discard support.  This is the default.
2370
2371           "discard = "enable""
2372               Enable discard support.  Fail if discard is not possible.
2373
2374           "discard = "besteffort""
2375               Enable discard support if possible, but don't fail if it is not
2376               supported.
2377
2378               Since not all backends and not all underlying systems support
2379               discard, this is a good choice if you want to use discard if
2380               possible, but don't mind if it doesn't work.
2381
2382       "copyonread"
2383           The boolean parameter "copyonread" enables copy-on-read support.
2384           This only affects disk formats which have backing files, and causes
2385           reads to be stored in the overlay layer, speeding up multiple reads
2386           of the same area of disk.
2387
2388           The default is false.
2389
2390       "blocksize"
2391           This parameter sets the sector size of the disk.  Possible values
2392           are 512 (the default if the parameter is omitted) or 4096.  Use
2393           4096 when handling an "Advanced Format" disk that uses 4K sector
2394           size (https://en.wikipedia.org/wiki/Advanced_Format).
2395
2396           Only a subset of the backends support this parameter (currently
2397           only the libvirt and direct backends do).
2398
2399       This function returns 0 on success or -1 on error.
2400
2401       (Added in 0.3)
2402
2403   guestfs_add_drive_opts_va
2404        int
2405        guestfs_add_drive_opts_va (guestfs_h *g,
2406                                   const char *filename,
2407                                   va_list args);
2408
2409       This is the "va_list variant" of "guestfs_add_drive_opts".
2410
2411       See "CALLS WITH OPTIONAL ARGUMENTS".
2412
2413   guestfs_add_drive_opts_argv
2414        int
2415        guestfs_add_drive_opts_argv (guestfs_h *g,
2416                                     const char *filename,
2417                                     const struct guestfs_add_drive_opts_argv *optargs);
2418
2419       This is the "argv variant" of "guestfs_add_drive_opts".
2420
2421       See "CALLS WITH OPTIONAL ARGUMENTS".
2422
2423   guestfs_add_drive_ro
2424        int
2425        guestfs_add_drive_ro (guestfs_h *g,
2426                              const char *filename);
2427
2428       This function is the equivalent of calling "guestfs_add_drive_opts"
2429       with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2430       so the disk is added read-only, with the format being detected
2431       automatically.
2432
2433       This function returns 0 on success or -1 on error.
2434
2435       (Added in 1.0.38)
2436
2437   guestfs_add_drive_ro_with_if
2438        int
2439        guestfs_add_drive_ro_with_if (guestfs_h *g,
2440                                      const char *filename,
2441                                      const char *iface);
2442
2443       This function is deprecated.  In new code, use the "guestfs_add_drive"
2444       call instead.
2445
2446       Deprecated functions will not be removed from the API, but the fact
2447       that they are deprecated indicates that there are problems with correct
2448       use of these functions.
2449
2450       This is the same as "guestfs_add_drive_ro" but it allows you to specify
2451       the QEMU interface emulation to use at run time.
2452
2453       This function returns 0 on success or -1 on error.
2454
2455       (Added in 1.0.84)
2456
2457   guestfs_add_drive_scratch
2458        int
2459        guestfs_add_drive_scratch (guestfs_h *g,
2460                                   int64_t size,
2461                                   ...);
2462
2463       You may supply a list of optional arguments to this call.  Use zero or
2464       more of the following pairs of parameters, and terminate the list with
2465       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2466
2467        GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2468        GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2469        GUESTFS_ADD_DRIVE_SCRATCH_BLOCKSIZE, int blocksize,
2470
2471       This command adds a temporary scratch drive to the handle.  The "size"
2472       parameter is the virtual size (in bytes).  The scratch drive is blank
2473       initially (all reads return zeroes until you start writing to it).  The
2474       drive is deleted when the handle is closed.
2475
2476       The optional arguments "name", "label" and "blocksize" are passed
2477       through to "guestfs_add_drive_opts".
2478
2479       This function returns 0 on success or -1 on error.
2480
2481       (Added in 1.23.10)
2482
2483   guestfs_add_drive_scratch_va
2484        int
2485        guestfs_add_drive_scratch_va (guestfs_h *g,
2486                                      int64_t size,
2487                                      va_list args);
2488
2489       This is the "va_list variant" of "guestfs_add_drive_scratch".
2490
2491       See "CALLS WITH OPTIONAL ARGUMENTS".
2492
2493   guestfs_add_drive_scratch_argv
2494        int
2495        guestfs_add_drive_scratch_argv (guestfs_h *g,
2496                                        int64_t size,
2497                                        const struct guestfs_add_drive_scratch_argv *optargs);
2498
2499       This is the "argv variant" of "guestfs_add_drive_scratch".
2500
2501       See "CALLS WITH OPTIONAL ARGUMENTS".
2502
2503   guestfs_add_drive_with_if
2504        int
2505        guestfs_add_drive_with_if (guestfs_h *g,
2506                                   const char *filename,
2507                                   const char *iface);
2508
2509       This function is deprecated.  In new code, use the "guestfs_add_drive"
2510       call instead.
2511
2512       Deprecated functions will not be removed from the API, but the fact
2513       that they are deprecated indicates that there are problems with correct
2514       use of these functions.
2515
2516       This is the same as "guestfs_add_drive" but it allows you to specify
2517       the QEMU interface emulation to use at run time.
2518
2519       This function returns 0 on success or -1 on error.
2520
2521       (Added in 1.0.84)
2522
2523   guestfs_add_libvirt_dom
2524        int
2525        guestfs_add_libvirt_dom (guestfs_h *g,
2526                                 void * /* really virDomainPtr */ dom,
2527                                 ...);
2528
2529       You may supply a list of optional arguments to this call.  Use zero or
2530       more of the following pairs of parameters, and terminate the list with
2531       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2532
2533        GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2534        GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2535        GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2536        GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2537        GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2538        GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2539        GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2540
2541       This function adds the disk(s) attached to the libvirt domain "dom".
2542       It works by requesting the domain XML from libvirt, parsing it for
2543       disks, and calling "guestfs_add_drive_opts" on each one.
2544
2545       In the C API we declare "void *dom", but really it has type
2546       "virDomainPtr dom".  This is so we don't need <libvirt.h>.
2547
2548       The number of disks added is returned.  This operation is atomic: if an
2549       error is returned, then no disks are added.
2550
2551       This function does some minimal checks to make sure the libvirt domain
2552       is not running (unless "readonly" is true).  In a future version we
2553       will try to acquire the libvirt lock on each disk.
2554
2555       Disks must be accessible locally.  This often means that adding disks
2556       from a remote libvirt connection (see https://libvirt.org/remote.html)
2557       will fail unless those disks are accessible via the same device path
2558       locally too.
2559
2560       The optional "live" flag controls whether this call will try to connect
2561       to a running virtual machine "guestfsd" process if it sees a suitable
2562       <channel> element in the libvirt XML definition.  The default (if the
2563       flag is omitted) is never to try.  See "ATTACHING TO RUNNING DAEMONS"
2564       for more information.
2565
2566       The optional "readonlydisk" parameter controls what we do for disks
2567       which are marked <readonly/> in the libvirt XML.  See
2568       "guestfs_add_domain" for possible values.
2569
2570       If present, the value of "logical_block_size" attribute of <blockio/>
2571       tag in libvirt XML will be passed as "blocksize" parameter to
2572       "guestfs_add_drive_opts".
2573
2574       The other optional parameters are passed directly through to
2575       "guestfs_add_drive_opts".
2576
2577       On error this function returns -1.
2578
2579       (Added in 1.29.14)
2580
2581   guestfs_add_libvirt_dom_va
2582        int
2583        guestfs_add_libvirt_dom_va (guestfs_h *g,
2584                                    void * /* really virDomainPtr */ dom,
2585                                    va_list args);
2586
2587       This is the "va_list variant" of "guestfs_add_libvirt_dom".
2588
2589       See "CALLS WITH OPTIONAL ARGUMENTS".
2590
2591   guestfs_add_libvirt_dom_argv
2592        int
2593        guestfs_add_libvirt_dom_argv (guestfs_h *g,
2594                                      void * /* really virDomainPtr */ dom,
2595                                      const struct guestfs_add_libvirt_dom_argv *optargs);
2596
2597       This is the "argv variant" of "guestfs_add_libvirt_dom".
2598
2599       See "CALLS WITH OPTIONAL ARGUMENTS".
2600
2601   guestfs_aug_clear
2602        int
2603        guestfs_aug_clear (guestfs_h *g,
2604                           const char *augpath);
2605
2606       Set the value associated with "path" to "NULL".  This is the same as
2607       the augtool(1) "clear" command.
2608
2609       This function returns 0 on success or -1 on error.
2610
2611       (Added in 1.3.4)
2612
2613   guestfs_aug_close
2614        int
2615        guestfs_aug_close (guestfs_h *g);
2616
2617       Close the current Augeas handle and free up any resources used by it.
2618       After calling this, you have to call "guestfs_aug_init" again before
2619       you can use any other Augeas functions.
2620
2621       This function returns 0 on success or -1 on error.
2622
2623       (Added in 0.7)
2624
2625   guestfs_aug_defnode
2626        struct guestfs_int_bool *
2627        guestfs_aug_defnode (guestfs_h *g,
2628                             const char *name,
2629                             const char *expr,
2630                             const char *val);
2631
2632       Defines a variable "name" whose value is the result of evaluating
2633       "expr".
2634
2635       If "expr" evaluates to an empty nodeset, a node is created, equivalent
2636       to calling "guestfs_aug_set" "expr", "val".  "name" will be the nodeset
2637       containing that single node.
2638
2639       On success this returns a pair containing the number of nodes in the
2640       nodeset, and a boolean flag if a node was created.
2641
2642       This function returns a "struct guestfs_int_bool *", or NULL if there
2643       was an error.  The caller must call "guestfs_free_int_bool" after use.
2644
2645       (Added in 0.7)
2646
2647   guestfs_aug_defvar
2648        int
2649        guestfs_aug_defvar (guestfs_h *g,
2650                            const char *name,
2651                            const char *expr);
2652
2653       Defines an Augeas variable "name" whose value is the result of
2654       evaluating "expr".  If "expr" is NULL, then "name" is undefined.
2655
2656       On success this returns the number of nodes in "expr", or 0 if "expr"
2657       evaluates to something which is not a nodeset.
2658
2659       On error this function returns -1.
2660
2661       (Added in 0.7)
2662
2663   guestfs_aug_get
2664        char *
2665        guestfs_aug_get (guestfs_h *g,
2666                         const char *augpath);
2667
2668       Look up the value associated with "path".  If "path" matches exactly
2669       one node, the "value" is returned.
2670
2671       This function returns a string, or NULL on error.  The caller must free
2672       the returned string after use.
2673
2674       (Added in 0.7)
2675
2676   guestfs_aug_init
2677        int
2678        guestfs_aug_init (guestfs_h *g,
2679                          const char *root,
2680                          int flags);
2681
2682       Create a new Augeas handle for editing configuration files.  If there
2683       was any previous Augeas handle associated with this guestfs session,
2684       then it is closed.
2685
2686       You must call this before using any other "guestfs_aug_*" commands.
2687
2688       "root" is the filesystem root.  "root" must not be NULL, use / instead.
2689
2690       The flags are the same as the flags defined in <augeas.h>, the logical
2691       or of the following integers:
2692
2693       "AUG_SAVE_BACKUP" = 1
2694           Keep the original file with a ".augsave" extension.
2695
2696       "AUG_SAVE_NEWFILE" = 2
2697           Save changes into a file with extension ".augnew", and do not
2698           overwrite original.  Overrides "AUG_SAVE_BACKUP".
2699
2700       "AUG_TYPE_CHECK" = 4
2701           Typecheck lenses.
2702
2703           This option is only useful when debugging Augeas lenses.  Use of
2704           this option may require additional memory for the libguestfs
2705           appliance.  You may need to set the "LIBGUESTFS_MEMSIZE"
2706           environment variable or call "guestfs_set_memsize".
2707
2708       "AUG_NO_STDINC" = 8
2709           Do not use standard load path for modules.
2710
2711       "AUG_SAVE_NOOP" = 16
2712           Make save a no-op, just record what would have been changed.
2713
2714       "AUG_NO_LOAD" = 32
2715           Do not load the tree in "guestfs_aug_init".
2716
2717       To close the handle, you can call "guestfs_aug_close".
2718
2719       To find out more about Augeas, see http://augeas.net/.
2720
2721       This function returns 0 on success or -1 on error.
2722
2723       (Added in 0.7)
2724
2725   guestfs_aug_insert
2726        int
2727        guestfs_aug_insert (guestfs_h *g,
2728                            const char *augpath,
2729                            const char *label,
2730                            int before);
2731
2732       Create a new sibling "label" for "path", inserting it into the tree
2733       before or after "path" (depending on the boolean flag "before").
2734
2735       "path" must match exactly one existing node in the tree, and "label"
2736       must be a label, ie. not contain /, "*" or end with a bracketed index
2737       "[N]".
2738
2739       This function returns 0 on success or -1 on error.
2740
2741       (Added in 0.7)
2742
2743   guestfs_aug_label
2744        char *
2745        guestfs_aug_label (guestfs_h *g,
2746                           const char *augpath);
2747
2748       The label (name of the last element) of the Augeas path expression
2749       "augpath" is returned.  "augpath" must match exactly one node, else
2750       this function returns an error.
2751
2752       This function returns a string, or NULL on error.  The caller must free
2753       the returned string after use.
2754
2755       (Added in 1.23.14)
2756
2757   guestfs_aug_load
2758        int
2759        guestfs_aug_load (guestfs_h *g);
2760
2761       Load files into the tree.
2762
2763       See "aug_load" in the Augeas documentation for the full gory details.
2764
2765       This function returns 0 on success or -1 on error.
2766
2767       (Added in 0.7)
2768
2769   guestfs_aug_ls
2770        char **
2771        guestfs_aug_ls (guestfs_h *g,
2772                        const char *augpath);
2773
2774       This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2775       sorting the resulting nodes into alphabetical order.
2776
2777       This function returns a NULL-terminated array of strings (like
2778       environ(3)), or NULL if there was an error.  The caller must free the
2779       strings and the array after use.
2780
2781       (Added in 0.8)
2782
2783   guestfs_aug_match
2784        char **
2785        guestfs_aug_match (guestfs_h *g,
2786                           const char *augpath);
2787
2788       Returns a list of paths which match the path expression "path".  The
2789       returned paths are sufficiently qualified so that they match exactly
2790       one node in the current tree.
2791
2792       This function returns a NULL-terminated array of strings (like
2793       environ(3)), or NULL if there was an error.  The caller must free the
2794       strings and the array after use.
2795
2796       (Added in 0.7)
2797
2798   guestfs_aug_mv
2799        int
2800        guestfs_aug_mv (guestfs_h *g,
2801                        const char *src,
2802                        const char *dest);
2803
2804       Move the node "src" to "dest".  "src" must match exactly one node.
2805       "dest" is overwritten if it exists.
2806
2807       This function returns 0 on success or -1 on error.
2808
2809       (Added in 0.7)
2810
2811   guestfs_aug_rm
2812        int
2813        guestfs_aug_rm (guestfs_h *g,
2814                        const char *augpath);
2815
2816       Remove "path" and all of its children.
2817
2818       On success this returns the number of entries which were removed.
2819
2820       On error this function returns -1.
2821
2822       (Added in 0.7)
2823
2824   guestfs_aug_save
2825        int
2826        guestfs_aug_save (guestfs_h *g);
2827
2828       This writes all pending changes to disk.
2829
2830       The flags which were passed to "guestfs_aug_init" affect exactly how
2831       files are saved.
2832
2833       This function returns 0 on success or -1 on error.
2834
2835       (Added in 0.7)
2836
2837   guestfs_aug_set
2838        int
2839        guestfs_aug_set (guestfs_h *g,
2840                         const char *augpath,
2841                         const char *val);
2842
2843       Set the value associated with "augpath" to "val".
2844
2845       In the Augeas API, it is possible to clear a node by setting the value
2846       to NULL.  Due to an oversight in the libguestfs API you cannot do that
2847       with this call.  Instead you must use the "guestfs_aug_clear" call.
2848
2849       This function returns 0 on success or -1 on error.
2850
2851       (Added in 0.7)
2852
2853   guestfs_aug_setm
2854        int
2855        guestfs_aug_setm (guestfs_h *g,
2856                          const char *base,
2857                          const char *sub,
2858                          const char *val);
2859
2860       Change multiple Augeas nodes in a single operation.  "base" is an
2861       expression matching multiple nodes.  "sub" is a path expression
2862       relative to "base".  All nodes matching "base" are found, and then for
2863       each node, "sub" is changed to "val".  "sub" may also be "NULL" in
2864       which case the "base" nodes are modified.
2865
2866       This returns the number of nodes modified.
2867
2868       On error this function returns -1.
2869
2870       (Added in 1.23.14)
2871
2872   guestfs_aug_transform
2873        int
2874        guestfs_aug_transform (guestfs_h *g,
2875                               const char *lens,
2876                               const char *file,
2877                               ...);
2878
2879       You may supply a list of optional arguments to this call.  Use zero or
2880       more of the following pairs of parameters, and terminate the list with
2881       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
2882
2883        GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2884
2885       Add an Augeas transformation for the specified "lens" so it can handle
2886       "file".
2887
2888       If "remove" is true ("false" by default), then the transformation is
2889       removed.
2890
2891       This function returns 0 on success or -1 on error.
2892
2893       (Added in 1.35.2)
2894
2895   guestfs_aug_transform_va
2896        int
2897        guestfs_aug_transform_va (guestfs_h *g,
2898                                  const char *lens,
2899                                  const char *file,
2900                                  va_list args);
2901
2902       This is the "va_list variant" of "guestfs_aug_transform".
2903
2904       See "CALLS WITH OPTIONAL ARGUMENTS".
2905
2906   guestfs_aug_transform_argv
2907        int
2908        guestfs_aug_transform_argv (guestfs_h *g,
2909                                    const char *lens,
2910                                    const char *file,
2911                                    const struct guestfs_aug_transform_argv *optargs);
2912
2913       This is the "argv variant" of "guestfs_aug_transform".
2914
2915       See "CALLS WITH OPTIONAL ARGUMENTS".
2916
2917   guestfs_available
2918        int
2919        guestfs_available (guestfs_h *g,
2920                           char *const *groups);
2921
2922       This command is used to check the availability of some groups of
2923       functionality in the appliance, which not all builds of the libguestfs
2924       appliance will be able to provide.
2925
2926       The libguestfs groups, and the functions that those groups correspond
2927       to, are listed in "AVAILABILITY".  You can also fetch this list at
2928       runtime by calling "guestfs_available_all_groups".
2929
2930       The argument "groups" is a list of group names, eg: "["inotify",
2931       "augeas"]" would check for the availability of the Linux inotify
2932       functions and Augeas (configuration file editing) functions.
2933
2934       The command returns no error if all requested groups are available.
2935
2936       It fails with an error if one or more of the requested groups is
2937       unavailable in the appliance.
2938
2939       If an unknown group name is included in the list of groups then an
2940       error is always returned.
2941
2942       Notes:
2943
2944       •   "guestfs_feature_available" is the same as this call, but with a
2945           slightly simpler to use API: that call returns a boolean true/false
2946           instead of throwing an error.
2947
2948       •   You must call "guestfs_launch" before calling this function.
2949
2950           The reason is because we don't know what groups are supported by
2951           the appliance/daemon until it is running and can be queried.
2952
2953       •   If a group of functions is available, this does not necessarily
2954           mean that they will work.  You still have to check for errors when
2955           calling individual API functions even if they are available.
2956
2957       •   It is usually the job of distro packagers to build complete
2958           functionality into the libguestfs appliance.  Upstream libguestfs,
2959           if built from source with all requirements satisfied, will support
2960           everything.
2961
2962       •   This call was added in version 1.0.80.  In previous versions of
2963           libguestfs all you could do would be to speculatively execute a
2964           command to find out if the daemon implemented it.  See also
2965           "guestfs_version".
2966
2967       See also "guestfs_filesystem_available".
2968
2969       This function returns 0 on success or -1 on error.
2970
2971       (Added in 1.0.80)
2972
2973   guestfs_available_all_groups
2974        char **
2975        guestfs_available_all_groups (guestfs_h *g);
2976
2977       This command returns a list of all optional groups that this daemon
2978       knows about.  Note this returns both supported and unsupported groups.
2979       To find out which ones the daemon can actually support you have to call
2980       "guestfs_available" / "guestfs_feature_available" on each member of the
2981       returned list.
2982
2983       See also "guestfs_available", "guestfs_feature_available" and
2984       "AVAILABILITY".
2985
2986       This function returns a NULL-terminated array of strings (like
2987       environ(3)), or NULL if there was an error.  The caller must free the
2988       strings and the array after use.
2989
2990       (Added in 1.3.15)
2991
2992   guestfs_base64_in
2993        int
2994        guestfs_base64_in (guestfs_h *g,
2995                           const char *base64file,
2996                           const char *filename);
2997
2998       This command uploads base64-encoded data from "base64file" to filename.
2999
3000       This function returns 0 on success or -1 on error.
3001
3002       (Added in 1.3.5)
3003
3004   guestfs_base64_out
3005        int
3006        guestfs_base64_out (guestfs_h *g,
3007                            const char *filename,
3008                            const char *base64file);
3009
3010       This command downloads the contents of filename, writing it out to
3011       local file "base64file" encoded as base64.
3012
3013       This function returns 0 on success or -1 on error.
3014
3015       (Added in 1.3.5)
3016
3017   guestfs_blkdiscard
3018        int
3019        guestfs_blkdiscard (guestfs_h *g,
3020                            const char *device);
3021
3022       This discards all blocks on the block device "device", giving the free
3023       space back to the host.
3024
3025       This operation requires support in libguestfs, the host filesystem,
3026       qemu and the host kernel.  If this support isn't present it may give an
3027       error or even appear to run but do nothing.  You must also set the
3028       "discard" attribute on the underlying drive (see
3029       "guestfs_add_drive_opts").
3030
3031       This function returns 0 on success or -1 on error.
3032
3033       This function depends on the feature "blkdiscard".  See also
3034       "guestfs_feature_available".
3035
3036       (Added in 1.25.44)
3037
3038   guestfs_blkdiscardzeroes
3039        int
3040        guestfs_blkdiscardzeroes (guestfs_h *g,
3041                                  const char *device);
3042
3043       This call returns true if blocks on "device" that have been discarded
3044       by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
3045       when read the next time.
3046
3047       If it returns false, then it may be that discarded blocks are read as
3048       stale or random data.
3049
3050       This function returns a C truth value on success or -1 on error.
3051
3052       This function depends on the feature "blkdiscardzeroes".  See also
3053       "guestfs_feature_available".
3054
3055       (Added in 1.25.44)
3056
3057   guestfs_blkid
3058        char **
3059        guestfs_blkid (guestfs_h *g,
3060                       const char *device);
3061
3062       This command returns block device attributes for "device". The
3063       following fields are usually present in the returned hash. Other fields
3064       may also be present.
3065
3066       "UUID"
3067           The uuid of this device.
3068
3069       "LABEL"
3070           The label of this device.
3071
3072       "VERSION"
3073           The version of blkid command.
3074
3075       "TYPE"
3076           The filesystem type or RAID of this device.
3077
3078       "USAGE"
3079           The usage of this device, for example "filesystem" or "raid".
3080
3081       This function returns a NULL-terminated array of strings, or NULL if
3082       there was an error.  The array of strings will always have length
3083       "2n+1", where "n" keys and values alternate, followed by the trailing
3084       NULL entry.  The caller must free the strings and the array after use.
3085
3086       (Added in 1.15.9)
3087
3088   guestfs_blockdev_flushbufs
3089        int
3090        guestfs_blockdev_flushbufs (guestfs_h *g,
3091                                    const char *device);
3092
3093       This tells the kernel to flush internal buffers associated with
3094       "device".
3095
3096       This uses the blockdev(8) command.
3097
3098       This function returns 0 on success or -1 on error.
3099
3100       (Added in 1.9.3)
3101
3102   guestfs_blockdev_getbsz
3103        int
3104        guestfs_blockdev_getbsz (guestfs_h *g,
3105                                 const char *device);
3106
3107       This returns the block size of a device.
3108
3109       Note: this is different from both size in blocks and filesystem block
3110       size.  Also this setting is not really used by anything.  You should
3111       probably not use it for anything.  Filesystems have their own idea
3112       about what block size to choose.
3113
3114       This uses the blockdev(8) command.
3115
3116       On error this function returns -1.
3117
3118       (Added in 1.9.3)
3119
3120   guestfs_blockdev_getro
3121        int
3122        guestfs_blockdev_getro (guestfs_h *g,
3123                                const char *device);
3124
3125       Returns a boolean indicating if the block device is read-only (true if
3126       read-only, false if not).
3127
3128       This uses the blockdev(8) command.
3129
3130       This function returns a C truth value on success or -1 on error.
3131
3132       (Added in 1.9.3)
3133
3134   guestfs_blockdev_getsize64
3135        int64_t
3136        guestfs_blockdev_getsize64 (guestfs_h *g,
3137                                    const char *device);
3138
3139       This returns the size of the device in bytes.
3140
3141       See also "guestfs_blockdev_getsz".
3142
3143       This uses the blockdev(8) command.
3144
3145       On error this function returns -1.
3146
3147       (Added in 1.9.3)
3148
3149   guestfs_blockdev_getss
3150        int
3151        guestfs_blockdev_getss (guestfs_h *g,
3152                                const char *device);
3153
3154       This returns the size of sectors on a block device.  Usually 512, but
3155       can be larger for modern devices.
3156
3157       (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
3158       for that).
3159
3160       This uses the blockdev(8) command.
3161
3162       On error this function returns -1.
3163
3164       (Added in 1.9.3)
3165
3166   guestfs_blockdev_getsz
3167        int64_t
3168        guestfs_blockdev_getsz (guestfs_h *g,
3169                                const char *device);
3170
3171       This returns the size of the device in units of 512-byte sectors (even
3172       if the sectorsize isn't 512 bytes ... weird).
3173
3174       See also "guestfs_blockdev_getss" for the real sector size of the
3175       device, and "guestfs_blockdev_getsize64" for the more useful size in
3176       bytes.
3177
3178       This uses the blockdev(8) command.
3179
3180       On error this function returns -1.
3181
3182       (Added in 1.9.3)
3183
3184   guestfs_blockdev_rereadpt
3185        int
3186        guestfs_blockdev_rereadpt (guestfs_h *g,
3187                                   const char *device);
3188
3189       Reread the partition table on "device".
3190
3191       This uses the blockdev(8) command.
3192
3193       This function returns 0 on success or -1 on error.
3194
3195       (Added in 1.9.3)
3196
3197   guestfs_blockdev_setbsz
3198        int
3199        guestfs_blockdev_setbsz (guestfs_h *g,
3200                                 const char *device,
3201                                 int blocksize);
3202
3203       This function is deprecated.  There is no replacement.  Consult the API
3204       documentation in guestfs(3) for further information.
3205
3206       Deprecated functions will not be removed from the API, but the fact
3207       that they are deprecated indicates that there are problems with correct
3208       use of these functions.
3209
3210       This call does nothing and has never done anything because of a bug in
3211       blockdev.  Do not use it.
3212
3213       If you need to set the filesystem block size, use the "blocksize"
3214       option of "guestfs_mkfs".
3215
3216       This function returns 0 on success or -1 on error.
3217
3218       (Added in 1.9.3)
3219
3220   guestfs_blockdev_setra
3221        int
3222        guestfs_blockdev_setra (guestfs_h *g,
3223                                const char *device,
3224                                int sectors);
3225
3226       Set readahead (in 512-byte sectors) for the device.
3227
3228       This uses the blockdev(8) command.
3229
3230       This function returns 0 on success or -1 on error.
3231
3232       (Added in 1.29.10)
3233
3234   guestfs_blockdev_setro
3235        int
3236        guestfs_blockdev_setro (guestfs_h *g,
3237                                const char *device);
3238
3239       Sets the block device named "device" to read-only.
3240
3241       This uses the blockdev(8) command.
3242
3243       This function returns 0 on success or -1 on error.
3244
3245       (Added in 1.9.3)
3246
3247   guestfs_blockdev_setrw
3248        int
3249        guestfs_blockdev_setrw (guestfs_h *g,
3250                                const char *device);
3251
3252       Sets the block device named "device" to read-write.
3253
3254       This uses the blockdev(8) command.
3255
3256       This function returns 0 on success or -1 on error.
3257
3258       (Added in 1.9.3)
3259
3260   guestfs_btrfs_balance_cancel
3261        int
3262        guestfs_btrfs_balance_cancel (guestfs_h *g,
3263                                      const char *path);
3264
3265       Cancel a running balance on a btrfs filesystem.
3266
3267       This function returns 0 on success or -1 on error.
3268
3269       This function depends on the feature "btrfs".  See also
3270       "guestfs_feature_available".
3271
3272       (Added in 1.29.22)
3273
3274   guestfs_btrfs_balance_pause
3275        int
3276        guestfs_btrfs_balance_pause (guestfs_h *g,
3277                                     const char *path);
3278
3279       Pause a running balance on a btrfs filesystem.
3280
3281       This function returns 0 on success or -1 on error.
3282
3283       This function depends on the feature "btrfs".  See also
3284       "guestfs_feature_available".
3285
3286       (Added in 1.29.22)
3287
3288   guestfs_btrfs_balance_resume
3289        int
3290        guestfs_btrfs_balance_resume (guestfs_h *g,
3291                                      const char *path);
3292
3293       Resume a paused balance on a btrfs filesystem.
3294
3295       This function returns 0 on success or -1 on error.
3296
3297       This function depends on the feature "btrfs".  See also
3298       "guestfs_feature_available".
3299
3300       (Added in 1.29.22)
3301
3302   guestfs_btrfs_balance_status
3303        struct guestfs_btrfsbalance *
3304        guestfs_btrfs_balance_status (guestfs_h *g,
3305                                      const char *path);
3306
3307       Show the status of a running or paused balance on a btrfs filesystem.
3308
3309       This function returns a "struct guestfs_btrfsbalance *", or NULL if
3310       there was an error.  The caller must call "guestfs_free_btrfsbalance"
3311       after use.
3312
3313       This function depends on the feature "btrfs".  See also
3314       "guestfs_feature_available".
3315
3316       (Added in 1.29.26)
3317
3318   guestfs_btrfs_device_add
3319        int
3320        guestfs_btrfs_device_add (guestfs_h *g,
3321                                  char *const *devices,
3322                                  const char *fs);
3323
3324       Add the list of device(s) in "devices" to the btrfs filesystem mounted
3325       at "fs".  If "devices" is an empty list, this does nothing.
3326
3327       This function returns 0 on success or -1 on error.
3328
3329       This function depends on the feature "btrfs".  See also
3330       "guestfs_feature_available".
3331
3332       (Added in 1.17.35)
3333
3334   guestfs_btrfs_device_delete
3335        int
3336        guestfs_btrfs_device_delete (guestfs_h *g,
3337                                     char *const *devices,
3338                                     const char *fs);
3339
3340       Remove the "devices" from the btrfs filesystem mounted at "fs".  If
3341       "devices" is an empty list, this does nothing.
3342
3343       This function returns 0 on success or -1 on error.
3344
3345       This function depends on the feature "btrfs".  See also
3346       "guestfs_feature_available".
3347
3348       (Added in 1.17.35)
3349
3350   guestfs_btrfs_filesystem_balance
3351        int
3352        guestfs_btrfs_filesystem_balance (guestfs_h *g,
3353                                          const char *fs);
3354
3355       Balance the chunks in the btrfs filesystem mounted at "fs" across the
3356       underlying devices.
3357
3358       This function returns 0 on success or -1 on error.
3359
3360       This function depends on the feature "btrfs".  See also
3361       "guestfs_feature_available".
3362
3363       (Added in 1.17.35)
3364
3365   guestfs_btrfs_filesystem_defragment
3366        int
3367        guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3368                                             const char *path,
3369                                             ...);
3370
3371       You may supply a list of optional arguments to this call.  Use zero or
3372       more of the following pairs of parameters, and terminate the list with
3373       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3374
3375        GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3376        GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3377
3378       Defragment a file or directory on a btrfs filesystem. compress is one
3379       of zlib or lzo.
3380
3381       This function returns 0 on success or -1 on error.
3382
3383       This function depends on the feature "btrfs".  See also
3384       "guestfs_feature_available".
3385
3386       (Added in 1.29.22)
3387
3388   guestfs_btrfs_filesystem_defragment_va
3389        int
3390        guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3391                                                const char *path,
3392                                                va_list args);
3393
3394       This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3395
3396       See "CALLS WITH OPTIONAL ARGUMENTS".
3397
3398   guestfs_btrfs_filesystem_defragment_argv
3399        int
3400        guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3401                                                  const char *path,
3402                                                  const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3403
3404       This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3405
3406       See "CALLS WITH OPTIONAL ARGUMENTS".
3407
3408   guestfs_btrfs_filesystem_resize
3409        int
3410        guestfs_btrfs_filesystem_resize (guestfs_h *g,
3411                                         const char *mountpoint,
3412                                         ...);
3413
3414       You may supply a list of optional arguments to this call.  Use zero or
3415       more of the following pairs of parameters, and terminate the list with
3416       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3417
3418        GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3419
3420       This command resizes a btrfs filesystem.
3421
3422       Note that unlike other resize calls, the filesystem has to be mounted
3423       and the parameter is the mountpoint not the device (this is a
3424       requirement of btrfs itself).
3425
3426       The optional parameters are:
3427
3428       "size"
3429           The new size (in bytes) of the filesystem.  If omitted, the
3430           filesystem is resized to the maximum size.
3431
3432       See also btrfs(8).
3433
3434       This function returns 0 on success or -1 on error.
3435
3436       This function depends on the feature "btrfs".  See also
3437       "guestfs_feature_available".
3438
3439       (Added in 1.11.17)
3440
3441   guestfs_btrfs_filesystem_resize_va
3442        int
3443        guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3444                                            const char *mountpoint,
3445                                            va_list args);
3446
3447       This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3448
3449       See "CALLS WITH OPTIONAL ARGUMENTS".
3450
3451   guestfs_btrfs_filesystem_resize_argv
3452        int
3453        guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3454                                              const char *mountpoint,
3455                                              const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3456
3457       This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3458
3459       See "CALLS WITH OPTIONAL ARGUMENTS".
3460
3461   guestfs_btrfs_filesystem_show
3462        char **
3463        guestfs_btrfs_filesystem_show (guestfs_h *g,
3464                                       const char *device);
3465
3466       Show all the devices where the filesystems in "device" is spanned over.
3467
3468       If not all the devices for the filesystems are present, then this
3469       function fails and the "errno" is set to "ENODEV".
3470
3471       This function returns a NULL-terminated array of strings (like
3472       environ(3)), or NULL if there was an error.  The caller must free the
3473       strings and the array after use.
3474
3475       This function depends on the feature "btrfs".  See also
3476       "guestfs_feature_available".
3477
3478       (Added in 1.33.29)
3479
3480   guestfs_btrfs_filesystem_sync
3481        int
3482        guestfs_btrfs_filesystem_sync (guestfs_h *g,
3483                                       const char *fs);
3484
3485       Force sync on the btrfs filesystem mounted at "fs".
3486
3487       This function returns 0 on success or -1 on error.
3488
3489       This function depends on the feature "btrfs".  See also
3490       "guestfs_feature_available".
3491
3492       (Added in 1.17.35)
3493
3494   guestfs_btrfs_fsck
3495        int
3496        guestfs_btrfs_fsck (guestfs_h *g,
3497                            const char *device,
3498                            ...);
3499
3500       You may supply a list of optional arguments to this call.  Use zero or
3501       more of the following pairs of parameters, and terminate the list with
3502       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3503
3504        GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3505        GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3506
3507       Used to check a btrfs filesystem, "device" is the device file where the
3508       filesystem is stored.
3509
3510       This function returns 0 on success or -1 on error.
3511
3512       This function depends on the feature "btrfs".  See also
3513       "guestfs_feature_available".
3514
3515       (Added in 1.17.43)
3516
3517   guestfs_btrfs_fsck_va
3518        int
3519        guestfs_btrfs_fsck_va (guestfs_h *g,
3520                               const char *device,
3521                               va_list args);
3522
3523       This is the "va_list variant" of "guestfs_btrfs_fsck".
3524
3525       See "CALLS WITH OPTIONAL ARGUMENTS".
3526
3527   guestfs_btrfs_fsck_argv
3528        int
3529        guestfs_btrfs_fsck_argv (guestfs_h *g,
3530                                 const char *device,
3531                                 const struct guestfs_btrfs_fsck_argv *optargs);
3532
3533       This is the "argv variant" of "guestfs_btrfs_fsck".
3534
3535       See "CALLS WITH OPTIONAL ARGUMENTS".
3536
3537   guestfs_btrfs_image
3538        int
3539        guestfs_btrfs_image (guestfs_h *g,
3540                             char *const *source,
3541                             const char *image,
3542                             ...);
3543
3544       You may supply a list of optional arguments to this call.  Use zero or
3545       more of the following pairs of parameters, and terminate the list with
3546       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3547
3548        GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3549
3550       This is used to create an image of a btrfs filesystem.  All data will
3551       be zeroed, but metadata and the like is preserved.
3552
3553       This function returns 0 on success or -1 on error.
3554
3555       This function depends on the feature "btrfs".  See also
3556       "guestfs_feature_available".
3557
3558       (Added in 1.29.32)
3559
3560   guestfs_btrfs_image_va
3561        int
3562        guestfs_btrfs_image_va (guestfs_h *g,
3563                                char *const *source,
3564                                const char *image,
3565                                va_list args);
3566
3567       This is the "va_list variant" of "guestfs_btrfs_image".
3568
3569       See "CALLS WITH OPTIONAL ARGUMENTS".
3570
3571   guestfs_btrfs_image_argv
3572        int
3573        guestfs_btrfs_image_argv (guestfs_h *g,
3574                                  char *const *source,
3575                                  const char *image,
3576                                  const struct guestfs_btrfs_image_argv *optargs);
3577
3578       This is the "argv variant" of "guestfs_btrfs_image".
3579
3580       See "CALLS WITH OPTIONAL ARGUMENTS".
3581
3582   guestfs_btrfs_qgroup_assign
3583        int
3584        guestfs_btrfs_qgroup_assign (guestfs_h *g,
3585                                     const char *src,
3586                                     const char *dst,
3587                                     const char *path);
3588
3589       Add qgroup "src" to parent qgroup "dst". This command can group several
3590       qgroups into a parent qgroup to share common limit.
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_create
3600        int
3601        guestfs_btrfs_qgroup_create (guestfs_h *g,
3602                                     const char *qgroupid,
3603                                     const char *subvolume);
3604
3605       Create a quota group (qgroup) for subvolume at "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_destroy
3615        int
3616        guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3617                                      const char *qgroupid,
3618                                      const char *subvolume);
3619
3620       Destroy a quota group.
3621
3622       This function returns 0 on success or -1 on error.
3623
3624       This function depends on the feature "btrfs".  See also
3625       "guestfs_feature_available".
3626
3627       (Added in 1.29.17)
3628
3629   guestfs_btrfs_qgroup_limit
3630        int
3631        guestfs_btrfs_qgroup_limit (guestfs_h *g,
3632                                    const char *subvolume,
3633                                    int64_t size);
3634
3635       Limit the size of the subvolume with path "subvolume".
3636
3637       This function returns 0 on success or -1 on error.
3638
3639       This function depends on the feature "btrfs".  See also
3640       "guestfs_feature_available".
3641
3642       (Added in 1.29.17)
3643
3644   guestfs_btrfs_qgroup_remove
3645        int
3646        guestfs_btrfs_qgroup_remove (guestfs_h *g,
3647                                     const char *src,
3648                                     const char *dst,
3649                                     const char *path);
3650
3651       Remove qgroup "src" from the parent qgroup "dst".
3652
3653       This function returns 0 on success or -1 on error.
3654
3655       This function depends on the feature "btrfs".  See also
3656       "guestfs_feature_available".
3657
3658       (Added in 1.29.17)
3659
3660   guestfs_btrfs_qgroup_show
3661        struct guestfs_btrfsqgroup_list *
3662        guestfs_btrfs_qgroup_show (guestfs_h *g,
3663                                   const char *path);
3664
3665       Show all subvolume quota groups in a btrfs filesystem, including their
3666       usages.
3667
3668       This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3669       there was an error.  The caller must call
3670       "guestfs_free_btrfsqgroup_list" after use.
3671
3672       This function depends on the feature "btrfs".  See also
3673       "guestfs_feature_available".
3674
3675       (Added in 1.29.17)
3676
3677   guestfs_btrfs_quota_enable
3678        int
3679        guestfs_btrfs_quota_enable (guestfs_h *g,
3680                                    const char *fs,
3681                                    int enable);
3682
3683       Enable or disable subvolume quota support for filesystem which contains
3684       "path".
3685
3686       This function returns 0 on success or -1 on error.
3687
3688       This function depends on the feature "btrfs".  See also
3689       "guestfs_feature_available".
3690
3691       (Added in 1.29.17)
3692
3693   guestfs_btrfs_quota_rescan
3694        int
3695        guestfs_btrfs_quota_rescan (guestfs_h *g,
3696                                    const char *fs);
3697
3698       Trash all qgroup numbers and scan the metadata again with the current
3699       config.
3700
3701       This function returns 0 on success or -1 on error.
3702
3703       This function depends on the feature "btrfs".  See also
3704       "guestfs_feature_available".
3705
3706       (Added in 1.29.17)
3707
3708   guestfs_btrfs_replace
3709        int
3710        guestfs_btrfs_replace (guestfs_h *g,
3711                               const char *srcdev,
3712                               const char *targetdev,
3713                               const char *mntpoint);
3714
3715       Replace device of a btrfs filesystem. On a live filesystem, duplicate
3716       the data to the target device which is currently stored on the source
3717       device.  After completion of the operation, the source device is wiped
3718       out and removed from the filesystem.
3719
3720       The "targetdev" needs to be same size or larger than the "srcdev".
3721       Devices which are currently mounted are never allowed to be used as the
3722       "targetdev".
3723
3724       This function returns 0 on success or -1 on error.
3725
3726       This function depends on the feature "btrfs".  See also
3727       "guestfs_feature_available".
3728
3729       (Added in 1.29.48)
3730
3731   guestfs_btrfs_rescue_chunk_recover
3732        int
3733        guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3734                                            const char *device);
3735
3736       Recover the chunk tree of btrfs filesystem by scanning the devices one
3737       by one.
3738
3739       This function returns 0 on success or -1 on error.
3740
3741       This function depends on the feature "btrfs".  See also
3742       "guestfs_feature_available".
3743
3744       (Added in 1.29.22)
3745
3746   guestfs_btrfs_rescue_super_recover
3747        int
3748        guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3749                                            const char *device);
3750
3751       Recover bad superblocks from good copies.
3752
3753       This function returns 0 on success or -1 on error.
3754
3755       This function depends on the feature "btrfs".  See also
3756       "guestfs_feature_available".
3757
3758       (Added in 1.29.22)
3759
3760   guestfs_btrfs_scrub_cancel
3761        int
3762        guestfs_btrfs_scrub_cancel (guestfs_h *g,
3763                                    const char *path);
3764
3765       Cancel a running scrub on a btrfs filesystem.
3766
3767       This function returns 0 on success or -1 on error.
3768
3769       This function depends on the feature "btrfs".  See also
3770       "guestfs_feature_available".
3771
3772       (Added in 1.29.22)
3773
3774   guestfs_btrfs_scrub_resume
3775        int
3776        guestfs_btrfs_scrub_resume (guestfs_h *g,
3777                                    const char *path);
3778
3779       Resume a previously canceled or interrupted scrub on a btrfs
3780       filesystem.
3781
3782       This function returns 0 on success or -1 on error.
3783
3784       This function depends on the feature "btrfs".  See also
3785       "guestfs_feature_available".
3786
3787       (Added in 1.29.22)
3788
3789   guestfs_btrfs_scrub_start
3790        int
3791        guestfs_btrfs_scrub_start (guestfs_h *g,
3792                                   const char *path);
3793
3794       Reads all the data and metadata on the filesystem, and uses checksums
3795       and the duplicate copies from RAID storage to identify and repair any
3796       corrupt data.
3797
3798       This function returns 0 on success or -1 on error.
3799
3800       This function depends on the feature "btrfs".  See also
3801       "guestfs_feature_available".
3802
3803       (Added in 1.29.22)
3804
3805   guestfs_btrfs_scrub_status
3806        struct guestfs_btrfsscrub *
3807        guestfs_btrfs_scrub_status (guestfs_h *g,
3808                                    const char *path);
3809
3810       Show status of running or finished scrub on a btrfs filesystem.
3811
3812       This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3813       was an error.  The caller must call "guestfs_free_btrfsscrub" after
3814       use.
3815
3816       This function depends on the feature "btrfs".  See also
3817       "guestfs_feature_available".
3818
3819       (Added in 1.29.26)
3820
3821   guestfs_btrfs_set_seeding
3822        int
3823        guestfs_btrfs_set_seeding (guestfs_h *g,
3824                                   const char *device,
3825                                   int seeding);
3826
3827       Enable or disable the seeding feature of a device that contains a btrfs
3828       filesystem.
3829
3830       This function returns 0 on success or -1 on error.
3831
3832       This function depends on the feature "btrfs".  See also
3833       "guestfs_feature_available".
3834
3835       (Added in 1.17.43)
3836
3837   guestfs_btrfs_subvolume_create
3838        int
3839        guestfs_btrfs_subvolume_create (guestfs_h *g,
3840                                        const char *dest);
3841
3842       This function is provided for backwards compatibility with earlier
3843       versions of libguestfs.  It simply calls
3844       "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3845
3846       (Added in 1.17.35)
3847
3848   guestfs_btrfs_subvolume_create_opts
3849        int
3850        guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3851                                             const char *dest,
3852                                             ...);
3853
3854       You may supply a list of optional arguments to this call.  Use zero or
3855       more of the following pairs of parameters, and terminate the list with
3856       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3857
3858        GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3859
3860       Create a btrfs subvolume.  The "dest" argument is the destination
3861       directory and the name of the subvolume, in the form
3862       /path/to/dest/name.  The optional parameter "qgroupid" represents the
3863       qgroup which the newly created subvolume will be added to.
3864
3865       This function returns 0 on success or -1 on error.
3866
3867       This function depends on the feature "btrfs".  See also
3868       "guestfs_feature_available".
3869
3870       (Added in 1.17.35)
3871
3872   guestfs_btrfs_subvolume_create_opts_va
3873        int
3874        guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3875                                                const char *dest,
3876                                                va_list args);
3877
3878       This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3879
3880       See "CALLS WITH OPTIONAL ARGUMENTS".
3881
3882   guestfs_btrfs_subvolume_create_opts_argv
3883        int
3884        guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3885                                                  const char *dest,
3886                                                  const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3887
3888       This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3889
3890       See "CALLS WITH OPTIONAL ARGUMENTS".
3891
3892   guestfs_btrfs_subvolume_delete
3893        int
3894        guestfs_btrfs_subvolume_delete (guestfs_h *g,
3895                                        const char *subvolume);
3896
3897       Delete the named btrfs subvolume or snapshot.
3898
3899       This function returns 0 on success or -1 on error.
3900
3901       This function depends on the feature "btrfs".  See also
3902       "guestfs_feature_available".
3903
3904       (Added in 1.17.35)
3905
3906   guestfs_btrfs_subvolume_get_default
3907        int64_t
3908        guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3909                                             const char *fs);
3910
3911       Get the default subvolume or snapshot of a filesystem mounted at
3912       "mountpoint".
3913
3914       On error this function returns -1.
3915
3916       This function depends on the feature "btrfs".  See also
3917       "guestfs_feature_available".
3918
3919       (Added in 1.29.17)
3920
3921   guestfs_btrfs_subvolume_list
3922        struct guestfs_btrfssubvolume_list *
3923        guestfs_btrfs_subvolume_list (guestfs_h *g,
3924                                      const char *fs);
3925
3926       List the btrfs snapshots and subvolumes of the btrfs filesystem which
3927       is mounted at "fs".
3928
3929       This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3930       if there was an error.  The caller must call
3931       "guestfs_free_btrfssubvolume_list" after use.
3932
3933       This function depends on the feature "btrfs".  See also
3934       "guestfs_feature_available".
3935
3936       (Added in 1.17.35)
3937
3938   guestfs_btrfs_subvolume_set_default
3939        int
3940        guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3941                                             int64_t id,
3942                                             const char *fs);
3943
3944       Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3945       default.  See "guestfs_btrfs_subvolume_list" to get a list of
3946       subvolumes.
3947
3948       This function returns 0 on success or -1 on error.
3949
3950       This function depends on the feature "btrfs".  See also
3951       "guestfs_feature_available".
3952
3953       (Added in 1.17.35)
3954
3955   guestfs_btrfs_subvolume_show
3956        char **
3957        guestfs_btrfs_subvolume_show (guestfs_h *g,
3958                                      const char *subvolume);
3959
3960       Return detailed information of the subvolume.
3961
3962       This function returns a NULL-terminated array of strings, or NULL if
3963       there was an error.  The array of strings will always have length
3964       "2n+1", where "n" keys and values alternate, followed by the trailing
3965       NULL entry.  The caller must free the strings and the array after use.
3966
3967       This function depends on the feature "btrfs".  See also
3968       "guestfs_feature_available".
3969
3970       (Added in 1.29.17)
3971
3972   guestfs_btrfs_subvolume_snapshot
3973        int
3974        guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3975                                          const char *source,
3976                                          const char *dest);
3977
3978       This function is provided for backwards compatibility with earlier
3979       versions of libguestfs.  It simply calls
3980       "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3981
3982       (Added in 1.17.35)
3983
3984   guestfs_btrfs_subvolume_snapshot_opts
3985        int
3986        guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3987                                               const char *source,
3988                                               const char *dest,
3989                                               ...);
3990
3991       You may supply a list of optional arguments to this call.  Use zero or
3992       more of the following pairs of parameters, and terminate the list with
3993       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
3994
3995        GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3996        GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3997
3998       Create a snapshot of the btrfs subvolume "source".  The "dest" argument
3999       is the destination directory and the name of the snapshot, in the form
4000       /path/to/dest/name. By default the newly created snapshot is writable,
4001       if the value of optional parameter "ro" is true, then a readonly
4002       snapshot is created. The optional parameter "qgroupid" represents the
4003       qgroup which the newly created snapshot will be added to.
4004
4005       This function returns 0 on success or -1 on error.
4006
4007       This function depends on the feature "btrfs".  See also
4008       "guestfs_feature_available".
4009
4010       (Added in 1.17.35)
4011
4012   guestfs_btrfs_subvolume_snapshot_opts_va
4013        int
4014        guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
4015                                                  const char *source,
4016                                                  const char *dest,
4017                                                  va_list args);
4018
4019       This is the "va_list variant" of
4020       "guestfs_btrfs_subvolume_snapshot_opts".
4021
4022       See "CALLS WITH OPTIONAL ARGUMENTS".
4023
4024   guestfs_btrfs_subvolume_snapshot_opts_argv
4025        int
4026        guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
4027                                                    const char *source,
4028                                                    const char *dest,
4029                                                    const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
4030
4031       This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
4032
4033       See "CALLS WITH OPTIONAL ARGUMENTS".
4034
4035   guestfs_btrfstune_enable_extended_inode_refs
4036        int
4037        guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
4038                                                      const char *device);
4039
4040       This will Enable extended inode refs.
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_btrfstune_enable_skinny_metadata_extent_refs
4050        int
4051        guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
4052                                                              const char *device);
4053
4054       This enable skinny metadata extent refs.
4055
4056       This function returns 0 on success or -1 on error.
4057
4058       This function depends on the feature "btrfs".  See also
4059       "guestfs_feature_available".
4060
4061       (Added in 1.29.29)
4062
4063   guestfs_btrfstune_seeding
4064        int
4065        guestfs_btrfstune_seeding (guestfs_h *g,
4066                                   const char *device,
4067                                   int seeding);
4068
4069       Enable seeding of a btrfs device, this will force a fs readonly so that
4070       you can use it to build other filesystems.
4071
4072       This function returns 0 on success or -1 on error.
4073
4074       This function depends on the feature "btrfs".  See also
4075       "guestfs_feature_available".
4076
4077       (Added in 1.29.29)
4078
4079   guestfs_c_pointer
4080        int64_t
4081        guestfs_c_pointer (guestfs_h *g);
4082
4083       In non-C language bindings, this allows you to retrieve the underlying
4084       C pointer to the handle (ie. "guestfs_h *").  The purpose of this is to
4085       allow other libraries to interwork with libguestfs.
4086
4087       On error this function returns -1.
4088
4089       (Added in 1.29.17)
4090
4091   guestfs_canonical_device_name
4092        char *
4093        guestfs_canonical_device_name (guestfs_h *g,
4094                                       const char *device);
4095
4096       This utility function is useful when displaying device names to the
4097       user.  It takes a number of irregular device names and returns them in
4098       a consistent format:
4099
4100       /dev/hdX
4101       /dev/vdX
4102           These are returned as /dev/sdX.  Note this works for device names
4103           and partition names.  This is approximately the reverse of the
4104           algorithm described in "BLOCK DEVICE NAMING".
4105
4106       /dev/mapper/VG-LV
4107       /dev/dm-N
4108           Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
4109
4110       Other strings are returned unmodified.
4111
4112       This function returns a string, or NULL on error.  The caller must free
4113       the returned string after use.
4114
4115       (Added in 1.19.7)
4116
4117   guestfs_cap_get_file
4118        char *
4119        guestfs_cap_get_file (guestfs_h *g,
4120                              const char *path);
4121
4122       This function returns the Linux capabilities attached to "path".  The
4123       capabilities set is returned in text form (see cap_to_text(3)).
4124
4125       If no capabilities are attached to a file, an empty string is returned.
4126
4127       This function returns a string, or NULL on error.  The caller must free
4128       the returned string after use.
4129
4130       This function depends on the feature "linuxcaps".  See also
4131       "guestfs_feature_available".
4132
4133       (Added in 1.19.63)
4134
4135   guestfs_cap_set_file
4136        int
4137        guestfs_cap_set_file (guestfs_h *g,
4138                              const char *path,
4139                              const char *cap);
4140
4141       This function sets the Linux capabilities attached to "path".  The
4142       capabilities set "cap" should be passed in text form (see
4143       cap_from_text(3)).
4144
4145       This function returns 0 on success or -1 on error.
4146
4147       This function depends on the feature "linuxcaps".  See also
4148       "guestfs_feature_available".
4149
4150       (Added in 1.19.63)
4151
4152   guestfs_case_sensitive_path
4153        char *
4154        guestfs_case_sensitive_path (guestfs_h *g,
4155                                     const char *path);
4156
4157       This can be used to resolve case insensitive paths on a filesystem
4158       which is case sensitive.  The use case is to resolve paths which you
4159       have read from Windows configuration files or the Windows Registry, to
4160       the true path.
4161
4162       The command handles a peculiarity of the Linux ntfs-3g filesystem
4163       driver (and probably others), which is that although the underlying
4164       filesystem is case-insensitive, the driver exports the filesystem to
4165       Linux as case-sensitive.
4166
4167       One consequence of this is that special directories such as C:\windows
4168       may appear as /WINDOWS or /windows (or other things) depending on the
4169       precise details of how they were created.  In Windows itself this would
4170       not be a problem.
4171
4172       Bug or feature?  You decide:
4173       https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4174
4175       "guestfs_case_sensitive_path" attempts to resolve the true case of each
4176       element in the path. It will return a resolved path if either the full
4177       path or its parent directory exists. If the parent directory exists but
4178       the full path does not, the case of the parent directory will be
4179       correctly resolved, and the remainder appended unmodified. For example,
4180       if the file "/Windows/System32/netkvm.sys" exists:
4181
4182       "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4183           "Windows/System32/netkvm.sys"
4184
4185       "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4186           "Windows/System32/NoSuchFile"
4187
4188       "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4189           ERROR
4190
4191       Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4192       cannot be used to check for the existence of a file.
4193
4194       Note: This function does not handle drive names, backslashes etc.
4195
4196       See also "guestfs_realpath".
4197
4198       This function returns a string, or NULL on error.  The caller must free
4199       the returned string after use.
4200
4201       (Added in 1.0.75)
4202
4203   guestfs_cat
4204        char *
4205        guestfs_cat (guestfs_h *g,
4206                     const char *path);
4207
4208       Return the contents of the file named "path".
4209
4210       Because, in C, this function returns a "char *", there is no way to
4211       differentiate between a "\0" character in a file and end of string.  To
4212       handle binary files, use the "guestfs_read_file" or "guestfs_download"
4213       functions.
4214
4215       This function returns a string, or NULL on error.  The caller must free
4216       the returned string after use.
4217
4218       (Added in 0.4)
4219
4220   guestfs_checksum
4221        char *
4222        guestfs_checksum (guestfs_h *g,
4223                          const char *csumtype,
4224                          const char *path);
4225
4226       This call computes the MD5, SHAx or CRC checksum of the file named
4227       "path".
4228
4229       The type of checksum to compute is given by the "csumtype" parameter
4230       which must have one of the following values:
4231
4232       "crc"
4233           Compute the cyclic redundancy check (CRC) specified by POSIX for
4234           the "cksum" command.
4235
4236       "md5"
4237           Compute the MD5 hash (using the md5sum(1) program).
4238
4239       "sha1"
4240           Compute the SHA1 hash (using the sha1sum(1) program).
4241
4242       "sha224"
4243           Compute the SHA224 hash (using the sha224sum(1) program).
4244
4245       "sha256"
4246           Compute the SHA256 hash (using the sha256sum(1) program).
4247
4248       "sha384"
4249           Compute the SHA384 hash (using the sha384sum(1) program).
4250
4251       "sha512"
4252           Compute the SHA512 hash (using the sha512sum(1) program).
4253
4254       The checksum is returned as a printable string.
4255
4256       To get the checksum for a device, use "guestfs_checksum_device".
4257
4258       To get the checksums for many files, use "guestfs_checksums_out".
4259
4260       This function returns a string, or NULL on error.  The caller must free
4261       the returned string after use.
4262
4263       (Added in 1.0.2)
4264
4265   guestfs_checksum_device
4266        char *
4267        guestfs_checksum_device (guestfs_h *g,
4268                                 const char *csumtype,
4269                                 const char *device);
4270
4271       This call computes the MD5, SHAx or CRC checksum of the contents of the
4272       device named "device".  For the types of checksums supported see the
4273       "guestfs_checksum" command.
4274
4275       This function returns a string, or NULL on error.  The caller must free
4276       the returned string after use.
4277
4278       (Added in 1.3.2)
4279
4280   guestfs_checksums_out
4281        int
4282        guestfs_checksums_out (guestfs_h *g,
4283                               const char *csumtype,
4284                               const char *directory,
4285                               const char *sumsfile);
4286
4287       This command computes the checksums of all regular files in directory
4288       and then emits a list of those checksums to the local output file
4289       "sumsfile".
4290
4291       This can be used for verifying the integrity of a virtual machine.
4292       However to be properly secure you should pay attention to the output of
4293       the checksum command (it uses the ones from GNU coreutils).  In
4294       particular when the filename is not printable, coreutils uses a special
4295       backslash syntax.  For more information, see the GNU coreutils info
4296       file.
4297
4298       This function returns 0 on success or -1 on error.
4299
4300       (Added in 1.3.7)
4301
4302   guestfs_chmod
4303        int
4304        guestfs_chmod (guestfs_h *g,
4305                       int mode,
4306                       const char *path);
4307
4308       Change the mode (permissions) of "path" to "mode".  Only numeric modes
4309       are supported.
4310
4311       Note: When using this command from guestfish, "mode" by default would
4312       be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4313       700.
4314
4315       The mode actually set is affected by the umask.
4316
4317       This function returns 0 on success or -1 on error.
4318
4319       (Added in 0.8)
4320
4321   guestfs_chown
4322        int
4323        guestfs_chown (guestfs_h *g,
4324                       int owner,
4325                       int group,
4326                       const char *path);
4327
4328       Change the file owner to "owner" and group to "group".
4329
4330       Only numeric uid and gid are supported.  If you want to use names, you
4331       will need to locate and parse the password file yourself (Augeas
4332       support makes this relatively easy).
4333
4334       This function returns 0 on success or -1 on error.
4335
4336       (Added in 0.8)
4337
4338   guestfs_clear_backend_setting
4339        int
4340        guestfs_clear_backend_setting (guestfs_h *g,
4341                                       const char *name);
4342
4343       If there is a backend setting string matching "name" or beginning with
4344       "name=", then that string is removed from the backend settings.
4345
4346       This call returns the number of strings which were removed (which may
4347       be 0, 1 or greater than 1).
4348
4349       See "BACKEND", "BACKEND SETTINGS".
4350
4351       On error this function returns -1.
4352
4353       (Added in 1.27.2)
4354
4355   guestfs_command
4356        char *
4357        guestfs_command (guestfs_h *g,
4358                         char *const *arguments);
4359
4360       This call runs a command from the guest filesystem.  The filesystem
4361       must be mounted, and must contain a compatible operating system (ie.
4362       something Linux, with the same or compatible processor architecture).
4363
4364       The single parameter is an argv-style list of arguments.  The first
4365       element is the name of the program to run.  Subsequent elements are
4366       parameters.  The list must be non-empty (ie. must contain a program
4367       name).  Note that the command runs directly, and is not invoked via the
4368       shell (see "guestfs_sh").
4369
4370       The return value is anything printed to stdout by the command.
4371
4372       If the command returns a non-zero exit status, then this function
4373       returns an error message.  The error message string is the content of
4374       stderr from the command.
4375
4376       The $PATH environment variable will contain at least /usr/bin and /bin.
4377       If you require a program from another location, you should provide the
4378       full path in the first parameter.
4379
4380       Shared libraries and data files required by the program must be
4381       available on filesystems which are mounted in the correct places.  It
4382       is the caller’s responsibility to ensure all filesystems that are
4383       needed are mounted at the right locations.
4384
4385       This function returns a string, or NULL on error.  The caller must free
4386       the returned string after use.
4387
4388       Because of the message protocol, there is a transfer limit of somewhere
4389       between 2MB and 4MB.  See "PROTOCOL LIMITS".
4390
4391       (Added in 1.9.1)
4392
4393   guestfs_command_lines
4394        char **
4395        guestfs_command_lines (guestfs_h *g,
4396                               char *const *arguments);
4397
4398       This is the same as "guestfs_command", but splits the result into a
4399       list of lines.
4400
4401       See also: "guestfs_sh_lines"
4402
4403       This function returns a NULL-terminated array of strings (like
4404       environ(3)), or NULL if there was an error.  The caller must free the
4405       strings and the array after use.
4406
4407       Because of the message protocol, there is a transfer limit of somewhere
4408       between 2MB and 4MB.  See "PROTOCOL LIMITS".
4409
4410       (Added in 1.9.1)
4411
4412   guestfs_compress_device_out
4413        int
4414        guestfs_compress_device_out (guestfs_h *g,
4415                                     const char *ctype,
4416                                     const char *device,
4417                                     const char *zdevice,
4418                                     ...);
4419
4420       You may supply a list of optional arguments to this call.  Use zero or
4421       more of the following pairs of parameters, and terminate the list with
4422       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4423
4424        GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4425
4426       This command compresses "device" and writes it out to the local file
4427       "zdevice".
4428
4429       The "ctype" and optional "level" parameters have the same meaning as in
4430       "guestfs_compress_out".
4431
4432       This function returns 0 on success or -1 on error.
4433
4434       (Added in 1.13.15)
4435
4436   guestfs_compress_device_out_va
4437        int
4438        guestfs_compress_device_out_va (guestfs_h *g,
4439                                        const char *ctype,
4440                                        const char *device,
4441                                        const char *zdevice,
4442                                        va_list args);
4443
4444       This is the "va_list variant" of "guestfs_compress_device_out".
4445
4446       See "CALLS WITH OPTIONAL ARGUMENTS".
4447
4448   guestfs_compress_device_out_argv
4449        int
4450        guestfs_compress_device_out_argv (guestfs_h *g,
4451                                          const char *ctype,
4452                                          const char *device,
4453                                          const char *zdevice,
4454                                          const struct guestfs_compress_device_out_argv *optargs);
4455
4456       This is the "argv variant" of "guestfs_compress_device_out".
4457
4458       See "CALLS WITH OPTIONAL ARGUMENTS".
4459
4460   guestfs_compress_out
4461        int
4462        guestfs_compress_out (guestfs_h *g,
4463                              const char *ctype,
4464                              const char *file,
4465                              const char *zfile,
4466                              ...);
4467
4468       You may supply a list of optional arguments to this call.  Use zero or
4469       more of the following pairs of parameters, and terminate the list with
4470       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4471
4472        GUESTFS_COMPRESS_OUT_LEVEL, int level,
4473
4474       This command compresses file and writes it out to the local file zfile.
4475
4476       The compression program used is controlled by the "ctype" parameter.
4477       Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4478       Some compression types may not be supported by particular builds of
4479       libguestfs, in which case you will get an error containing the
4480       substring "not supported".
4481
4482       The optional "level" parameter controls compression level.  The meaning
4483       and default for this parameter depends on the compression program being
4484       used.
4485
4486       This function returns 0 on success or -1 on error.
4487
4488       (Added in 1.13.15)
4489
4490   guestfs_compress_out_va
4491        int
4492        guestfs_compress_out_va (guestfs_h *g,
4493                                 const char *ctype,
4494                                 const char *file,
4495                                 const char *zfile,
4496                                 va_list args);
4497
4498       This is the "va_list variant" of "guestfs_compress_out".
4499
4500       See "CALLS WITH OPTIONAL ARGUMENTS".
4501
4502   guestfs_compress_out_argv
4503        int
4504        guestfs_compress_out_argv (guestfs_h *g,
4505                                   const char *ctype,
4506                                   const char *file,
4507                                   const char *zfile,
4508                                   const struct guestfs_compress_out_argv *optargs);
4509
4510       This is the "argv variant" of "guestfs_compress_out".
4511
4512       See "CALLS WITH OPTIONAL ARGUMENTS".
4513
4514   guestfs_config
4515        int
4516        guestfs_config (guestfs_h *g,
4517                        const char *hvparam,
4518                        const char *hvvalue);
4519
4520       This can be used to add arbitrary hypervisor parameters of the form
4521       -param value.  Actually it’s not quite arbitrary - we prevent you from
4522       setting some parameters which would interfere with parameters that we
4523       use.
4524
4525       The first character of "hvparam" string must be a "-" (dash).
4526
4527       "hvvalue" can be NULL.
4528
4529       This function returns 0 on success or -1 on error.
4530
4531       (Added in 0.3)
4532
4533   guestfs_copy_attributes
4534        int
4535        guestfs_copy_attributes (guestfs_h *g,
4536                                 const char *src,
4537                                 const char *dest,
4538                                 ...);
4539
4540       You may supply a list of optional arguments to this call.  Use zero or
4541       more of the following pairs of parameters, and terminate the list with
4542       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4543
4544        GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4545        GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4546        GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4547        GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4548
4549       Copy the attributes of a path (which can be a file or a directory) to
4550       another path.
4551
4552       By default no attribute is copied, so make sure to specify any (or
4553       "all" to copy everything).
4554
4555       The optional arguments specify which attributes can be copied:
4556
4557       "mode"
4558           Copy part of the file mode from "source" to "destination". Only the
4559           UNIX permissions and the sticky/setuid/setgid bits can be copied.
4560
4561       "xattributes"
4562           Copy the Linux extended attributes (xattrs) from "source" to
4563           "destination".  This flag does nothing if the linuxxattrs feature
4564           is not available (see "guestfs_feature_available").
4565
4566       "ownership"
4567           Copy the owner uid and the group gid of "source" to "destination".
4568
4569       "all"
4570           Copy all the attributes from "source" to "destination". Enabling it
4571           enables all the other flags, if they are not specified already.
4572
4573       This function returns 0 on success or -1 on error.
4574
4575       (Added in 1.25.21)
4576
4577   guestfs_copy_attributes_va
4578        int
4579        guestfs_copy_attributes_va (guestfs_h *g,
4580                                    const char *src,
4581                                    const char *dest,
4582                                    va_list args);
4583
4584       This is the "va_list variant" of "guestfs_copy_attributes".
4585
4586       See "CALLS WITH OPTIONAL ARGUMENTS".
4587
4588   guestfs_copy_attributes_argv
4589        int
4590        guestfs_copy_attributes_argv (guestfs_h *g,
4591                                      const char *src,
4592                                      const char *dest,
4593                                      const struct guestfs_copy_attributes_argv *optargs);
4594
4595       This is the "argv variant" of "guestfs_copy_attributes".
4596
4597       See "CALLS WITH OPTIONAL ARGUMENTS".
4598
4599   guestfs_copy_device_to_device
4600        int
4601        guestfs_copy_device_to_device (guestfs_h *g,
4602                                       const char *src,
4603                                       const char *dest,
4604                                       ...);
4605
4606       You may supply a list of optional arguments to this call.  Use zero or
4607       more of the following pairs of parameters, and terminate the list with
4608       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4609
4610        GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4611        GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4612        GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4613        GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4614        GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4615
4616       The four calls "guestfs_copy_device_to_device",
4617       "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4618       "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4619       a destination (device|file).
4620
4621       Partial copies can be made since you can specify optionally the source
4622       offset, destination offset and size to copy.  These values are all
4623       specified in bytes.  If not given, the offsets both default to zero,
4624       and the size defaults to copying as much as possible until we hit the
4625       end of the source.
4626
4627       The source and destination may be the same object.  However overlapping
4628       regions may not be copied correctly.
4629
4630       If the destination is a file, it is created if required.  If the
4631       destination file is not large enough, it is extended.
4632
4633       If the destination is a file and the "append" flag is not set, then the
4634       destination file is truncated.  If the "append" flag is set, then the
4635       copy appends to the destination file.  The "append" flag currently
4636       cannot be set for devices.
4637
4638       If the "sparse" flag is true then the call avoids writing blocks that
4639       contain only zeroes, which can help in some situations where the
4640       backing disk is thin-provisioned.  Note that unless the target is
4641       already zeroed, using this option will result in incorrect copying.
4642
4643       This function returns 0 on success or -1 on error.
4644
4645       This long-running command can generate progress notification messages
4646       so that the caller can display a progress bar or indicator.  To receive
4647       these messages, the caller must register a progress event callback.
4648       See "GUESTFS_EVENT_PROGRESS".
4649
4650       (Added in 1.13.25)
4651
4652   guestfs_copy_device_to_device_va
4653        int
4654        guestfs_copy_device_to_device_va (guestfs_h *g,
4655                                          const char *src,
4656                                          const char *dest,
4657                                          va_list args);
4658
4659       This is the "va_list variant" of "guestfs_copy_device_to_device".
4660
4661       See "CALLS WITH OPTIONAL ARGUMENTS".
4662
4663   guestfs_copy_device_to_device_argv
4664        int
4665        guestfs_copy_device_to_device_argv (guestfs_h *g,
4666                                            const char *src,
4667                                            const char *dest,
4668                                            const struct guestfs_copy_device_to_device_argv *optargs);
4669
4670       This is the "argv variant" of "guestfs_copy_device_to_device".
4671
4672       See "CALLS WITH OPTIONAL ARGUMENTS".
4673
4674   guestfs_copy_device_to_file
4675        int
4676        guestfs_copy_device_to_file (guestfs_h *g,
4677                                     const char *src,
4678                                     const char *dest,
4679                                     ...);
4680
4681       You may supply a list of optional arguments to this call.  Use zero or
4682       more of the following pairs of parameters, and terminate the list with
4683       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4684
4685        GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4686        GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4687        GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4688        GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4689        GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4690
4691       See "guestfs_copy_device_to_device" for a general overview of this
4692       call.
4693
4694       This function returns 0 on success or -1 on error.
4695
4696       This long-running command can generate progress notification messages
4697       so that the caller can display a progress bar or indicator.  To receive
4698       these messages, the caller must register a progress event callback.
4699       See "GUESTFS_EVENT_PROGRESS".
4700
4701       (Added in 1.13.25)
4702
4703   guestfs_copy_device_to_file_va
4704        int
4705        guestfs_copy_device_to_file_va (guestfs_h *g,
4706                                        const char *src,
4707                                        const char *dest,
4708                                        va_list args);
4709
4710       This is the "va_list variant" of "guestfs_copy_device_to_file".
4711
4712       See "CALLS WITH OPTIONAL ARGUMENTS".
4713
4714   guestfs_copy_device_to_file_argv
4715        int
4716        guestfs_copy_device_to_file_argv (guestfs_h *g,
4717                                          const char *src,
4718                                          const char *dest,
4719                                          const struct guestfs_copy_device_to_file_argv *optargs);
4720
4721       This is the "argv variant" of "guestfs_copy_device_to_file".
4722
4723       See "CALLS WITH OPTIONAL ARGUMENTS".
4724
4725   guestfs_copy_file_to_device
4726        int
4727        guestfs_copy_file_to_device (guestfs_h *g,
4728                                     const char *src,
4729                                     const char *dest,
4730                                     ...);
4731
4732       You may supply a list of optional arguments to this call.  Use zero or
4733       more of the following pairs of parameters, and terminate the list with
4734       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4735
4736        GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4737        GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4738        GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4739        GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4740        GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4741
4742       See "guestfs_copy_device_to_device" for a general overview of this
4743       call.
4744
4745       This function returns 0 on success or -1 on error.
4746
4747       This long-running command can generate progress notification messages
4748       so that the caller can display a progress bar or indicator.  To receive
4749       these messages, the caller must register a progress event callback.
4750       See "GUESTFS_EVENT_PROGRESS".
4751
4752       (Added in 1.13.25)
4753
4754   guestfs_copy_file_to_device_va
4755        int
4756        guestfs_copy_file_to_device_va (guestfs_h *g,
4757                                        const char *src,
4758                                        const char *dest,
4759                                        va_list args);
4760
4761       This is the "va_list variant" of "guestfs_copy_file_to_device".
4762
4763       See "CALLS WITH OPTIONAL ARGUMENTS".
4764
4765   guestfs_copy_file_to_device_argv
4766        int
4767        guestfs_copy_file_to_device_argv (guestfs_h *g,
4768                                          const char *src,
4769                                          const char *dest,
4770                                          const struct guestfs_copy_file_to_device_argv *optargs);
4771
4772       This is the "argv variant" of "guestfs_copy_file_to_device".
4773
4774       See "CALLS WITH OPTIONAL ARGUMENTS".
4775
4776   guestfs_copy_file_to_file
4777        int
4778        guestfs_copy_file_to_file (guestfs_h *g,
4779                                   const char *src,
4780                                   const char *dest,
4781                                   ...);
4782
4783       You may supply a list of optional arguments to this call.  Use zero or
4784       more of the following pairs of parameters, and terminate the list with
4785       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4786
4787        GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4788        GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4789        GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4790        GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4791        GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4792
4793       See "guestfs_copy_device_to_device" for a general overview of this
4794       call.
4795
4796       This is not the function you want for copying files.  This is for
4797       copying blocks within existing files.  See "guestfs_cp", "guestfs_cp_a"
4798       and "guestfs_mv" for general file copying and moving functions.
4799
4800       This function returns 0 on success or -1 on error.
4801
4802       This long-running command can generate progress notification messages
4803       so that the caller can display a progress bar or indicator.  To receive
4804       these messages, the caller must register a progress event callback.
4805       See "GUESTFS_EVENT_PROGRESS".
4806
4807       (Added in 1.13.25)
4808
4809   guestfs_copy_file_to_file_va
4810        int
4811        guestfs_copy_file_to_file_va (guestfs_h *g,
4812                                      const char *src,
4813                                      const char *dest,
4814                                      va_list args);
4815
4816       This is the "va_list variant" of "guestfs_copy_file_to_file".
4817
4818       See "CALLS WITH OPTIONAL ARGUMENTS".
4819
4820   guestfs_copy_file_to_file_argv
4821        int
4822        guestfs_copy_file_to_file_argv (guestfs_h *g,
4823                                        const char *src,
4824                                        const char *dest,
4825                                        const struct guestfs_copy_file_to_file_argv *optargs);
4826
4827       This is the "argv variant" of "guestfs_copy_file_to_file".
4828
4829       See "CALLS WITH OPTIONAL ARGUMENTS".
4830
4831   guestfs_copy_in
4832        int
4833        guestfs_copy_in (guestfs_h *g,
4834                         const char *localpath,
4835                         const char *remotedir);
4836
4837       "guestfs_copy_in" copies local files or directories recursively into
4838       the disk image, placing them in the directory called "remotedir" (which
4839       must exist).
4840
4841       Wildcards cannot be used.
4842
4843       This function returns 0 on success or -1 on error.
4844
4845       (Added in 1.29.24)
4846
4847   guestfs_copy_out
4848        int
4849        guestfs_copy_out (guestfs_h *g,
4850                          const char *remotepath,
4851                          const char *localdir);
4852
4853       "guestfs_copy_out" copies remote files or directories recursively out
4854       of the disk image, placing them on the host disk in a local directory
4855       called "localdir" (which must exist).
4856
4857       To download to the current directory, use "." as in:
4858
4859        C<guestfs_copy_out> /home .
4860
4861       Wildcards cannot be used.
4862
4863       This function returns 0 on success or -1 on error.
4864
4865       (Added in 1.29.24)
4866
4867   guestfs_copy_size
4868        int
4869        guestfs_copy_size (guestfs_h *g,
4870                           const char *src,
4871                           const char *dest,
4872                           int64_t size);
4873
4874       This function is deprecated.  In new code, use the
4875       "guestfs_copy_device_to_device" call instead.
4876
4877       Deprecated functions will not be removed from the API, but the fact
4878       that they are deprecated indicates that there are problems with correct
4879       use of these functions.
4880
4881       This command copies exactly "size" bytes from one source device or file
4882       "src" to another destination device or file "dest".
4883
4884       Note this will fail if the source is too short or if the destination is
4885       not large enough.
4886
4887       This function returns 0 on success or -1 on error.
4888
4889       This long-running command can generate progress notification messages
4890       so that the caller can display a progress bar or indicator.  To receive
4891       these messages, the caller must register a progress event callback.
4892       See "GUESTFS_EVENT_PROGRESS".
4893
4894       (Added in 1.0.87)
4895
4896   guestfs_cp
4897        int
4898        guestfs_cp (guestfs_h *g,
4899                    const char *src,
4900                    const char *dest);
4901
4902       This copies a file from "src" to "dest" where "dest" is either a
4903       destination filename or destination directory.
4904
4905       This function returns 0 on success or -1 on error.
4906
4907       (Added in 1.0.18)
4908
4909   guestfs_cp_a
4910        int
4911        guestfs_cp_a (guestfs_h *g,
4912                      const char *src,
4913                      const char *dest);
4914
4915       This copies a file or directory from "src" to "dest" recursively using
4916       the "cp -a" command.
4917
4918       This function returns 0 on success or -1 on error.
4919
4920       (Added in 1.0.18)
4921
4922   guestfs_cp_r
4923        int
4924        guestfs_cp_r (guestfs_h *g,
4925                      const char *src,
4926                      const char *dest);
4927
4928       This copies a file or directory from "src" to "dest" recursively using
4929       the "cp -rP" command.
4930
4931       Most users should use "guestfs_cp_a" instead.  This command is useful
4932       when you don't want to preserve permissions, because the target
4933       filesystem does not support it (primarily when writing to DOS FAT
4934       filesystems).
4935
4936       This function returns 0 on success or -1 on error.
4937
4938       (Added in 1.21.38)
4939
4940   guestfs_cpio_out
4941        int
4942        guestfs_cpio_out (guestfs_h *g,
4943                          const char *directory,
4944                          const char *cpiofile,
4945                          ...);
4946
4947       You may supply a list of optional arguments to this call.  Use zero or
4948       more of the following pairs of parameters, and terminate the list with
4949       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
4950
4951        GUESTFS_CPIO_OUT_FORMAT, const char *format,
4952
4953       This command packs the contents of directory and downloads it to local
4954       file "cpiofile".
4955
4956       The optional "format" parameter can be used to select the format.  Only
4957       the following formats are currently permitted:
4958
4959       "newc"
4960           New (SVR4) portable format.  This format happens to be compatible
4961           with the cpio-like format used by the Linux kernel for initramfs.
4962
4963           This is the default format.
4964
4965       "crc"
4966           New (SVR4) portable format with a checksum.
4967
4968       This function returns 0 on success or -1 on error.
4969
4970       (Added in 1.27.9)
4971
4972   guestfs_cpio_out_va
4973        int
4974        guestfs_cpio_out_va (guestfs_h *g,
4975                             const char *directory,
4976                             const char *cpiofile,
4977                             va_list args);
4978
4979       This is the "va_list variant" of "guestfs_cpio_out".
4980
4981       See "CALLS WITH OPTIONAL ARGUMENTS".
4982
4983   guestfs_cpio_out_argv
4984        int
4985        guestfs_cpio_out_argv (guestfs_h *g,
4986                               const char *directory,
4987                               const char *cpiofile,
4988                               const struct guestfs_cpio_out_argv *optargs);
4989
4990       This is the "argv variant" of "guestfs_cpio_out".
4991
4992       See "CALLS WITH OPTIONAL ARGUMENTS".
4993
4994   guestfs_cryptsetup_close
4995        int
4996        guestfs_cryptsetup_close (guestfs_h *g,
4997                                  const char *device);
4998
4999       This closes an encrypted device that was created earlier by
5000       "guestfs_cryptsetup_open".  The "device" parameter must be the name of
5001       the mapping device (ie. /dev/mapper/mapname) and not the name of the
5002       underlying block device.
5003
5004       This function returns 0 on success or -1 on error.
5005
5006       This function depends on the feature "luks".  See also
5007       "guestfs_feature_available".
5008
5009       (Added in 1.43.2)
5010
5011   guestfs_cryptsetup_open
5012        int
5013        guestfs_cryptsetup_open (guestfs_h *g,
5014                                 const char *device,
5015                                 const char *key,
5016                                 const char *mapname,
5017                                 ...);
5018
5019       You may supply a list of optional arguments to this call.  Use zero or
5020       more of the following pairs of parameters, and terminate the list with
5021       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
5022
5023        GUESTFS_CRYPTSETUP_OPEN_READONLY, int readonly,
5024        GUESTFS_CRYPTSETUP_OPEN_CRYPTTYPE, const char *crypttype,
5025
5026       This command opens a block device which has been encrypted according to
5027       the Linux Unified Key Setup (LUKS) standard, Windows BitLocker, or some
5028       other types.
5029
5030       "device" is the encrypted block device or partition.
5031
5032       The caller must supply one of the keys associated with the encrypted
5033       block device, in the "key" parameter.
5034
5035       This creates a new block device called /dev/mapper/mapname.  Reads and
5036       writes to this block device are decrypted from and encrypted to the
5037       underlying "device" respectively.
5038
5039       "mapname" cannot be "control" because that name is reserved by device-
5040       mapper.
5041
5042       If the optional "crypttype" parameter is not present then libguestfs
5043       tries to guess the correct type (for example LUKS or BitLocker).
5044       However you can override this by specifying one of the following types:
5045
5046       "luks"
5047           A Linux LUKS device.
5048
5049       "bitlk"
5050           A Windows BitLocker device.
5051
5052       The optional "readonly" flag, if set to true, creates a read-only
5053       mapping.
5054
5055       If this block device contains LVM volume groups, then calling
5056       "guestfs_lvm_scan" with the "activate" parameter "true" will make them
5057       visible.
5058
5059       Use "guestfs_list_dm_devices" to list all device mapper devices.
5060
5061       This function returns 0 on success or -1 on error.
5062
5063       This function takes a key or passphrase parameter which could contain
5064       sensitive material.  Read the section "KEYS AND PASSPHRASES" for more
5065       information.
5066
5067       This function depends on the feature "luks".  See also
5068       "guestfs_feature_available".
5069
5070       (Added in 1.43.2)
5071
5072   guestfs_cryptsetup_open_va
5073        int
5074        guestfs_cryptsetup_open_va (guestfs_h *g,
5075                                    const char *device,
5076                                    const char *key,
5077                                    const char *mapname,
5078                                    va_list args);
5079
5080       This is the "va_list variant" of "guestfs_cryptsetup_open".
5081
5082       See "CALLS WITH OPTIONAL ARGUMENTS".
5083
5084   guestfs_cryptsetup_open_argv
5085        int
5086        guestfs_cryptsetup_open_argv (guestfs_h *g,
5087                                      const char *device,
5088                                      const char *key,
5089                                      const char *mapname,
5090                                      const struct guestfs_cryptsetup_open_argv *optargs);
5091
5092       This is the "argv variant" of "guestfs_cryptsetup_open".
5093
5094       See "CALLS WITH OPTIONAL ARGUMENTS".
5095
5096   guestfs_dd
5097        int
5098        guestfs_dd (guestfs_h *g,
5099                    const char *src,
5100                    const char *dest);
5101
5102       This function is deprecated.  In new code, use the
5103       "guestfs_copy_device_to_device" call instead.
5104
5105       Deprecated functions will not be removed from the API, but the fact
5106       that they are deprecated indicates that there are problems with correct
5107       use of these functions.
5108
5109       This command copies from one source device or file "src" to another
5110       destination device or file "dest".  Normally you would use this to copy
5111       to or from a device or partition, for example to duplicate a
5112       filesystem.
5113
5114       If the destination is a device, it must be as large or larger than the
5115       source file or device, otherwise the copy will fail.  This command
5116       cannot do partial copies (see "guestfs_copy_device_to_device").
5117
5118       This function returns 0 on success or -1 on error.
5119
5120       (Added in 1.0.80)
5121
5122   guestfs_device_index
5123        int
5124        guestfs_device_index (guestfs_h *g,
5125                              const char *device);
5126
5127       This function takes a device name (eg. "/dev/sdb") and returns the
5128       index of the device in the list of devices.
5129
5130       Index numbers start from 0.  The named device must exist, for example
5131       as a string returned from "guestfs_list_devices".
5132
5133       See also "guestfs_list_devices", "guestfs_part_to_dev".
5134
5135       On error this function returns -1.
5136
5137       (Added in 1.19.7)
5138
5139   guestfs_df
5140        char *
5141        guestfs_df (guestfs_h *g);
5142
5143       This command runs the df(1) command to report disk space used.
5144
5145       This command is mostly useful for interactive sessions.  It is not
5146       intended that you try to parse the output string.  Use
5147       "guestfs_statvfs" from programs.
5148
5149       This function returns a string, or NULL on error.  The caller must free
5150       the returned string after use.
5151
5152       (Added in 1.0.54)
5153
5154   guestfs_df_h
5155        char *
5156        guestfs_df_h (guestfs_h *g);
5157
5158       This command runs the "df -h" command to report disk space used in
5159       human-readable format.
5160
5161       This command is mostly useful for interactive sessions.  It is not
5162       intended that you try to parse the output string.  Use
5163       "guestfs_statvfs" from programs.
5164
5165       This function returns a string, or NULL on error.  The caller must free
5166       the returned string after use.
5167
5168       (Added in 1.0.54)
5169
5170   guestfs_disk_create
5171        int
5172        guestfs_disk_create (guestfs_h *g,
5173                             const char *filename,
5174                             const char *format,
5175                             int64_t size,
5176                             ...);
5177
5178       You may supply a list of optional arguments to this call.  Use zero or
5179       more of the following pairs of parameters, and terminate the list with
5180       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
5181
5182        GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
5183        GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
5184        GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
5185        GUESTFS_DISK_CREATE_COMPAT, const char *compat,
5186        GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
5187
5188       Create a blank disk image called filename (a host file) with format
5189       "format" (usually "raw" or "qcow2").  The size is "size" bytes.
5190
5191       If used with the optional "backingfile" parameter, then a snapshot is
5192       created on top of the backing file.  In this case, "size" must be
5193       passed as "-1".  The size of the snapshot is the same as the size of
5194       the backing file, which is discovered automatically.  You are
5195       encouraged to also pass "backingformat" to describe the format of
5196       "backingfile".
5197
5198       If filename refers to a block device, then the device is formatted.
5199       The "size" is ignored since block devices have an intrinsic size.
5200
5201       The other optional parameters are:
5202
5203       "preallocation"
5204           If format is "raw", then this can be either "off" (or "sparse") or
5205           "full" to create a sparse or fully allocated file respectively.
5206           The default is "off".
5207
5208           If format is "qcow2", then this can be "off" (or "sparse"),
5209           "metadata" or "full".  Preallocating metadata can be faster when
5210           doing lots of writes, but uses more space.  The default is "off".
5211
5212       "compat"
5213           "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5214           supported by qemu ≥ 1.1.
5215
5216       "clustersize"
5217           "qcow2" only: Change the qcow2 cluster size.  The default is 65536
5218           (bytes) and this setting may be any power of two between 512 and
5219           2097152.
5220
5221       Note that this call does not add the new disk to the handle.  You may
5222       need to call "guestfs_add_drive_opts" separately.
5223
5224       This function returns 0 on success or -1 on error.
5225
5226       (Added in 1.25.31)
5227
5228   guestfs_disk_create_va
5229        int
5230        guestfs_disk_create_va (guestfs_h *g,
5231                                const char *filename,
5232                                const char *format,
5233                                int64_t size,
5234                                va_list args);
5235
5236       This is the "va_list variant" of "guestfs_disk_create".
5237
5238       See "CALLS WITH OPTIONAL ARGUMENTS".
5239
5240   guestfs_disk_create_argv
5241        int
5242        guestfs_disk_create_argv (guestfs_h *g,
5243                                  const char *filename,
5244                                  const char *format,
5245                                  int64_t size,
5246                                  const struct guestfs_disk_create_argv *optargs);
5247
5248       This is the "argv variant" of "guestfs_disk_create".
5249
5250       See "CALLS WITH OPTIONAL ARGUMENTS".
5251
5252   guestfs_disk_format
5253        char *
5254        guestfs_disk_format (guestfs_h *g,
5255                             const char *filename);
5256
5257       Detect and return the format of the disk image called filename.
5258       filename can also be a host device, etc.  If the format of the image
5259       could not be detected, then "unknown" is returned.
5260
5261       Note that detecting the disk format can be insecure under some
5262       circumstances.  See "CVE-2010-3851".
5263
5264       See also: "DISK IMAGE FORMATS"
5265
5266       This function returns a string, or NULL on error.  The caller must free
5267       the returned string after use.
5268
5269       (Added in 1.19.38)
5270
5271   guestfs_disk_has_backing_file
5272        int
5273        guestfs_disk_has_backing_file (guestfs_h *g,
5274                                       const char *filename);
5275
5276       Detect and return whether the disk image filename has a backing file.
5277
5278       Note that detecting disk features can be insecure under some
5279       circumstances.  See "CVE-2010-3851".
5280
5281       This function returns a C truth value on success or -1 on error.
5282
5283       (Added in 1.19.39)
5284
5285   guestfs_disk_virtual_size
5286        int64_t
5287        guestfs_disk_virtual_size (guestfs_h *g,
5288                                   const char *filename);
5289
5290       Detect and return the virtual size in bytes of the disk image called
5291       filename.
5292
5293       Note that detecting disk features can be insecure under some
5294       circumstances.  See "CVE-2010-3851".
5295
5296       On error this function returns -1.
5297
5298       (Added in 1.19.39)
5299
5300   guestfs_dmesg
5301        char *
5302        guestfs_dmesg (guestfs_h *g);
5303
5304       This returns the kernel messages (dmesg(1) output) from the guest
5305       kernel.  This is sometimes useful for extended debugging of problems.
5306
5307       Another way to get the same information is to enable verbose messages
5308       with "guestfs_set_verbose" or by setting the environment variable
5309       "LIBGUESTFS_DEBUG=1" before running the program.
5310
5311       This function returns a string, or NULL on error.  The caller must free
5312       the returned string after use.
5313
5314       (Added in 1.0.18)
5315
5316   guestfs_download
5317        int
5318        guestfs_download (guestfs_h *g,
5319                          const char *remotefilename,
5320                          const char *filename);
5321
5322       Download file remotefilename and save it as filename on the local
5323       machine.
5324
5325       filename can also be a named pipe.
5326
5327       See also "guestfs_upload", "guestfs_cat".
5328
5329       This function returns 0 on success or -1 on error.
5330
5331       This long-running command can generate progress notification messages
5332       so that the caller can display a progress bar or indicator.  To receive
5333       these messages, the caller must register a progress event callback.
5334       See "GUESTFS_EVENT_PROGRESS".
5335
5336       (Added in 1.0.2)
5337
5338   guestfs_download_blocks
5339        int
5340        guestfs_download_blocks (guestfs_h *g,
5341                                 const char *device,
5342                                 int64_t start,
5343                                 int64_t stop,
5344                                 const char *filename,
5345                                 ...);
5346
5347       You may supply a list of optional arguments to this call.  Use zero or
5348       more of the following pairs of parameters, and terminate the list with
5349       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
5350
5351        GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5352
5353       Download the data units from start address to stop from the disk
5354       partition (eg. /dev/sda1) and save them as filename on the local
5355       machine.
5356
5357       The use of this API on sparse disk image formats such as QCOW, may
5358       result in large zero-filled files downloaded on the host.
5359
5360       The size of a data unit varies across filesystem implementations.  On
5361       NTFS filesystems data units are referred as clusters while on ExtX ones
5362       they are referred as fragments.
5363
5364       If the optional "unallocated" flag is true (default is false), only the
5365       unallocated blocks will be extracted.  This is useful to detect hidden
5366       data or to retrieve deleted files which data units have not been
5367       overwritten yet.
5368
5369       This function returns 0 on success or -1 on error.
5370
5371       This long-running command can generate progress notification messages
5372       so that the caller can display a progress bar or indicator.  To receive
5373       these messages, the caller must register a progress event callback.
5374       See "GUESTFS_EVENT_PROGRESS".
5375
5376       This function depends on the feature "sleuthkit".  See also
5377       "guestfs_feature_available".
5378
5379       (Added in 1.33.45)
5380
5381   guestfs_download_blocks_va
5382        int
5383        guestfs_download_blocks_va (guestfs_h *g,
5384                                    const char *device,
5385                                    int64_t start,
5386                                    int64_t stop,
5387                                    const char *filename,
5388                                    va_list args);
5389
5390       This is the "va_list variant" of "guestfs_download_blocks".
5391
5392       See "CALLS WITH OPTIONAL ARGUMENTS".
5393
5394   guestfs_download_blocks_argv
5395        int
5396        guestfs_download_blocks_argv (guestfs_h *g,
5397                                      const char *device,
5398                                      int64_t start,
5399                                      int64_t stop,
5400                                      const char *filename,
5401                                      const struct guestfs_download_blocks_argv *optargs);
5402
5403       This is the "argv variant" of "guestfs_download_blocks".
5404
5405       See "CALLS WITH OPTIONAL ARGUMENTS".
5406
5407   guestfs_download_inode
5408        int
5409        guestfs_download_inode (guestfs_h *g,
5410                                const char *device,
5411                                int64_t inode,
5412                                const char *filename);
5413
5414       Download a file given its inode from the disk partition (eg. /dev/sda1)
5415       and save it as filename on the local machine.
5416
5417       It is not required to mount the disk to run this command.
5418
5419       The command is capable of downloading deleted or inaccessible files.
5420
5421       This function returns 0 on success or -1 on error.
5422
5423       This long-running command can generate progress notification messages
5424       so that the caller can display a progress bar or indicator.  To receive
5425       these messages, the caller must register a progress event callback.
5426       See "GUESTFS_EVENT_PROGRESS".
5427
5428       This function depends on the feature "sleuthkit".  See also
5429       "guestfs_feature_available".
5430
5431       (Added in 1.33.14)
5432
5433   guestfs_download_offset
5434        int
5435        guestfs_download_offset (guestfs_h *g,
5436                                 const char *remotefilename,
5437                                 const char *filename,
5438                                 int64_t offset,
5439                                 int64_t size);
5440
5441       Download file remotefilename and save it as filename on the local
5442       machine.
5443
5444       remotefilename is read for "size" bytes starting at "offset" (this
5445       region must be within the file or device).
5446
5447       Note that there is no limit on the amount of data that can be
5448       downloaded with this call, unlike with "guestfs_pread", and this call
5449       always reads the full amount unless an error occurs.
5450
5451       See also "guestfs_download", "guestfs_pread".
5452
5453       This function returns 0 on success or -1 on error.
5454
5455       This long-running command can generate progress notification messages
5456       so that the caller can display a progress bar or indicator.  To receive
5457       these messages, the caller must register a progress event callback.
5458       See "GUESTFS_EVENT_PROGRESS".
5459
5460       (Added in 1.5.17)
5461
5462   guestfs_drop_caches
5463        int
5464        guestfs_drop_caches (guestfs_h *g,
5465                             int whattodrop);
5466
5467       This instructs the guest kernel to drop its page cache, and/or dentries
5468       and inode caches.  The parameter "whattodrop" tells the kernel what
5469       precisely to drop, see https://linux-mm.org/Drop_Caches
5470
5471       Setting "whattodrop" to 3 should drop everything.
5472
5473       This automatically calls sync(2) before the operation, so that the
5474       maximum guest memory is freed.
5475
5476       This function returns 0 on success or -1 on error.
5477
5478       (Added in 1.0.18)
5479
5480   guestfs_du
5481        int64_t
5482        guestfs_du (guestfs_h *g,
5483                    const char *path);
5484
5485       This command runs the "du -s" command to estimate file space usage for
5486       "path".
5487
5488       "path" can be a file or a directory.  If "path" is a directory then the
5489       estimate includes the contents of the directory and all subdirectories
5490       (recursively).
5491
5492       The result is the estimated size in kilobytes (ie. units of 1024
5493       bytes).
5494
5495       On error this function returns -1.
5496
5497       This long-running command can generate progress notification messages
5498       so that the caller can display a progress bar or indicator.  To receive
5499       these messages, the caller must register a progress event callback.
5500       See "GUESTFS_EVENT_PROGRESS".
5501
5502       (Added in 1.0.54)
5503
5504   guestfs_e2fsck
5505        int
5506        guestfs_e2fsck (guestfs_h *g,
5507                        const char *device,
5508                        ...);
5509
5510       You may supply a list of optional arguments to this call.  Use zero or
5511       more of the following pairs of parameters, and terminate the list with
5512       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
5513
5514        GUESTFS_E2FSCK_CORRECT, int correct,
5515        GUESTFS_E2FSCK_FORCEALL, int forceall,
5516
5517       This runs the ext2/ext3 filesystem checker on "device".  It can take
5518       the following optional arguments:
5519
5520       "correct"
5521           Automatically repair the file system. This option will cause e2fsck
5522           to automatically fix any filesystem problems that can be safely
5523           fixed without human intervention.
5524
5525           This option may not be specified at the same time as the "forceall"
5526           option.
5527
5528       "forceall"
5529           Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5530           used non-interactively.
5531
5532           This option may not be specified at the same time as the "correct"
5533           option.
5534
5535       This function returns 0 on success or -1 on error.
5536
5537       (Added in 1.15.17)
5538
5539   guestfs_e2fsck_va
5540        int
5541        guestfs_e2fsck_va (guestfs_h *g,
5542                           const char *device,
5543                           va_list args);
5544
5545       This is the "va_list variant" of "guestfs_e2fsck".
5546
5547       See "CALLS WITH OPTIONAL ARGUMENTS".
5548
5549   guestfs_e2fsck_argv
5550        int
5551        guestfs_e2fsck_argv (guestfs_h *g,
5552                             const char *device,
5553                             const struct guestfs_e2fsck_argv *optargs);
5554
5555       This is the "argv variant" of "guestfs_e2fsck".
5556
5557       See "CALLS WITH OPTIONAL ARGUMENTS".
5558
5559   guestfs_e2fsck_f
5560        int
5561        guestfs_e2fsck_f (guestfs_h *g,
5562                          const char *device);
5563
5564       This function is deprecated.  In new code, use the "guestfs_e2fsck"
5565       call instead.
5566
5567       Deprecated functions will not be removed from the API, but the fact
5568       that they are deprecated indicates that there are problems with correct
5569       use of these functions.
5570
5571       This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5572       checker on "device", noninteractively (-p), even if the filesystem
5573       appears to be clean (-f).
5574
5575       This function returns 0 on success or -1 on error.
5576
5577       (Added in 1.0.29)
5578
5579   guestfs_echo_daemon
5580        char *
5581        guestfs_echo_daemon (guestfs_h *g,
5582                             char *const *words);
5583
5584       This command concatenates the list of "words" passed with single spaces
5585       between them and returns the resulting string.
5586
5587       You can use this command to test the connection through to the daemon.
5588
5589       See also "guestfs_ping_daemon".
5590
5591       This function returns a string, or NULL on error.  The caller must free
5592       the returned string after use.
5593
5594       (Added in 1.0.69)
5595
5596   guestfs_egrep
5597        char **
5598        guestfs_egrep (guestfs_h *g,
5599                       const char *regex,
5600                       const char *path);
5601
5602       This function is deprecated.  In new code, use the "guestfs_grep" call
5603       instead.
5604
5605       Deprecated functions will not be removed from the API, but the fact
5606       that they are deprecated indicates that there are problems with correct
5607       use of these functions.
5608
5609       This calls the external egrep(1) program and returns the matching
5610       lines.
5611
5612       This function returns a NULL-terminated array of strings (like
5613       environ(3)), or NULL if there was an error.  The caller must free the
5614       strings and the array after use.
5615
5616       Because of the message protocol, there is a transfer limit of somewhere
5617       between 2MB and 4MB.  See "PROTOCOL LIMITS".
5618
5619       (Added in 1.0.66)
5620
5621   guestfs_egrepi
5622        char **
5623        guestfs_egrepi (guestfs_h *g,
5624                        const char *regex,
5625                        const char *path);
5626
5627       This function is deprecated.  In new code, use the "guestfs_grep" call
5628       instead.
5629
5630       Deprecated functions will not be removed from the API, but the fact
5631       that they are deprecated indicates that there are problems with correct
5632       use of these functions.
5633
5634       This calls the external "egrep -i" program and returns the matching
5635       lines.
5636
5637       This function returns a NULL-terminated array of strings (like
5638       environ(3)), or NULL if there was an error.  The caller must free the
5639       strings and the array after use.
5640
5641       Because of the message protocol, there is a transfer limit of somewhere
5642       between 2MB and 4MB.  See "PROTOCOL LIMITS".
5643
5644       (Added in 1.0.66)
5645
5646   guestfs_equal
5647        int
5648        guestfs_equal (guestfs_h *g,
5649                       const char *file1,
5650                       const char *file2);
5651
5652       This compares the two files file1 and file2 and returns true if their
5653       content is exactly equal, or false otherwise.
5654
5655       The external cmp(1) program is used for the comparison.
5656
5657       This function returns a C truth value on success or -1 on error.
5658
5659       (Added in 1.0.18)
5660
5661   guestfs_exists
5662        int
5663        guestfs_exists (guestfs_h *g,
5664                        const char *path);
5665
5666       This returns "true" if and only if there is a file, directory (or
5667       anything) with the given "path" name.
5668
5669       See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5670
5671       This function returns a C truth value on success or -1 on error.
5672
5673       (Added in 0.8)
5674
5675   guestfs_extlinux
5676        int
5677        guestfs_extlinux (guestfs_h *g,
5678                          const char *directory);
5679
5680       Install the SYSLINUX bootloader on the device mounted at directory.
5681       Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5682       used on an ext2/3/4 or btrfs filesystem.
5683
5684       The directory parameter can be either a mountpoint, or a directory
5685       within the mountpoint.
5686
5687       You also have to mark the partition as "active"
5688       ("guestfs_part_set_bootable") and a Master Boot Record must be
5689       installed (eg. using "guestfs_pwrite_device") on the first sector of
5690       the whole disk.  The SYSLINUX package comes with some suitable Master
5691       Boot Records.  See the extlinux(1) man page for further information.
5692
5693       Additional configuration can be supplied to SYSLINUX by placing a file
5694       called extlinux.conf on the filesystem under directory.  For further
5695       information about the contents of this file, see extlinux(1).
5696
5697       See also "guestfs_syslinux".
5698
5699       This function returns 0 on success or -1 on error.
5700
5701       This function depends on the feature "extlinux".  See also
5702       "guestfs_feature_available".
5703
5704       (Added in 1.21.27)
5705
5706   guestfs_f2fs_expand
5707        int
5708        guestfs_f2fs_expand (guestfs_h *g,
5709                             const char *device);
5710
5711       This expands a f2fs filesystem to match the size of the underlying
5712       device.
5713
5714       This function returns 0 on success or -1 on error.
5715
5716       This function depends on the feature "f2fs".  See also
5717       "guestfs_feature_available".
5718
5719       (Added in 1.39.3)
5720
5721   guestfs_fallocate
5722        int
5723        guestfs_fallocate (guestfs_h *g,
5724                           const char *path,
5725                           int len);
5726
5727       This function is deprecated.  In new code, use the
5728       "guestfs_fallocate64" call instead.
5729
5730       Deprecated functions will not be removed from the API, but the fact
5731       that they are deprecated indicates that there are problems with correct
5732       use of these functions.
5733
5734       This command preallocates a file (containing zero bytes) named "path"
5735       of size "len" bytes.  If the file exists already, it is overwritten.
5736
5737       Do not confuse this with the guestfish-specific "alloc" command which
5738       allocates a file in the host and attaches it as a device.
5739
5740       This function returns 0 on success or -1 on error.
5741
5742       (Added in 1.0.66)
5743
5744   guestfs_fallocate64
5745        int
5746        guestfs_fallocate64 (guestfs_h *g,
5747                             const char *path,
5748                             int64_t len);
5749
5750       This command preallocates a file (containing zero bytes) named "path"
5751       of size "len" bytes.  If the file exists already, it is overwritten.
5752
5753       Note that this call allocates disk blocks for the file.  To create a
5754       sparse file use "guestfs_truncate_size" instead.
5755
5756       The deprecated call "guestfs_fallocate" does the same, but owing to an
5757       oversight it only allowed 30 bit lengths to be specified, effectively
5758       limiting the maximum size of files created through that call to 1GB.
5759
5760       Do not confuse this with the guestfish-specific "alloc" and "sparse"
5761       commands which create a file in the host and attach it as a device.
5762
5763       This function returns 0 on success or -1 on error.
5764
5765       (Added in 1.3.17)
5766
5767   guestfs_feature_available
5768        int
5769        guestfs_feature_available (guestfs_h *g,
5770                                   char *const *groups);
5771
5772       This is the same as "guestfs_available", but unlike that call it
5773       returns a simple true/false boolean result, instead of throwing an
5774       exception if a feature is not found.  For other documentation see
5775       "guestfs_available".
5776
5777       This function returns a C truth value on success or -1 on error.
5778
5779       (Added in 1.21.26)
5780
5781   guestfs_fgrep
5782        char **
5783        guestfs_fgrep (guestfs_h *g,
5784                       const char *pattern,
5785                       const char *path);
5786
5787       This function is deprecated.  In new code, use the "guestfs_grep" call
5788       instead.
5789
5790       Deprecated functions will not be removed from the API, but the fact
5791       that they are deprecated indicates that there are problems with correct
5792       use of these functions.
5793
5794       This calls the external fgrep(1) program and returns the matching
5795       lines.
5796
5797       This function returns a NULL-terminated array of strings (like
5798       environ(3)), or NULL if there was an error.  The caller must free the
5799       strings and the array after use.
5800
5801       Because of the message protocol, there is a transfer limit of somewhere
5802       between 2MB and 4MB.  See "PROTOCOL LIMITS".
5803
5804       (Added in 1.0.66)
5805
5806   guestfs_fgrepi
5807        char **
5808        guestfs_fgrepi (guestfs_h *g,
5809                        const char *pattern,
5810                        const char *path);
5811
5812       This function is deprecated.  In new code, use the "guestfs_grep" call
5813       instead.
5814
5815       Deprecated functions will not be removed from the API, but the fact
5816       that they are deprecated indicates that there are problems with correct
5817       use of these functions.
5818
5819       This calls the external "fgrep -i" program and returns the matching
5820       lines.
5821
5822       This function returns a NULL-terminated array of strings (like
5823       environ(3)), or NULL if there was an error.  The caller must free the
5824       strings and the array after use.
5825
5826       Because of the message protocol, there is a transfer limit of somewhere
5827       between 2MB and 4MB.  See "PROTOCOL LIMITS".
5828
5829       (Added in 1.0.66)
5830
5831   guestfs_file
5832        char *
5833        guestfs_file (guestfs_h *g,
5834                      const char *path);
5835
5836       This call uses the standard file(1) command to determine the type or
5837       contents of the file.
5838
5839       This call will also transparently look inside various types of
5840       compressed file.
5841
5842       The exact command which runs is "file -zb path".  Note in particular
5843       that the filename is not prepended to the output (the -b option).
5844
5845       The output depends on the output of the underlying file(1) command and
5846       it can change in future in ways beyond our control.  In other words,
5847       the output is not guaranteed by the ABI.
5848
5849       See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5850       "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5851
5852       This function returns a string, or NULL on error.  The caller must free
5853       the returned string after use.
5854
5855       (Added in 1.9.1)
5856
5857   guestfs_file_architecture
5858        char *
5859        guestfs_file_architecture (guestfs_h *g,
5860                                   const char *filename);
5861
5862       This detects the architecture of the binary filename, and returns it if
5863       known.
5864
5865       Currently defined architectures are:
5866
5867       "aarch64"
5868           64 bit ARM.
5869
5870       "arm"
5871           32 bit ARM.
5872
5873       "i386"
5874           This string is returned for all 32 bit i386, i486, i586, i686
5875           binaries irrespective of the precise processor requirements of the
5876           binary.
5877
5878       "ia64"
5879           Intel Itanium.
5880
5881       "ppc"
5882           32 bit Power PC.
5883
5884       "ppc64"
5885           64 bit Power PC (big endian).
5886
5887       "ppc64le"
5888           64 bit Power PC (little endian).
5889
5890       "riscv32"
5891       "riscv64"
5892       "riscv128"
5893           RISC-V 32-, 64- or 128-bit variants.
5894
5895       "s390"
5896           31 bit IBM S/390.
5897
5898       "s390x"
5899           64 bit IBM S/390.
5900
5901       "sparc"
5902           32 bit SPARC.
5903
5904       "sparc64"
5905           64 bit SPARC V9 and above.
5906
5907       "x86_64"
5908           64 bit x86-64.
5909
5910       Libguestfs may return other architecture strings in future.
5911
5912       The function works on at least the following types of files:
5913
5914       •   many types of Un*x and Linux binary
5915
5916       •   many types of Un*x and Linux shared library
5917
5918       •   Windows Win32 and Win64 binaries
5919
5920       •   Windows Win32 and Win64 DLLs
5921
5922           Win32 binaries and DLLs return "i386".
5923
5924           Win64 binaries and DLLs return "x86_64".
5925
5926       •   Linux kernel modules
5927
5928       •   Linux new-style initrd images
5929
5930       •   some non-x86 Linux vmlinuz kernels
5931
5932       What it can't do currently:
5933
5934       •   static libraries (libfoo.a)
5935
5936       •   Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5937
5938       •   x86 Linux vmlinuz kernels
5939
5940           x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5941           and compressed code, and are horribly hard to unpack.  If you want
5942           to find the architecture of a kernel, use the architecture of the
5943           associated initrd or kernel module(s) instead.
5944
5945       This function returns a string, or NULL on error.  The caller must free
5946       the returned string after use.
5947
5948       (Added in 1.5.3)
5949
5950   guestfs_filesize
5951        int64_t
5952        guestfs_filesize (guestfs_h *g,
5953                          const char *file);
5954
5955       This command returns the size of file in bytes.
5956
5957       To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5958       "guestfs_is_dir", "guestfs_is_file" etc.  To get the size of block
5959       devices, use "guestfs_blockdev_getsize64".
5960
5961       On error this function returns -1.
5962
5963       (Added in 1.0.82)
5964
5965   guestfs_filesystem_available
5966        int
5967        guestfs_filesystem_available (guestfs_h *g,
5968                                      const char *filesystem);
5969
5970       Check whether libguestfs supports the named filesystem.  The argument
5971       "filesystem" is a filesystem name, such as "ext3".
5972
5973       You must call "guestfs_launch" before using this command.
5974
5975       This is mainly useful as a negative test.  If this returns true, it
5976       doesn't mean that a particular filesystem can be created or mounted,
5977       since filesystems can fail for other reasons such as it being a later
5978       version of the filesystem, or having incompatible features, or lacking
5979       the right mkfs.<fs> tool.
5980
5981       See also "guestfs_available", "guestfs_feature_available",
5982       "AVAILABILITY".
5983
5984       This function returns a C truth value on success or -1 on error.
5985
5986       (Added in 1.19.5)
5987
5988   guestfs_filesystem_walk
5989        struct guestfs_tsk_dirent_list *
5990        guestfs_filesystem_walk (guestfs_h *g,
5991                                 const char *device);
5992
5993       Walk through the internal structures of a disk partition (eg.
5994       /dev/sda1) in order to return a list of all the files and directories
5995       stored within.
5996
5997       It is not necessary to mount the disk partition to run this command.
5998
5999       All entries in the filesystem are returned. This function can list
6000       deleted or unaccessible files. The entries are not sorted.
6001
6002       The "tsk_dirent" structure contains the following fields.
6003
6004       "tsk_inode"
6005           Filesystem reference number of the node. It might be 0 if the node
6006           has been deleted.
6007
6008       "tsk_type"
6009           Basic file type information.  See below for a detailed list of
6010           values.
6011
6012       "tsk_size"
6013           File size in bytes. It might be "-1" if the node has been deleted.
6014
6015       "tsk_name"
6016           The file path relative to its directory.
6017
6018       "tsk_flags"
6019           Bitfield containing extra information regarding the entry.  It
6020           contains the logical OR of the following values:
6021
6022           0x0001
6023               If set to 1, the file is allocated and visible within the
6024               filesystem.  Otherwise, the file has been deleted.  Under
6025               certain circumstances, the function "download_inode" can be
6026               used to recover deleted files.
6027
6028           0x0002
6029               Filesystem such as NTFS and Ext2 or greater, separate the file
6030               name from the metadata structure.  The bit is set to 1 when the
6031               file name is in an unallocated state and the metadata structure
6032               is in an allocated one.  This generally implies the metadata
6033               has been reallocated to a new file.  Therefore, information
6034               such as file type, file size, timestamps, number of links and
6035               symlink target might not correspond with the ones of the
6036               original deleted entry.
6037
6038           0x0004
6039               The bit is set to 1 when the file is compressed using
6040               filesystem native compression support (NTFS). The API is not
6041               able to detect application level compression.
6042
6043       "tsk_atime_sec"
6044       "tsk_atime_nsec"
6045       "tsk_mtime_sec"
6046       "tsk_mtime_nsec"
6047       "tsk_ctime_sec"
6048       "tsk_ctime_nsec"
6049       "tsk_crtime_sec"
6050       "tsk_crtime_nsec"
6051           Respectively, access, modification, last status change and creation
6052           time in Unix format in seconds and nanoseconds.
6053
6054       "tsk_nlink"
6055           Number of file names pointing to this entry.
6056
6057       "tsk_link"
6058           If the entry is a symbolic link, this field will contain the path
6059           to the target file.
6060
6061       The "tsk_type" field will contain one of the following characters:
6062
6063       'b' Block special
6064
6065       'c' Char special
6066
6067       'd' Directory
6068
6069       'f' FIFO (named pipe)
6070
6071       'l' Symbolic link
6072
6073       'r' Regular file
6074
6075       's' Socket
6076
6077       'h' Shadow inode (Solaris)
6078
6079       'w' Whiteout inode (BSD)
6080
6081       'u' Unknown file type
6082
6083       This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6084       there was an error.  The caller must call
6085       "guestfs_free_tsk_dirent_list" after use.
6086
6087       This long-running command can generate progress notification messages
6088       so that the caller can display a progress bar or indicator.  To receive
6089       these messages, the caller must register a progress event callback.
6090       See "GUESTFS_EVENT_PROGRESS".
6091
6092       This function depends on the feature "libtsk".  See also
6093       "guestfs_feature_available".
6094
6095       (Added in 1.33.39)
6096
6097   guestfs_fill
6098        int
6099        guestfs_fill (guestfs_h *g,
6100                      int c,
6101                      int len,
6102                      const char *path);
6103
6104       This command creates a new file called "path".  The initial content of
6105       the file is "len" octets of "c", where "c" must be a number in the
6106       range "[0..255]".
6107
6108       To fill a file with zero bytes (sparsely), it is much more efficient to
6109       use "guestfs_truncate_size".  To create a file with a pattern of
6110       repeating bytes use "guestfs_fill_pattern".
6111
6112       This function returns 0 on success or -1 on error.
6113
6114       This long-running command can generate progress notification messages
6115       so that the caller can display a progress bar or indicator.  To receive
6116       these messages, the caller must register a progress event callback.
6117       See "GUESTFS_EVENT_PROGRESS".
6118
6119       (Added in 1.0.79)
6120
6121   guestfs_fill_dir
6122        int
6123        guestfs_fill_dir (guestfs_h *g,
6124                          const char *dir,
6125                          int nr);
6126
6127       This function, useful for testing filesystems, creates "nr" empty files
6128       in the directory "dir" with names 00000000 through "nr-1" (ie. each
6129       file name is 8 digits long padded with zeroes).
6130
6131       This function returns 0 on success or -1 on error.
6132
6133       (Added in 1.19.32)
6134
6135   guestfs_fill_pattern
6136        int
6137        guestfs_fill_pattern (guestfs_h *g,
6138                              const char *pattern,
6139                              int len,
6140                              const char *path);
6141
6142       This function is like "guestfs_fill" except that it creates a new file
6143       of length "len" containing the repeating pattern of bytes in "pattern".
6144       The pattern is truncated if necessary to ensure the length of the file
6145       is exactly "len" bytes.
6146
6147       This function returns 0 on success or -1 on error.
6148
6149       This long-running command can generate progress notification messages
6150       so that the caller can display a progress bar or indicator.  To receive
6151       these messages, the caller must register a progress event callback.
6152       See "GUESTFS_EVENT_PROGRESS".
6153
6154       (Added in 1.3.12)
6155
6156   guestfs_find
6157        char **
6158        guestfs_find (guestfs_h *g,
6159                      const char *directory);
6160
6161       This command lists out all files and directories, recursively, starting
6162       at directory.  It is essentially equivalent to running the shell
6163       command "find directory -print" but some post-processing happens on the
6164       output, described below.
6165
6166       This returns a list of strings without any prefix.  Thus if the
6167       directory structure was:
6168
6169        /tmp/a
6170        /tmp/b
6171        /tmp/c/d
6172
6173       then the returned list from "guestfs_find" /tmp would be 4 elements:
6174
6175        a
6176        b
6177        c
6178        c/d
6179
6180       If directory is not a directory, then this command returns an error.
6181
6182       The returned list is sorted.
6183
6184       This function returns a NULL-terminated array of strings (like
6185       environ(3)), or NULL if there was an error.  The caller must free the
6186       strings and the array after use.
6187
6188       (Added in 1.0.27)
6189
6190   guestfs_find0
6191        int
6192        guestfs_find0 (guestfs_h *g,
6193                       const char *directory,
6194                       const char *files);
6195
6196       This command lists out all files and directories, recursively, starting
6197       at directory, placing the resulting list in the external file called
6198       files.
6199
6200       This command works the same way as "guestfs_find" with the following
6201       exceptions:
6202
6203       •   The resulting list is written to an external file.
6204
6205       •   Items (filenames) in the result are separated by "\0" characters.
6206           See find(1) option -print0.
6207
6208       •   The result list is not sorted.
6209
6210       This function returns 0 on success or -1 on error.
6211
6212       (Added in 1.0.74)
6213
6214   guestfs_find_inode
6215        struct guestfs_tsk_dirent_list *
6216        guestfs_find_inode (guestfs_h *g,
6217                            const char *device,
6218                            int64_t inode);
6219
6220       Searches all the entries associated with the given inode.
6221
6222       For each entry, a "tsk_dirent" structure is returned.  See
6223       "filesystem_walk" for more information about "tsk_dirent" structures.
6224
6225       This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6226       there was an error.  The caller must call
6227       "guestfs_free_tsk_dirent_list" after use.
6228
6229       This long-running command can generate progress notification messages
6230       so that the caller can display a progress bar or indicator.  To receive
6231       these messages, the caller must register a progress event callback.
6232       See "GUESTFS_EVENT_PROGRESS".
6233
6234       This function depends on the feature "libtsk".  See also
6235       "guestfs_feature_available".
6236
6237       (Added in 1.35.6)
6238
6239   guestfs_findfs_label
6240        char *
6241        guestfs_findfs_label (guestfs_h *g,
6242                              const char *label);
6243
6244       This command searches the filesystems and returns the one which has the
6245       given label.  An error is returned if no such filesystem can be found.
6246
6247       To find the label of a filesystem, use "guestfs_vfs_label".
6248
6249       This function returns a string, or NULL on error.  The caller must free
6250       the returned string after use.
6251
6252       (Added in 1.5.3)
6253
6254   guestfs_findfs_uuid
6255        char *
6256        guestfs_findfs_uuid (guestfs_h *g,
6257                             const char *uuid);
6258
6259       This command searches the filesystems and returns the one which has the
6260       given UUID.  An error is returned if no such filesystem can be found.
6261
6262       To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6263
6264       This function returns a string, or NULL on error.  The caller must free
6265       the returned string after use.
6266
6267       (Added in 1.5.3)
6268
6269   guestfs_fsck
6270        int
6271        guestfs_fsck (guestfs_h *g,
6272                      const char *fstype,
6273                      const char *device);
6274
6275       This runs the filesystem checker (fsck) on "device" which should have
6276       filesystem type "fstype".
6277
6278       The returned integer is the status.  See fsck(8) for the list of status
6279       codes from "fsck".
6280
6281       Notes:
6282
6283       •   Multiple status codes can be summed together.
6284
6285       •   A non-zero return code can mean "success", for example if errors
6286           have been corrected on the filesystem.
6287
6288       •   Checking or repairing NTFS volumes is not supported (by linux-
6289           ntfs).
6290
6291       This command is entirely equivalent to running "fsck -a -t fstype
6292       device".
6293
6294       On error this function returns -1.
6295
6296       (Added in 1.0.16)
6297
6298   guestfs_fstrim
6299        int
6300        guestfs_fstrim (guestfs_h *g,
6301                        const char *mountpoint,
6302                        ...);
6303
6304       You may supply a list of optional arguments to this call.  Use zero or
6305       more of the following pairs of parameters, and terminate the list with
6306       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
6307
6308        GUESTFS_FSTRIM_OFFSET, int64_t offset,
6309        GUESTFS_FSTRIM_LENGTH, int64_t length,
6310        GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6311
6312       Trim the free space in the filesystem mounted on "mountpoint".  The
6313       filesystem must be mounted read-write.
6314
6315       The filesystem contents are not affected, but any free space in the
6316       filesystem is "trimmed", that is, given back to the host device, thus
6317       making disk images more sparse, allowing unused space in qcow2 files to
6318       be reused, etc.
6319
6320       This operation requires support in libguestfs, the mounted filesystem,
6321       the host filesystem, qemu and the host kernel.  If this support isn't
6322       present it may give an error or even appear to run but do nothing.
6323
6324       In the case where the kernel vfs driver does not support trimming, this
6325       call will fail with errno set to "ENOTSUP".  Currently this happens
6326       when trying to trim FAT filesystems.
6327
6328       See also "guestfs_zero_free_space".  That is a slightly different
6329       operation that turns free space in the filesystem into zeroes.  It is
6330       valid to call "guestfs_fstrim" either instead of, or after calling
6331       "guestfs_zero_free_space".
6332
6333       This function returns 0 on success or -1 on error.
6334
6335       This function depends on the feature "fstrim".  See also
6336       "guestfs_feature_available".
6337
6338       (Added in 1.19.6)
6339
6340   guestfs_fstrim_va
6341        int
6342        guestfs_fstrim_va (guestfs_h *g,
6343                           const char *mountpoint,
6344                           va_list args);
6345
6346       This is the "va_list variant" of "guestfs_fstrim".
6347
6348       See "CALLS WITH OPTIONAL ARGUMENTS".
6349
6350   guestfs_fstrim_argv
6351        int
6352        guestfs_fstrim_argv (guestfs_h *g,
6353                             const char *mountpoint,
6354                             const struct guestfs_fstrim_argv *optargs);
6355
6356       This is the "argv variant" of "guestfs_fstrim".
6357
6358       See "CALLS WITH OPTIONAL ARGUMENTS".
6359
6360   guestfs_get_append
6361        const char *
6362        guestfs_get_append (guestfs_h *g);
6363
6364       Return the additional kernel options which are added to the libguestfs
6365       appliance kernel command line.
6366
6367       If "NULL" then no options are added.
6368
6369       This function returns a string which may be NULL.  There is no way to
6370       return an error from this function.  The string is owned by the guest
6371       handle and must not be freed.
6372
6373       (Added in 1.0.26)
6374
6375   guestfs_get_attach_method
6376        char *
6377        guestfs_get_attach_method (guestfs_h *g);
6378
6379       This function is deprecated.  In new code, use the
6380       "guestfs_get_backend" call instead.
6381
6382       Deprecated functions will not be removed from the API, but the fact
6383       that they are deprecated indicates that there are problems with correct
6384       use of these functions.
6385
6386       Return the current backend.
6387
6388       See "guestfs_set_backend" and "BACKEND".
6389
6390       This function returns a string, or NULL on error.  The caller must free
6391       the returned string after use.
6392
6393       (Added in 1.9.8)
6394
6395   guestfs_get_autosync
6396        int
6397        guestfs_get_autosync (guestfs_h *g);
6398
6399       Get the autosync flag.
6400
6401       This function returns a C truth value on success or -1 on error.
6402
6403       (Added in 0.3)
6404
6405   guestfs_get_backend
6406        char *
6407        guestfs_get_backend (guestfs_h *g);
6408
6409       Return the current backend.
6410
6411       This handle property was previously called the "attach method".
6412
6413       See "guestfs_set_backend" and "BACKEND".
6414
6415       This function returns a string, or NULL on error.  The caller must free
6416       the returned string after use.
6417
6418       (Added in 1.21.26)
6419
6420   guestfs_get_backend_setting
6421        char *
6422        guestfs_get_backend_setting (guestfs_h *g,
6423                                     const char *name);
6424
6425       Find a backend setting string which is either "name" or begins with
6426       "name=".  If "name", this returns the string "1".  If "name=", this
6427       returns the part after the equals sign (which may be an empty string).
6428
6429       If no such setting is found, this function throws an error.  The errno
6430       (see "guestfs_last_errno") will be "ESRCH" in this case.
6431
6432       See "BACKEND", "BACKEND SETTINGS".
6433
6434       This function returns a string, or NULL on error.  The caller must free
6435       the returned string after use.
6436
6437       (Added in 1.27.2)
6438
6439   guestfs_get_backend_settings
6440        char **
6441        guestfs_get_backend_settings (guestfs_h *g);
6442
6443       Return the current backend settings.
6444
6445       This call returns all backend settings strings.  If you want to find a
6446       single backend setting, see "guestfs_get_backend_setting".
6447
6448       See "BACKEND", "BACKEND SETTINGS".
6449
6450       This function returns a NULL-terminated array of strings (like
6451       environ(3)), or NULL if there was an error.  The caller must free the
6452       strings and the array after use.
6453
6454       (Added in 1.25.24)
6455
6456   guestfs_get_cachedir
6457        char *
6458        guestfs_get_cachedir (guestfs_h *g);
6459
6460       Get the directory used by the handle to store the appliance cache.
6461
6462       This function returns a string, or NULL on error.  The caller must free
6463       the returned string after use.
6464
6465       (Added in 1.19.58)
6466
6467   guestfs_get_direct
6468        int
6469        guestfs_get_direct (guestfs_h *g);
6470
6471       This function is deprecated.  In new code, use the
6472       "guestfs_internal_get_console_socket" call instead.
6473
6474       Deprecated functions will not be removed from the API, but the fact
6475       that they are deprecated indicates that there are problems with correct
6476       use of these functions.
6477
6478       Return the direct appliance mode flag.
6479
6480       This function returns a C truth value on success or -1 on error.
6481
6482       (Added in 1.0.72)
6483
6484   guestfs_get_e2attrs
6485        char *
6486        guestfs_get_e2attrs (guestfs_h *g,
6487                             const char *file);
6488
6489       This returns the file attributes associated with file.
6490
6491       The attributes are a set of bits associated with each inode which
6492       affect the behaviour of the file.  The attributes are returned as a
6493       string of letters (described below).  The string may be empty,
6494       indicating that no file attributes are set for this file.
6495
6496       These attributes are only present when the file is located on an
6497       ext2/3/4 filesystem.  Using this call on other filesystem types will
6498       result in an error.
6499
6500       The characters (file attributes) in the returned string are currently:
6501
6502       'A' When the file is accessed, its atime is not modified.
6503
6504       'a' The file is append-only.
6505
6506       'c' The file is compressed on-disk.
6507
6508       'D' (Directories only.)  Changes to this directory are written
6509           synchronously to disk.
6510
6511       'd' The file is not a candidate for backup (see dump(8)).
6512
6513       'E' The file has compression errors.
6514
6515       'e' The file is using extents.
6516
6517       'h' The file is storing its blocks in units of the filesystem blocksize
6518           instead of sectors.
6519
6520       'I' (Directories only.)  The directory is using hashed trees.
6521
6522       'i' The file is immutable.  It cannot be modified, deleted or renamed.
6523           No link can be created to this file.
6524
6525       'j' The file is data-journaled.
6526
6527       's' When the file is deleted, all its blocks will be zeroed.
6528
6529       'S' Changes to this file are written synchronously to disk.
6530
6531       'T' (Directories only.)  This is a hint to the block allocator that
6532           subdirectories contained in this directory should be spread across
6533           blocks.  If not present, the block allocator will try to group
6534           subdirectories together.
6535
6536       't' For a file, this disables tail-merging.  (Not used by upstream
6537           implementations of ext2.)
6538
6539       'u' When the file is deleted, its blocks will be saved, allowing the
6540           file to be undeleted.
6541
6542       'X' The raw contents of the compressed file may be accessed.
6543
6544       'Z' The compressed file is dirty.
6545
6546       More file attributes may be added to this list later.  Not all file
6547       attributes may be set for all kinds of files.  For detailed
6548       information, consult the chattr(1) man page.
6549
6550       See also "guestfs_set_e2attrs".
6551
6552       Don't confuse these attributes with extended attributes (see
6553       "guestfs_getxattr").
6554
6555       This function returns a string, or NULL on error.  The caller must free
6556       the returned string after use.
6557
6558       (Added in 1.17.31)
6559
6560   guestfs_get_e2generation
6561        int64_t
6562        guestfs_get_e2generation (guestfs_h *g,
6563                                  const char *file);
6564
6565       This returns the ext2 file generation of a file.  The generation (which
6566       used to be called the "version") is a number associated with an inode.
6567       This is most commonly used by NFS servers.
6568
6569       The generation is only present when the file is located on an ext2/3/4
6570       filesystem.  Using this call on other filesystem types will result in
6571       an error.
6572
6573       See "guestfs_set_e2generation".
6574
6575       On error this function returns -1.
6576
6577       (Added in 1.17.31)
6578
6579   guestfs_get_e2label
6580        char *
6581        guestfs_get_e2label (guestfs_h *g,
6582                             const char *device);
6583
6584       This function is deprecated.  In new code, use the "guestfs_vfs_label"
6585       call instead.
6586
6587       Deprecated functions will not be removed from the API, but the fact
6588       that they are deprecated indicates that there are problems with correct
6589       use of these functions.
6590
6591       This returns the ext2/3/4 filesystem label of the filesystem on
6592       "device".
6593
6594       This function returns a string, or NULL on error.  The caller must free
6595       the returned string after use.
6596
6597       (Added in 1.0.15)
6598
6599   guestfs_get_e2uuid
6600        char *
6601        guestfs_get_e2uuid (guestfs_h *g,
6602                            const char *device);
6603
6604       This function is deprecated.  In new code, use the "guestfs_vfs_uuid"
6605       call instead.
6606
6607       Deprecated functions will not be removed from the API, but the fact
6608       that they are deprecated indicates that there are problems with correct
6609       use of these functions.
6610
6611       This returns the ext2/3/4 filesystem UUID of the filesystem on
6612       "device".
6613
6614       This function returns a string, or NULL on error.  The caller must free
6615       the returned string after use.
6616
6617       (Added in 1.0.15)
6618
6619   guestfs_get_hv
6620        char *
6621        guestfs_get_hv (guestfs_h *g);
6622
6623       Return the current hypervisor binary.
6624
6625       This is always non-NULL.  If it wasn't set already, then this will
6626       return the default qemu binary name.
6627
6628       This function returns a string, or NULL on error.  The caller must free
6629       the returned string after use.
6630
6631       (Added in 1.23.17)
6632
6633   guestfs_get_identifier
6634        const char *
6635        guestfs_get_identifier (guestfs_h *g);
6636
6637       Get the handle identifier.  See "guestfs_set_identifier".
6638
6639       This function returns a string, or NULL on error.  The string is owned
6640       by the guest handle and must not be freed.
6641
6642       (Added in 1.31.14)
6643
6644   guestfs_get_libvirt_requested_credential_challenge
6645        char *
6646        guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6647                                                            int index);
6648
6649       Get the challenge (provided by libvirt) for the "index"'th requested
6650       credential.  If libvirt did not provide a challenge, this returns the
6651       empty string "".
6652
6653       See "LIBVIRT AUTHENTICATION" for documentation and example code.
6654
6655       This function returns a string, or NULL on error.  The caller must free
6656       the returned string after use.
6657
6658       (Added in 1.19.52)
6659
6660   guestfs_get_libvirt_requested_credential_defresult
6661        char *
6662        guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6663                                                            int index);
6664
6665       Get the default result (provided by libvirt) for the "index"'th
6666       requested credential.  If libvirt did not provide a default result,
6667       this returns the empty string "".
6668
6669       See "LIBVIRT AUTHENTICATION" for documentation and example code.
6670
6671       This function returns a string, or NULL on error.  The caller must free
6672       the returned string after use.
6673
6674       (Added in 1.19.52)
6675
6676   guestfs_get_libvirt_requested_credential_prompt
6677        char *
6678        guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6679                                                         int index);
6680
6681       Get the prompt (provided by libvirt) for the "index"'th requested
6682       credential.  If libvirt did not provide a prompt, this returns the
6683       empty string "".
6684
6685       See "LIBVIRT AUTHENTICATION" for documentation and example code.
6686
6687       This function returns a string, or NULL on error.  The caller must free
6688       the returned string after use.
6689
6690       (Added in 1.19.52)
6691
6692   guestfs_get_libvirt_requested_credentials
6693        char **
6694        guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6695
6696       This should only be called during the event callback for events of type
6697       "GUESTFS_EVENT_LIBVIRT_AUTH".
6698
6699       Return the list of credentials requested by libvirt.  Possible values
6700       are a subset of the strings provided when you called
6701       "guestfs_set_libvirt_supported_credentials".
6702
6703       See "LIBVIRT AUTHENTICATION" for documentation and example code.
6704
6705       This function returns a NULL-terminated array of strings (like
6706       environ(3)), or NULL if there was an error.  The caller must free the
6707       strings and the array after use.
6708
6709       (Added in 1.19.52)
6710
6711   guestfs_get_memsize
6712        int
6713        guestfs_get_memsize (guestfs_h *g);
6714
6715       This gets the memory size in megabytes allocated to the hypervisor.
6716
6717       If "guestfs_set_memsize" was not called on this handle, and if
6718       "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6719       default value for memsize.
6720
6721       For more information on the architecture of libguestfs, see guestfs(3).
6722
6723       On error this function returns -1.
6724
6725       (Added in 1.0.55)
6726
6727   guestfs_get_network
6728        int
6729        guestfs_get_network (guestfs_h *g);
6730
6731       This returns the enable network flag.
6732
6733       This function returns a C truth value on success or -1 on error.
6734
6735       (Added in 1.5.4)
6736
6737   guestfs_get_path
6738        const char *
6739        guestfs_get_path (guestfs_h *g);
6740
6741       Return the current search path.
6742
6743       This is always non-NULL.  If it wasn't set already, then this will
6744       return the default path.
6745
6746       This function returns a string, or NULL on error.  The string is owned
6747       by the guest handle and must not be freed.
6748
6749       (Added in 0.3)
6750
6751   guestfs_get_pgroup
6752        int
6753        guestfs_get_pgroup (guestfs_h *g);
6754
6755       This returns the process group flag.
6756
6757       This function returns a C truth value on success or -1 on error.
6758
6759       (Added in 1.11.18)
6760
6761   guestfs_get_pid
6762        int
6763        guestfs_get_pid (guestfs_h *g);
6764
6765       Return the process ID of the hypervisor.  If there is no hypervisor
6766       running, then this will return an error.
6767
6768       This is an internal call used for debugging and testing.
6769
6770       On error this function returns -1.
6771
6772       (Added in 1.0.56)
6773
6774   guestfs_get_program
6775        const char *
6776        guestfs_get_program (guestfs_h *g);
6777
6778       Get the program name.  See "guestfs_set_program".
6779
6780       This function returns a string, or NULL on error.  The string is owned
6781       by the guest handle and must not be freed.
6782
6783       (Added in 1.21.29)
6784
6785   guestfs_get_qemu
6786        const char *
6787        guestfs_get_qemu (guestfs_h *g);
6788
6789       This function is deprecated.  In new code, use the "guestfs_get_hv"
6790       call instead.
6791
6792       Deprecated functions will not be removed from the API, but the fact
6793       that they are deprecated indicates that there are problems with correct
6794       use of these functions.
6795
6796       Return the current hypervisor binary (usually qemu).
6797
6798       This is always non-NULL.  If it wasn't set already, then this will
6799       return the default qemu binary name.
6800
6801       This function returns a string, or NULL on error.  The string is owned
6802       by the guest handle and must not be freed.
6803
6804       (Added in 1.0.6)
6805
6806   guestfs_get_recovery_proc
6807        int
6808        guestfs_get_recovery_proc (guestfs_h *g);
6809
6810       Return the recovery process enabled flag.
6811
6812       This function returns a C truth value on success or -1 on error.
6813
6814       (Added in 1.0.77)
6815
6816   guestfs_get_selinux
6817        int
6818        guestfs_get_selinux (guestfs_h *g);
6819
6820       This function is deprecated.  In new code, use the
6821       "guestfs_selinux_relabel" call instead.
6822
6823       Deprecated functions will not be removed from the API, but the fact
6824       that they are deprecated indicates that there are problems with correct
6825       use of these functions.
6826
6827       This returns the current setting of the selinux flag which is passed to
6828       the appliance at boot time.  See "guestfs_set_selinux".
6829
6830       For more information on the architecture of libguestfs, see guestfs(3).
6831
6832       This function returns a C truth value on success or -1 on error.
6833
6834       (Added in 1.0.67)
6835
6836   guestfs_get_smp
6837        int
6838        guestfs_get_smp (guestfs_h *g);
6839
6840       This returns the number of virtual CPUs assigned to the appliance.
6841
6842       On error this function returns -1.
6843
6844       (Added in 1.13.15)
6845
6846   guestfs_get_sockdir
6847        char *
6848        guestfs_get_sockdir (guestfs_h *g);
6849
6850       Get the directory used by the handle to store temporary socket files.
6851
6852       This is different from "guestfs_get_tmpdir", as we need shorter paths
6853       for sockets (due to the limited buffers of filenames for UNIX sockets),
6854       and "guestfs_get_tmpdir" may be too long for them.
6855
6856       The environment variable "XDG_RUNTIME_DIR" controls the default value:
6857       If "XDG_RUNTIME_DIR" is set, then that is the default.  Else /tmp is
6858       the default.
6859
6860       This function returns a string, or NULL on error.  The caller must free
6861       the returned string after use.
6862
6863       (Added in 1.33.8)
6864
6865   guestfs_get_state
6866        int
6867        guestfs_get_state (guestfs_h *g);
6868
6869       This returns the current state as an opaque integer.  This is only
6870       useful for printing debug and internal error messages.
6871
6872       For more information on states, see guestfs(3).
6873
6874       On error this function returns -1.
6875
6876       (Added in 1.0.2)
6877
6878   guestfs_get_tmpdir
6879        char *
6880        guestfs_get_tmpdir (guestfs_h *g);
6881
6882       Get the directory used by the handle to store temporary files.
6883
6884       This function returns a string, or NULL on error.  The caller must free
6885       the returned string after use.
6886
6887       (Added in 1.19.58)
6888
6889   guestfs_get_trace
6890        int
6891        guestfs_get_trace (guestfs_h *g);
6892
6893       Return the command trace flag.
6894
6895       This function returns a C truth value on success or -1 on error.
6896
6897       (Added in 1.0.69)
6898
6899   guestfs_get_umask
6900        int
6901        guestfs_get_umask (guestfs_h *g);
6902
6903       Return the current umask.  By default the umask is 022 unless it has
6904       been set by calling "guestfs_umask".
6905
6906       On error this function returns -1.
6907
6908       (Added in 1.3.4)
6909
6910   guestfs_get_verbose
6911        int
6912        guestfs_get_verbose (guestfs_h *g);
6913
6914       This returns the verbose messages flag.
6915
6916       This function returns a C truth value on success or -1 on error.
6917
6918       (Added in 0.3)
6919
6920   guestfs_getcon
6921        char *
6922        guestfs_getcon (guestfs_h *g);
6923
6924       This function is deprecated.  In new code, use the
6925       "guestfs_selinux_relabel" call instead.
6926
6927       Deprecated functions will not be removed from the API, but the fact
6928       that they are deprecated indicates that there are problems with correct
6929       use of these functions.
6930
6931       This gets the SELinux security context of the daemon.
6932
6933       See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6934
6935       This function returns a string, or NULL on error.  The caller must free
6936       the returned string after use.
6937
6938       This function depends on the feature "selinux".  See also
6939       "guestfs_feature_available".
6940
6941       (Added in 1.0.67)
6942
6943   guestfs_getxattr
6944        char *
6945        guestfs_getxattr (guestfs_h *g,
6946                          const char *path,
6947                          const char *name,
6948                          size_t *size_r);
6949
6950       Get a single extended attribute from file "path" named "name".  This
6951       call follows symlinks.  If you want to lookup an extended attribute for
6952       the symlink itself, use "guestfs_lgetxattr".
6953
6954       Normally it is better to get all extended attributes from a file in one
6955       go by calling "guestfs_getxattrs".  However some Linux filesystem
6956       implementations are buggy and do not provide a way to list out
6957       attributes.  For these filesystems (notably ntfs-3g) you have to know
6958       the names of the extended attributes you want in advance and call this
6959       function.
6960
6961       Extended attribute values are blobs of binary data.  If there is no
6962       extended attribute named "name", this returns an error.
6963
6964       See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6965
6966       This function returns a buffer, or NULL on error.  The size of the
6967       returned buffer is written to *size_r.  The caller must free the
6968       returned buffer after use.
6969
6970       This function depends on the feature "linuxxattrs".  See also
6971       "guestfs_feature_available".
6972
6973       (Added in 1.7.24)
6974
6975   guestfs_getxattrs
6976        struct guestfs_xattr_list *
6977        guestfs_getxattrs (guestfs_h *g,
6978                           const char *path);
6979
6980       This call lists the extended attributes of the file or directory
6981       "path".
6982
6983       At the system call level, this is a combination of the listxattr(2) and
6984       getxattr(2) calls.
6985
6986       See also: "guestfs_lgetxattrs", attr(5).
6987
6988       This function returns a "struct guestfs_xattr_list *", or NULL if there
6989       was an error.  The caller must call "guestfs_free_xattr_list" after
6990       use.
6991
6992       This function depends on the feature "linuxxattrs".  See also
6993       "guestfs_feature_available".
6994
6995       (Added in 1.0.59)
6996
6997   guestfs_glob_expand
6998        char **
6999        guestfs_glob_expand (guestfs_h *g,
7000                             const char *pattern);
7001
7002       This function is provided for backwards compatibility with earlier
7003       versions of libguestfs.  It simply calls "guestfs_glob_expand_opts"
7004       with no optional arguments.
7005
7006       (Added in 1.0.50)
7007
7008   guestfs_glob_expand_opts
7009        char **
7010        guestfs_glob_expand_opts (guestfs_h *g,
7011                                  const char *pattern,
7012                                  ...);
7013
7014       You may supply a list of optional arguments to this call.  Use zero or
7015       more of the following pairs of parameters, and terminate the list with
7016       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
7017
7018        GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
7019
7020       This command searches for all the pathnames matching "pattern"
7021       according to the wildcard expansion rules used by the shell.
7022
7023       If no paths match, then this returns an empty list (note: not an
7024       error).
7025
7026       It is just a wrapper around the C glob(3) function with flags
7027       "GLOB_MARK|GLOB_BRACE".  See that manual page for more details.
7028
7029       "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
7030       and it defaults to true.  It can be explicitly set as off to return no
7031       trailing slashes in filenames of directories.
7032
7033       Notice that there is no equivalent command for expanding a device name
7034       (eg. /dev/sd*).  Use "guestfs_list_devices", "guestfs_list_partitions"
7035       etc functions instead.
7036
7037       This function returns a NULL-terminated array of strings (like
7038       environ(3)), or NULL if there was an error.  The caller must free the
7039       strings and the array after use.
7040
7041       (Added in 1.0.50)
7042
7043   guestfs_glob_expand_opts_va
7044        char **
7045        guestfs_glob_expand_opts_va (guestfs_h *g,
7046                                     const char *pattern,
7047                                     va_list args);
7048
7049       This is the "va_list variant" of "guestfs_glob_expand_opts".
7050
7051       See "CALLS WITH OPTIONAL ARGUMENTS".
7052
7053   guestfs_glob_expand_opts_argv
7054        char **
7055        guestfs_glob_expand_opts_argv (guestfs_h *g,
7056                                       const char *pattern,
7057                                       const struct guestfs_glob_expand_opts_argv *optargs);
7058
7059       This is the "argv variant" of "guestfs_glob_expand_opts".
7060
7061       See "CALLS WITH OPTIONAL ARGUMENTS".
7062
7063   guestfs_grep
7064        char **
7065        guestfs_grep (guestfs_h *g,
7066                      const char *regex,
7067                      const char *path);
7068
7069       This function is provided for backwards compatibility with earlier
7070       versions of libguestfs.  It simply calls "guestfs_grep_opts" with no
7071       optional arguments.
7072
7073       (Added in 1.0.66)
7074
7075   guestfs_grep_opts
7076        char **
7077        guestfs_grep_opts (guestfs_h *g,
7078                           const char *regex,
7079                           const char *path,
7080                           ...);
7081
7082       You may supply a list of optional arguments to this call.  Use zero or
7083       more of the following pairs of parameters, and terminate the list with
7084       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
7085
7086        GUESTFS_GREP_OPTS_EXTENDED, int extended,
7087        GUESTFS_GREP_OPTS_FIXED, int fixed,
7088        GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
7089        GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
7090
7091       This calls the external grep(1) program and returns the matching lines.
7092
7093       The optional flags are:
7094
7095       "extended"
7096           Use extended regular expressions.  This is the same as using the -E
7097           flag.
7098
7099       "fixed"
7100           Match fixed (don't use regular expressions).  This is the same as
7101           using the -F flag.
7102
7103       "insensitive"
7104           Match case-insensitive.  This is the same as using the -i flag.
7105
7106       "compressed"
7107           Use zgrep(1) instead of grep(1).  This allows the input to be
7108           compress- or gzip-compressed.
7109
7110       This function returns a NULL-terminated array of strings (like
7111       environ(3)), or NULL if there was an error.  The caller must free the
7112       strings and the array after use.
7113
7114       Because of the message protocol, there is a transfer limit of somewhere
7115       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7116
7117       (Added in 1.0.66)
7118
7119   guestfs_grep_opts_va
7120        char **
7121        guestfs_grep_opts_va (guestfs_h *g,
7122                              const char *regex,
7123                              const char *path,
7124                              va_list args);
7125
7126       This is the "va_list variant" of "guestfs_grep_opts".
7127
7128       See "CALLS WITH OPTIONAL ARGUMENTS".
7129
7130   guestfs_grep_opts_argv
7131        char **
7132        guestfs_grep_opts_argv (guestfs_h *g,
7133                                const char *regex,
7134                                const char *path,
7135                                const struct guestfs_grep_opts_argv *optargs);
7136
7137       This is the "argv variant" of "guestfs_grep_opts".
7138
7139       See "CALLS WITH OPTIONAL ARGUMENTS".
7140
7141   guestfs_grepi
7142        char **
7143        guestfs_grepi (guestfs_h *g,
7144                       const char *regex,
7145                       const char *path);
7146
7147       This function is deprecated.  In new code, use the "guestfs_grep" call
7148       instead.
7149
7150       Deprecated functions will not be removed from the API, but the fact
7151       that they are deprecated indicates that there are problems with correct
7152       use of these functions.
7153
7154       This calls the external "grep -i" program and returns the matching
7155       lines.
7156
7157       This function returns a NULL-terminated array of strings (like
7158       environ(3)), or NULL if there was an error.  The caller must free the
7159       strings and the array after use.
7160
7161       Because of the message protocol, there is a transfer limit of somewhere
7162       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7163
7164       (Added in 1.0.66)
7165
7166   guestfs_grub_install
7167        int
7168        guestfs_grub_install (guestfs_h *g,
7169                              const char *root,
7170                              const char *device);
7171
7172       This command installs GRUB 1 (the Grand Unified Bootloader) on
7173       "device", with the root directory being "root".
7174
7175       Notes:
7176
7177       •   There is currently no way in the API to install grub2, which is
7178           used by most modern Linux guests.  It is possible to run the grub2
7179           command from the guest, although see the caveats in "RUNNING
7180           COMMANDS".
7181
7182       •   This uses grub-install(8) from the host.  Unfortunately grub is not
7183           always compatible with itself, so this only works in rather narrow
7184           circumstances.  Careful testing with each guest version is
7185           advisable.
7186
7187       •   If grub-install reports the error "No suitable drive was found in
7188           the generated device map."  it may be that you need to create a
7189           /boot/grub/device.map file first that contains the mapping between
7190           grub device names and Linux device names.  It is usually sufficient
7191           to create a file containing:
7192
7193            (hd0) /dev/vda
7194
7195           replacing /dev/vda with the name of the installation device.
7196
7197       This function returns 0 on success or -1 on error.
7198
7199       This function depends on the feature "grub".  See also
7200       "guestfs_feature_available".
7201
7202       (Added in 1.0.17)
7203
7204   guestfs_head
7205        char **
7206        guestfs_head (guestfs_h *g,
7207                      const char *path);
7208
7209       This command returns up to the first 10 lines of a file as a list of
7210       strings.
7211
7212       This function returns a NULL-terminated array of strings (like
7213       environ(3)), or NULL if there was an error.  The caller must free the
7214       strings and the array after use.
7215
7216       Because of the message protocol, there is a transfer limit of somewhere
7217       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7218
7219       (Added in 1.0.54)
7220
7221   guestfs_head_n
7222        char **
7223        guestfs_head_n (guestfs_h *g,
7224                        int nrlines,
7225                        const char *path);
7226
7227       If the parameter "nrlines" is a positive number, this returns the first
7228       "nrlines" lines of the file "path".
7229
7230       If the parameter "nrlines" is a negative number, this returns lines
7231       from the file "path", excluding the last "nrlines" lines.
7232
7233       If the parameter "nrlines" is zero, this returns an empty list.
7234
7235       This function returns a NULL-terminated array of strings (like
7236       environ(3)), or NULL if there was an error.  The caller must free the
7237       strings and the array after use.
7238
7239       Because of the message protocol, there is a transfer limit of somewhere
7240       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7241
7242       (Added in 1.0.54)
7243
7244   guestfs_hexdump
7245        char *
7246        guestfs_hexdump (guestfs_h *g,
7247                         const char *path);
7248
7249       This runs "hexdump -C" on the given "path".  The result is the human-
7250       readable, canonical hex dump of the file.
7251
7252       This function returns a string, or NULL on error.  The caller must free
7253       the returned string after use.
7254
7255       Because of the message protocol, there is a transfer limit of somewhere
7256       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7257
7258       (Added in 1.0.22)
7259
7260   guestfs_hivex_close
7261        int
7262        guestfs_hivex_close (guestfs_h *g);
7263
7264       Close the current hivex handle.
7265
7266       This is a wrapper around the hivex(3) call of the same name.
7267
7268       This function returns 0 on success or -1 on error.
7269
7270       This function depends on the feature "hivex".  See also
7271       "guestfs_feature_available".
7272
7273       (Added in 1.19.35)
7274
7275   guestfs_hivex_commit
7276        int
7277        guestfs_hivex_commit (guestfs_h *g,
7278                              const char *filename);
7279
7280       Commit (write) changes to the hive.
7281
7282       If the optional filename parameter is null, then the changes are
7283       written back to the same hive that was opened.  If this is not null
7284       then they are written to the alternate filename given and the original
7285       hive is left untouched.
7286
7287       This is a wrapper around the hivex(3) call of the same name.
7288
7289       This function returns 0 on success or -1 on error.
7290
7291       This function depends on the feature "hivex".  See also
7292       "guestfs_feature_available".
7293
7294       (Added in 1.19.35)
7295
7296   guestfs_hivex_node_add_child
7297        int64_t
7298        guestfs_hivex_node_add_child (guestfs_h *g,
7299                                      int64_t parent,
7300                                      const char *name);
7301
7302       Add a child node to "parent" named "name".
7303
7304       This is a wrapper around the hivex(3) call of the same name.
7305
7306       On error this function returns -1.
7307
7308       This function depends on the feature "hivex".  See also
7309       "guestfs_feature_available".
7310
7311       (Added in 1.19.35)
7312
7313   guestfs_hivex_node_children
7314        struct guestfs_hivex_node_list *
7315        guestfs_hivex_node_children (guestfs_h *g,
7316                                     int64_t nodeh);
7317
7318       Return the list of nodes which are subkeys of "nodeh".
7319
7320       This is a wrapper around the hivex(3) call of the same name.
7321
7322       This function returns a "struct guestfs_hivex_node_list *", or NULL if
7323       there was an error.  The caller must call
7324       "guestfs_free_hivex_node_list" after use.
7325
7326       This function depends on the feature "hivex".  See also
7327       "guestfs_feature_available".
7328
7329       (Added in 1.19.35)
7330
7331   guestfs_hivex_node_delete_child
7332        int
7333        guestfs_hivex_node_delete_child (guestfs_h *g,
7334                                         int64_t nodeh);
7335
7336       Delete "nodeh", recursively if necessary.
7337
7338       This is a wrapper around the hivex(3) call of the same name.
7339
7340       This function returns 0 on success or -1 on error.
7341
7342       This function depends on the feature "hivex".  See also
7343       "guestfs_feature_available".
7344
7345       (Added in 1.19.35)
7346
7347   guestfs_hivex_node_get_child
7348        int64_t
7349        guestfs_hivex_node_get_child (guestfs_h *g,
7350                                      int64_t nodeh,
7351                                      const char *name);
7352
7353       Return the child of "nodeh" with the name "name", if it exists.  This
7354       can return 0 meaning the name was not found.
7355
7356       This is a wrapper around the hivex(3) call of the same name.
7357
7358       On error this function returns -1.
7359
7360       This function depends on the feature "hivex".  See also
7361       "guestfs_feature_available".
7362
7363       (Added in 1.19.35)
7364
7365   guestfs_hivex_node_get_value
7366        int64_t
7367        guestfs_hivex_node_get_value (guestfs_h *g,
7368                                      int64_t nodeh,
7369                                      const char *key);
7370
7371       Return the value attached to "nodeh" which has the name "key", if it
7372       exists.  This can return 0 meaning the key was not found.
7373
7374       This is a wrapper around the hivex(3) call of the same name.
7375
7376       On error this function returns -1.
7377
7378       This function depends on the feature "hivex".  See also
7379       "guestfs_feature_available".
7380
7381       (Added in 1.19.35)
7382
7383   guestfs_hivex_node_name
7384        char *
7385        guestfs_hivex_node_name (guestfs_h *g,
7386                                 int64_t nodeh);
7387
7388       Return the name of "nodeh".
7389
7390       This is a wrapper around the hivex(3) call of the same name.
7391
7392       This function returns a string, or NULL on error.  The caller must free
7393       the returned string after use.
7394
7395       This function depends on the feature "hivex".  See also
7396       "guestfs_feature_available".
7397
7398       (Added in 1.19.35)
7399
7400   guestfs_hivex_node_parent
7401        int64_t
7402        guestfs_hivex_node_parent (guestfs_h *g,
7403                                   int64_t nodeh);
7404
7405       Return the parent node of "nodeh".
7406
7407       This is a wrapper around the hivex(3) call of the same name.
7408
7409       On error this function returns -1.
7410
7411       This function depends on the feature "hivex".  See also
7412       "guestfs_feature_available".
7413
7414       (Added in 1.19.35)
7415
7416   guestfs_hivex_node_set_value
7417        int
7418        guestfs_hivex_node_set_value (guestfs_h *g,
7419                                      int64_t nodeh,
7420                                      const char *key,
7421                                      int64_t t,
7422                                      const char *val,
7423                                      size_t val_size);
7424
7425       Set or replace a single value under the node "nodeh".  The "key" is the
7426       name, "t" is the type, and "val" is the data.
7427
7428       This is a wrapper around the hivex(3) call of the same name.
7429
7430       This function returns 0 on success or -1 on error.
7431
7432       This function depends on the feature "hivex".  See also
7433       "guestfs_feature_available".
7434
7435       (Added in 1.19.35)
7436
7437   guestfs_hivex_node_values
7438        struct guestfs_hivex_value_list *
7439        guestfs_hivex_node_values (guestfs_h *g,
7440                                   int64_t nodeh);
7441
7442       Return the array of (key, datatype, data) tuples attached to "nodeh".
7443
7444       This is a wrapper around the hivex(3) call of the same name.
7445
7446       This function returns a "struct guestfs_hivex_value_list *", or NULL if
7447       there was an error.  The caller must call
7448       "guestfs_free_hivex_value_list" after use.
7449
7450       This function depends on the feature "hivex".  See also
7451       "guestfs_feature_available".
7452
7453       (Added in 1.19.35)
7454
7455   guestfs_hivex_open
7456        int
7457        guestfs_hivex_open (guestfs_h *g,
7458                            const char *filename,
7459                            ...);
7460
7461       You may supply a list of optional arguments to this call.  Use zero or
7462       more of the following pairs of parameters, and terminate the list with
7463       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
7464
7465        GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7466        GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7467        GUESTFS_HIVEX_OPEN_WRITE, int write,
7468        GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7469
7470       Open the Windows Registry hive file named filename.  If there was any
7471       previous hivex handle associated with this guestfs session, then it is
7472       closed.
7473
7474       This is a wrapper around the hivex(3) call of the same name.
7475
7476       This function returns 0 on success or -1 on error.
7477
7478       This function depends on the feature "hivex".  See also
7479       "guestfs_feature_available".
7480
7481       (Added in 1.19.35)
7482
7483   guestfs_hivex_open_va
7484        int
7485        guestfs_hivex_open_va (guestfs_h *g,
7486                               const char *filename,
7487                               va_list args);
7488
7489       This is the "va_list variant" of "guestfs_hivex_open".
7490
7491       See "CALLS WITH OPTIONAL ARGUMENTS".
7492
7493   guestfs_hivex_open_argv
7494        int
7495        guestfs_hivex_open_argv (guestfs_h *g,
7496                                 const char *filename,
7497                                 const struct guestfs_hivex_open_argv *optargs);
7498
7499       This is the "argv variant" of "guestfs_hivex_open".
7500
7501       See "CALLS WITH OPTIONAL ARGUMENTS".
7502
7503   guestfs_hivex_root
7504        int64_t
7505        guestfs_hivex_root (guestfs_h *g);
7506
7507       Return the root node of the hive.
7508
7509       This is a wrapper around the hivex(3) call of the same name.
7510
7511       On error this function returns -1.
7512
7513       This function depends on the feature "hivex".  See also
7514       "guestfs_feature_available".
7515
7516       (Added in 1.19.35)
7517
7518   guestfs_hivex_value_key
7519        char *
7520        guestfs_hivex_value_key (guestfs_h *g,
7521                                 int64_t valueh);
7522
7523       Return the key (name) field of a (key, datatype, data) tuple.
7524
7525       This is a wrapper around the hivex(3) call of the same name.
7526
7527       This function returns a string, or NULL on error.  The caller must free
7528       the returned string after use.
7529
7530       This function depends on the feature "hivex".  See also
7531       "guestfs_feature_available".
7532
7533       (Added in 1.19.35)
7534
7535   guestfs_hivex_value_string
7536        char *
7537        guestfs_hivex_value_string (guestfs_h *g,
7538                                    int64_t valueh);
7539
7540       This calls "guestfs_hivex_value_value" (which returns the data field
7541       from a hivex value tuple).  It then assumes that the field is a
7542       UTF-16LE string and converts the result to UTF-8 (or if this is not
7543       possible, it returns an error).
7544
7545       This is useful for reading strings out of the Windows registry.
7546       However it is not foolproof because the registry is not strongly-typed
7547       and fields can contain arbitrary or unexpected data.
7548
7549       This function returns a string, or NULL on error.  The caller must free
7550       the returned string after use.
7551
7552       This function depends on the feature "hivex".  See also
7553       "guestfs_feature_available".
7554
7555       (Added in 1.37.22)
7556
7557   guestfs_hivex_value_type
7558        int64_t
7559        guestfs_hivex_value_type (guestfs_h *g,
7560                                  int64_t valueh);
7561
7562       Return the data type field from a (key, datatype, data) tuple.
7563
7564       This is a wrapper around the hivex(3) call of the same name.
7565
7566       On error this function returns -1.
7567
7568       This function depends on the feature "hivex".  See also
7569       "guestfs_feature_available".
7570
7571       (Added in 1.19.35)
7572
7573   guestfs_hivex_value_utf8
7574        char *
7575        guestfs_hivex_value_utf8 (guestfs_h *g,
7576                                  int64_t valueh);
7577
7578       This function is deprecated.  In new code, use the
7579       "guestfs_hivex_value_string" call instead.
7580
7581       Deprecated functions will not be removed from the API, but the fact
7582       that they are deprecated indicates that there are problems with correct
7583       use of these functions.
7584
7585       This calls "guestfs_hivex_value_value" (which returns the data field
7586       from a hivex value tuple).  It then assumes that the field is a
7587       UTF-16LE string and converts the result to UTF-8 (or if this is not
7588       possible, it returns an error).
7589
7590       This is useful for reading strings out of the Windows registry.
7591       However it is not foolproof because the registry is not strongly-typed
7592       and fields can contain arbitrary or unexpected data.
7593
7594       This function returns a string, or NULL on error.  The caller must free
7595       the returned string after use.
7596
7597       This function depends on the feature "hivex".  See also
7598       "guestfs_feature_available".
7599
7600       (Added in 1.19.35)
7601
7602   guestfs_hivex_value_value
7603        char *
7604        guestfs_hivex_value_value (guestfs_h *g,
7605                                   int64_t valueh,
7606                                   size_t *size_r);
7607
7608       Return the data field of a (key, datatype, data) tuple.
7609
7610       This is a wrapper around the hivex(3) call of the same name.
7611
7612       See also: "guestfs_hivex_value_utf8".
7613
7614       This function returns a buffer, or NULL on error.  The size of the
7615       returned buffer is written to *size_r.  The caller must free the
7616       returned buffer after use.
7617
7618       This function depends on the feature "hivex".  See also
7619       "guestfs_feature_available".
7620
7621       (Added in 1.19.35)
7622
7623   guestfs_initrd_cat
7624        char *
7625        guestfs_initrd_cat (guestfs_h *g,
7626                            const char *initrdpath,
7627                            const char *filename,
7628                            size_t *size_r);
7629
7630       This command unpacks the file filename from the initrd file called
7631       initrdpath.  The filename must be given without the initial /
7632       character.
7633
7634       For example, in guestfish you could use the following command to
7635       examine the boot script (usually called /init) contained in a Linux
7636       initrd or initramfs image:
7637
7638        initrd-cat /boot/initrd-<version>.img init
7639
7640       See also "guestfs_initrd_list".
7641
7642       This function returns a buffer, or NULL on error.  The size of the
7643       returned buffer is written to *size_r.  The caller must free the
7644       returned buffer after use.
7645
7646       Because of the message protocol, there is a transfer limit of somewhere
7647       between 2MB and 4MB.  See "PROTOCOL LIMITS".
7648
7649       (Added in 1.0.84)
7650
7651   guestfs_initrd_list
7652        char **
7653        guestfs_initrd_list (guestfs_h *g,
7654                             const char *path);
7655
7656       This command lists out files contained in an initrd.
7657
7658       The files are listed without any initial / character.  The files are
7659       listed in the order they appear (not necessarily alphabetical).
7660       Directory names are listed as separate items.
7661
7662       Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7663       as initrd.  We only support the newer initramfs format (compressed cpio
7664       files).
7665
7666       This function returns a NULL-terminated array of strings (like
7667       environ(3)), or NULL if there was an error.  The caller must free the
7668       strings and the array after use.
7669
7670       (Added in 1.0.54)
7671
7672   guestfs_inotify_add_watch
7673        int64_t
7674        guestfs_inotify_add_watch (guestfs_h *g,
7675                                   const char *path,
7676                                   int mask);
7677
7678       Watch "path" for the events listed in "mask".
7679
7680       Note that if "path" is a directory then events within that directory
7681       are watched, but this does not happen recursively (in subdirectories).
7682
7683       Note for non-C or non-Linux callers: the inotify events are defined by
7684       the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7685
7686       On error this function returns -1.
7687
7688       This function depends on the feature "inotify".  See also
7689       "guestfs_feature_available".
7690
7691       (Added in 1.0.66)
7692
7693   guestfs_inotify_close
7694        int
7695        guestfs_inotify_close (guestfs_h *g);
7696
7697       This closes the inotify handle which was previously opened by
7698       inotify_init.  It removes all watches, throws away any pending events,
7699       and deallocates all resources.
7700
7701       This function returns 0 on success or -1 on error.
7702
7703       This function depends on the feature "inotify".  See also
7704       "guestfs_feature_available".
7705
7706       (Added in 1.0.66)
7707
7708   guestfs_inotify_files
7709        char **
7710        guestfs_inotify_files (guestfs_h *g);
7711
7712       This function is a helpful wrapper around "guestfs_inotify_read" which
7713       just returns a list of pathnames of objects that were touched.  The
7714       returned pathnames are sorted and deduplicated.
7715
7716       This function returns a NULL-terminated array of strings (like
7717       environ(3)), or NULL if there was an error.  The caller must free the
7718       strings and the array after use.
7719
7720       This function depends on the feature "inotify".  See also
7721       "guestfs_feature_available".
7722
7723       (Added in 1.0.66)
7724
7725   guestfs_inotify_init
7726        int
7727        guestfs_inotify_init (guestfs_h *g,
7728                              int maxevents);
7729
7730       This command creates a new inotify handle.  The inotify subsystem can
7731       be used to notify events which happen to objects in the guest
7732       filesystem.
7733
7734       "maxevents" is the maximum number of events which will be queued up
7735       between calls to "guestfs_inotify_read" or "guestfs_inotify_files".  If
7736       this is passed as 0, then the kernel (or previously set) default is
7737       used.  For Linux 2.6.29 the default was 16384 events.  Beyond this
7738       limit, the kernel throws away events, but records the fact that it
7739       threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7740       structure list (see "guestfs_inotify_read").
7741
7742       Before any events are generated, you have to add some watches to the
7743       internal watch list.  See: "guestfs_inotify_add_watch" and
7744       "guestfs_inotify_rm_watch".
7745
7746       Queued up events should be read periodically by calling
7747       "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7748       helpful wrapper around "guestfs_inotify_read").  If you don't read the
7749       events out often enough then you risk the internal queue overflowing.
7750
7751       The handle should be closed after use by calling
7752       "guestfs_inotify_close".  This also removes any watches automatically.
7753
7754       See also inotify(7) for an overview of the inotify interface as exposed
7755       by the Linux kernel, which is roughly what we expose via libguestfs.
7756       Note that there is one global inotify handle per libguestfs instance.
7757
7758       This function returns 0 on success or -1 on error.
7759
7760       This function depends on the feature "inotify".  See also
7761       "guestfs_feature_available".
7762
7763       (Added in 1.0.66)
7764
7765   guestfs_inotify_read
7766        struct guestfs_inotify_event_list *
7767        guestfs_inotify_read (guestfs_h *g);
7768
7769       Return the complete queue of events that have happened since the
7770       previous read call.
7771
7772       If no events have happened, this returns an empty list.
7773
7774       Note: In order to make sure that all events have been read, you must
7775       call this function repeatedly until it returns an empty list.  The
7776       reason is that the call will read events up to the maximum appliance-
7777       to-host message size and leave remaining events in the queue.
7778
7779       This function returns a "struct guestfs_inotify_event_list *", or NULL
7780       if there was an error.  The caller must call
7781       "guestfs_free_inotify_event_list" after use.
7782
7783       This function depends on the feature "inotify".  See also
7784       "guestfs_feature_available".
7785
7786       (Added in 1.0.66)
7787
7788   guestfs_inotify_rm_watch
7789        int
7790        guestfs_inotify_rm_watch (guestfs_h *g,
7791                                  int wd);
7792
7793       Remove a previously defined inotify watch.  See
7794       "guestfs_inotify_add_watch".
7795
7796       This function returns 0 on success or -1 on error.
7797
7798       This function depends on the feature "inotify".  See also
7799       "guestfs_feature_available".
7800
7801       (Added in 1.0.66)
7802
7803   guestfs_inspect_get_arch
7804        char *
7805        guestfs_inspect_get_arch (guestfs_h *g,
7806                                  const char *root);
7807
7808       This returns the architecture of the inspected operating system.  The
7809       possible return values are listed under "guestfs_file_architecture".
7810
7811       If the architecture could not be determined, then the string "unknown"
7812       is returned.
7813
7814       Please read "INSPECTION" for more details.
7815
7816       This function returns a string, or NULL on error.  The caller must free
7817       the returned string after use.
7818
7819       (Added in 1.5.3)
7820
7821   guestfs_inspect_get_distro
7822        char *
7823        guestfs_inspect_get_distro (guestfs_h *g,
7824                                    const char *root);
7825
7826       This returns the distro (distribution) of the inspected operating
7827       system.
7828
7829       Currently defined distros are:
7830
7831       "alpinelinux"
7832           Alpine Linux.
7833
7834       "altlinux"
7835           ALT Linux.
7836
7837       "archlinux"
7838           Arch Linux.
7839
7840       "buildroot"
7841           Buildroot-derived distro, but not one we specifically recognize.
7842
7843       "centos"
7844           CentOS.
7845
7846       "cirros"
7847           Cirros.
7848
7849       "coreos"
7850           CoreOS.
7851
7852       "debian"
7853           Debian.
7854
7855       "fedora"
7856           Fedora.
7857
7858       "freebsd"
7859           FreeBSD.
7860
7861       "freedos"
7862           FreeDOS.
7863
7864       "frugalware"
7865           Frugalware.
7866
7867       "gentoo"
7868           Gentoo.
7869
7870       "kalilinux"
7871           Kali Linux.
7872
7873       "linuxmint"
7874           Linux Mint.
7875
7876       "mageia"
7877           Mageia.
7878
7879       "mandriva"
7880           Mandriva.
7881
7882       "meego"
7883           MeeGo.
7884
7885       "msdos"
7886           Microsoft DOS.
7887
7888       "neokylin"
7889           NeoKylin.
7890
7891       "netbsd"
7892           NetBSD.
7893
7894       "openbsd"
7895           OpenBSD.
7896
7897       "openmandriva"
7898           OpenMandriva Lx.
7899
7900       "opensuse"
7901           OpenSUSE.
7902
7903       "oraclelinux"
7904           Oracle Linux.
7905
7906       "pardus"
7907           Pardus.
7908
7909       "pldlinux"
7910           PLD Linux.
7911
7912       "redhat-based"
7913           Some Red Hat-derived distro.
7914
7915       "rhel"
7916           Red Hat Enterprise Linux.
7917
7918       "scientificlinux"
7919           Scientific Linux.
7920
7921       "slackware"
7922           Slackware.
7923
7924       "sles"
7925           SuSE Linux Enterprise Server or Desktop.
7926
7927       "suse-based"
7928           Some openSuSE-derived distro.
7929
7930       "ttylinux"
7931           ttylinux.
7932
7933       "ubuntu"
7934           Ubuntu.
7935
7936       "unknown"
7937           The distro could not be determined.
7938
7939       "voidlinux"
7940           Void Linux.
7941
7942       "windows"
7943           Windows does not have distributions.  This string is returned if
7944           the OS type is Windows.
7945
7946       Future versions of libguestfs may return other strings here.  The
7947       caller should be prepared to handle any string.
7948
7949       Please read "INSPECTION" for more details.
7950
7951       This function returns a string, or NULL on error.  The caller must free
7952       the returned string after use.
7953
7954       (Added in 1.5.3)
7955
7956   guestfs_inspect_get_drive_mappings
7957        char **
7958        guestfs_inspect_get_drive_mappings (guestfs_h *g,
7959                                            const char *root);
7960
7961       This call is useful for Windows which uses a primitive system of
7962       assigning drive letters (like C:\) to partitions.  This inspection API
7963       examines the Windows Registry to find out how disks/partitions are
7964       mapped to drive letters, and returns a hash table as in the example
7965       below:
7966
7967        C      =>     /dev/vda2
7968        E      =>     /dev/vdb1
7969        F      =>     /dev/vdc1
7970
7971       Note that keys are drive letters.  For Windows, the key is case
7972       insensitive and just contains the drive letter, without the customary
7973       colon separator character.
7974
7975       In future we may support other operating systems that also used drive
7976       letters, but the keys for those might not be case insensitive and might
7977       be longer than 1 character.  For example in OS-9, hard drives were
7978       named "h0", "h1" etc.
7979
7980       For Windows guests, currently only hard drive mappings are returned.
7981       Removable disks (eg. DVD-ROMs) are ignored.
7982
7983       For guests that do not use drive mappings, or if the drive mappings
7984       could not be determined, this returns an empty hash table.
7985
7986       Please read "INSPECTION" for more details.  See also
7987       "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7988
7989       This function returns a NULL-terminated array of strings, or NULL if
7990       there was an error.  The array of strings will always have length
7991       "2n+1", where "n" keys and values alternate, followed by the trailing
7992       NULL entry.  The caller must free the strings and the array after use.
7993
7994       (Added in 1.9.17)
7995
7996   guestfs_inspect_get_filesystems
7997        char **
7998        guestfs_inspect_get_filesystems (guestfs_h *g,
7999                                         const char *root);
8000
8001       This returns a list of all the filesystems that we think are associated
8002       with this operating system.  This includes the root filesystem, other
8003       ordinary filesystems, and non-mounted devices like swap partitions.
8004
8005       In the case of a multi-boot virtual machine, it is possible for a
8006       filesystem to be shared between operating systems.
8007
8008       Please read "INSPECTION" for more details.  See also
8009       "guestfs_inspect_get_mountpoints".
8010
8011       This function returns a NULL-terminated array of strings (like
8012       environ(3)), or NULL if there was an error.  The caller must free the
8013       strings and the array after use.
8014
8015       (Added in 1.5.3)
8016
8017   guestfs_inspect_get_format
8018        char *
8019        guestfs_inspect_get_format (guestfs_h *g,
8020                                    const char *root);
8021
8022       This function is deprecated.  There is no replacement.  Consult the API
8023       documentation in guestfs(3) for further information.
8024
8025       Deprecated functions will not be removed from the API, but the fact
8026       that they are deprecated indicates that there are problems with correct
8027       use of these functions.
8028
8029       Before libguestfs 1.38, there was some unreliable support for detecting
8030       installer CDs.  This API would return:
8031
8032       "installed"
8033           This is an installed operating system.
8034
8035       "installer"
8036           The disk image being inspected is not an installed operating
8037           system, but a bootable install disk, live CD, or similar.
8038
8039       "unknown"
8040           The format of this disk image is not known.
8041
8042       In libguestfs ≥ 1.38, this only returns "installed".  Use libosinfo
8043       directly to detect installer CDs.
8044
8045       Please read "INSPECTION" for more details.
8046
8047       This function returns a string, or NULL on error.  The caller must free
8048       the returned string after use.
8049
8050       (Added in 1.9.4)
8051
8052   guestfs_inspect_get_hostname
8053        char *
8054        guestfs_inspect_get_hostname (guestfs_h *g,
8055                                      const char *root);
8056
8057       This function returns the hostname of the operating system as found by
8058       inspection of the guest’s configuration files.
8059
8060       If the hostname could not be determined, then the string "unknown" is
8061       returned.
8062
8063       Please read "INSPECTION" for more details.
8064
8065       This function returns a string, or NULL on error.  The caller must free
8066       the returned string after use.
8067
8068       (Added in 1.7.9)
8069
8070   guestfs_inspect_get_icon
8071        char *
8072        guestfs_inspect_get_icon (guestfs_h *g,
8073                                  const char *root,
8074                                  size_t *size_r,
8075                                  ...);
8076
8077       You may supply a list of optional arguments to this call.  Use zero or
8078       more of the following pairs of parameters, and terminate the list with
8079       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8080
8081        GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
8082        GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
8083
8084       This function returns an icon corresponding to the inspected operating
8085       system.  The icon is returned as a buffer containing a PNG image (re-
8086       encoded to PNG if necessary).
8087
8088       If it was not possible to get an icon this function returns a zero-
8089       length (non-NULL) buffer.  Callers must check for this case.
8090
8091       Libguestfs will start by looking for a file called /etc/favicon.png or
8092       C:\etc\favicon.png and if it has the correct format, the contents of
8093       this file will be returned.  You can disable favicons by passing the
8094       optional "favicon" boolean as false (default is true).
8095
8096       If finding the favicon fails, then we look in other places in the guest
8097       for a suitable icon.
8098
8099       If the optional "highquality" boolean is true then only high quality
8100       icons are returned, which means only icons of high resolution with an
8101       alpha channel.  The default (false) is to return any icon we can, even
8102       if it is of substandard quality.
8103
8104       Notes:
8105
8106       •   Unlike most other inspection API calls, the guest’s disks must be
8107           mounted up before you call this, since it needs to read information
8108           from the guest filesystem during the call.
8109
8110Security: The icon data comes from the untrusted guest, and should
8111           be treated with caution.  PNG files have been known to contain
8112           exploits.  Ensure that libpng (or other relevant libraries) are
8113           fully up to date before trying to process or display the icon.
8114
8115       •   The PNG image returned can be any size.  It might not be square.
8116           Libguestfs tries to return the largest, highest quality icon
8117           available.  The application must scale the icon to the required
8118           size.
8119
8120       •   Extracting icons from Windows guests requires the external
8121           wrestool(1) program from the "icoutils" package, and several
8122           programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
8123           package.  These must be installed separately.
8124
8125       •   Operating system icons are usually trademarks.  Seek legal advice
8126           before using trademarks in applications.
8127
8128       This function returns a buffer, or NULL on error.  The size of the
8129       returned buffer is written to *size_r.  The caller must free the
8130       returned buffer after use.
8131
8132       (Added in 1.11.12)
8133
8134   guestfs_inspect_get_icon_va
8135        char *
8136        guestfs_inspect_get_icon_va (guestfs_h *g,
8137                                     const char *root,
8138                                     size_t *size_r,
8139                                     va_list args);
8140
8141       This is the "va_list variant" of "guestfs_inspect_get_icon".
8142
8143       See "CALLS WITH OPTIONAL ARGUMENTS".
8144
8145   guestfs_inspect_get_icon_argv
8146        char *
8147        guestfs_inspect_get_icon_argv (guestfs_h *g,
8148                                       const char *root,
8149                                       size_t *size_r,
8150                                       const struct guestfs_inspect_get_icon_argv *optargs);
8151
8152       This is the "argv variant" of "guestfs_inspect_get_icon".
8153
8154       See "CALLS WITH OPTIONAL ARGUMENTS".
8155
8156   guestfs_inspect_get_major_version
8157        int
8158        guestfs_inspect_get_major_version (guestfs_h *g,
8159                                           const char *root);
8160
8161       This returns the major version number of the inspected operating
8162       system.
8163
8164       Windows uses a consistent versioning scheme which is not reflected in
8165       the popular public names used by the operating system.  Notably the
8166       operating system known as "Windows 7" is really version 6.1 (ie. major
8167       = 6, minor = 1).  You can find out the real versions corresponding to
8168       releases of Windows by consulting Wikipedia or MSDN.
8169
8170       If the version could not be determined, then 0 is returned.
8171
8172       Please read "INSPECTION" for more details.
8173
8174       On error this function returns -1.
8175
8176       (Added in 1.5.3)
8177
8178   guestfs_inspect_get_minor_version
8179        int
8180        guestfs_inspect_get_minor_version (guestfs_h *g,
8181                                           const char *root);
8182
8183       This returns the minor version number of the inspected operating
8184       system.
8185
8186       If the version could not be determined, then 0 is returned.
8187
8188       Please read "INSPECTION" for more details.  See also
8189       "guestfs_inspect_get_major_version".
8190
8191       On error this function returns -1.
8192
8193       (Added in 1.5.3)
8194
8195   guestfs_inspect_get_mountpoints
8196        char **
8197        guestfs_inspect_get_mountpoints (guestfs_h *g,
8198                                         const char *root);
8199
8200       This returns a hash of where we think the filesystems associated with
8201       this operating system should be mounted.  Callers should note that this
8202       is at best an educated guess made by reading configuration files such
8203       as /etc/fstab.  In particular note that this may return filesystems
8204       which are non-existent or not mountable and callers should be prepared
8205       to handle or ignore failures if they try to mount them.
8206
8207       Each element in the returned hashtable has a key which is the path of
8208       the mountpoint (eg. /boot) and a value which is the filesystem that
8209       would be mounted there (eg. /dev/sda1).
8210
8211       Non-mounted devices such as swap devices are not returned in this list.
8212
8213       For operating systems like Windows which still use drive letters, this
8214       call will only return an entry for the first drive "mounted on" /.  For
8215       information about the mapping of drive letters to partitions, see
8216       "guestfs_inspect_get_drive_mappings".
8217
8218       Please read "INSPECTION" for more details.  See also
8219       "guestfs_inspect_get_filesystems".
8220
8221       This function returns a NULL-terminated array of strings, or NULL if
8222       there was an error.  The array of strings will always have length
8223       "2n+1", where "n" keys and values alternate, followed by the trailing
8224       NULL entry.  The caller must free the strings and the array after use.
8225
8226       (Added in 1.5.3)
8227
8228   guestfs_inspect_get_osinfo
8229        char *
8230        guestfs_inspect_get_osinfo (guestfs_h *g,
8231                                    const char *root);
8232
8233       This function returns a possible short ID for libosinfo corresponding
8234       to the guest.
8235
8236       Note: The returned ID is only a guess by libguestfs, and nothing
8237       ensures that it actually exists in osinfo-db.
8238
8239       If no ID could not be determined, then the string "unknown" is
8240       returned.
8241
8242       This function returns a string, or NULL on error.  The caller must free
8243       the returned string after use.
8244
8245       (Added in 1.39.1)
8246
8247   guestfs_inspect_get_package_format
8248        char *
8249        guestfs_inspect_get_package_format (guestfs_h *g,
8250                                            const char *root);
8251
8252       This function and "guestfs_inspect_get_package_management" return the
8253       package format and package management tool used by the inspected
8254       operating system.  For example for Fedora these functions would return
8255       "rpm" (package format), and "yum" or "dnf" (package management).
8256
8257       This returns the string "unknown" if we could not determine the package
8258       format or if the operating system does not have a real packaging system
8259       (eg. Windows).
8260
8261       Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8262       "pkgsrc", "apk", "xbps".  Future versions of libguestfs may return
8263       other strings.
8264
8265       Please read "INSPECTION" for more details.
8266
8267       This function returns a string, or NULL on error.  The caller must free
8268       the returned string after use.
8269
8270       (Added in 1.7.5)
8271
8272   guestfs_inspect_get_package_management
8273        char *
8274        guestfs_inspect_get_package_management (guestfs_h *g,
8275                                                const char *root);
8276
8277       "guestfs_inspect_get_package_format" and this function return the
8278       package format and package management tool used by the inspected
8279       operating system.  For example for Fedora these functions would return
8280       "rpm" (package format), and "yum" or "dnf" (package management).
8281
8282       This returns the string "unknown" if we could not determine the package
8283       management tool or if the operating system does not have a real
8284       packaging system (eg. Windows).
8285
8286       Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8287       Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8288       "apk", "xbps".  Future versions of libguestfs may return other strings.
8289
8290       Please read "INSPECTION" for more details.
8291
8292       This function returns a string, or NULL on error.  The caller must free
8293       the returned string after use.
8294
8295       (Added in 1.7.5)
8296
8297   guestfs_inspect_get_product_name
8298        char *
8299        guestfs_inspect_get_product_name (guestfs_h *g,
8300                                          const char *root);
8301
8302       This returns the product name of the inspected operating system.  The
8303       product name is generally some freeform string which can be displayed
8304       to the user, but should not be parsed by programs.
8305
8306       If the product name could not be determined, then the string "unknown"
8307       is returned.
8308
8309       Please read "INSPECTION" for more details.
8310
8311       This function returns a string, or NULL on error.  The caller must free
8312       the returned string after use.
8313
8314       (Added in 1.5.3)
8315
8316   guestfs_inspect_get_product_variant
8317        char *
8318        guestfs_inspect_get_product_variant (guestfs_h *g,
8319                                             const char *root);
8320
8321       This returns the product variant of the inspected operating system.
8322
8323       For Windows guests, this returns the contents of the Registry key
8324       "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8325       which is usually a string such as "Client" or "Server" (other values
8326       are possible).  This can be used to distinguish consumer and enterprise
8327       versions of Windows that have the same version number (for example,
8328       Windows 7 and Windows 2008 Server are both version 6.1, but the former
8329       is "Client" and the latter is "Server").
8330
8331       For enterprise Linux guests, in future we intend this to return the
8332       product variant such as "Desktop", "Server" and so on.  But this is not
8333       implemented at present.
8334
8335       If the product variant could not be determined, then the string
8336       "unknown" is returned.
8337
8338       Please read "INSPECTION" for more details.  See also
8339       "guestfs_inspect_get_product_name",
8340       "guestfs_inspect_get_major_version".
8341
8342       This function returns a string, or NULL on error.  The caller must free
8343       the returned string after use.
8344
8345       (Added in 1.9.13)
8346
8347   guestfs_inspect_get_roots
8348        char **
8349        guestfs_inspect_get_roots (guestfs_h *g);
8350
8351       This function is a convenient way to get the list of root devices, as
8352       returned from a previous call to "guestfs_inspect_os", but without
8353       redoing the whole inspection process.
8354
8355       This returns an empty list if either no root devices were found or the
8356       caller has not called "guestfs_inspect_os".
8357
8358       Please read "INSPECTION" for more details.
8359
8360       This function returns a NULL-terminated array of strings (like
8361       environ(3)), or NULL if there was an error.  The caller must free the
8362       strings and the array after use.
8363
8364       (Added in 1.7.3)
8365
8366   guestfs_inspect_get_type
8367        char *
8368        guestfs_inspect_get_type (guestfs_h *g,
8369                                  const char *root);
8370
8371       This returns the type of the inspected operating system.  Currently
8372       defined types are:
8373
8374       "linux"
8375           Any Linux-based operating system.
8376
8377       "windows"
8378           Any Microsoft Windows operating system.
8379
8380       "freebsd"
8381           FreeBSD.
8382
8383       "netbsd"
8384           NetBSD.
8385
8386       "openbsd"
8387           OpenBSD.
8388
8389       "hurd"
8390           GNU/Hurd.
8391
8392       "dos"
8393           MS-DOS, FreeDOS and others.
8394
8395       "minix"
8396           MINIX.
8397
8398       "unknown"
8399           The operating system type could not be determined.
8400
8401       Future versions of libguestfs may return other strings here.  The
8402       caller should be prepared to handle any string.
8403
8404       Please read "INSPECTION" for more details.
8405
8406       This function returns a string, or NULL on error.  The caller must free
8407       the returned string after use.
8408
8409       (Added in 1.5.3)
8410
8411   guestfs_inspect_get_windows_current_control_set
8412        char *
8413        guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8414                                                         const char *root);
8415
8416       This returns the Windows CurrentControlSet of the inspected guest.  The
8417       CurrentControlSet is a registry key name such as "ControlSet001".
8418
8419       This call assumes that the guest is Windows and that the Registry could
8420       be examined by inspection.  If this is not the case then an error is
8421       returned.
8422
8423       Please read "INSPECTION" for more details.
8424
8425       This function returns a string, or NULL on error.  The caller must free
8426       the returned string after use.
8427
8428       (Added in 1.9.17)
8429
8430   guestfs_inspect_get_windows_software_hive
8431        char *
8432        guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8433                                                   const char *root);
8434
8435       This returns the path to the hive (binary Windows Registry file)
8436       corresponding to HKLM\SOFTWARE.
8437
8438       This call assumes that the guest is Windows and that the guest has a
8439       software hive file with the right name.  If this is not the case then
8440       an error is returned.  This call does not check that the hive is a
8441       valid Windows Registry hive.
8442
8443       You can use "guestfs_hivex_open" to read or write to the hive.
8444
8445       Please read "INSPECTION" for more details.
8446
8447       This function returns a string, or NULL on error.  The caller must free
8448       the returned string after use.
8449
8450       (Added in 1.35.26)
8451
8452   guestfs_inspect_get_windows_system_hive
8453        char *
8454        guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8455                                                 const char *root);
8456
8457       This returns the path to the hive (binary Windows Registry file)
8458       corresponding to HKLM\SYSTEM.
8459
8460       This call assumes that the guest is Windows and that the guest has a
8461       system hive file with the right name.  If this is not the case then an
8462       error is returned.  This call does not check that the hive is a valid
8463       Windows Registry hive.
8464
8465       You can use "guestfs_hivex_open" to read or write to the hive.
8466
8467       Please read "INSPECTION" for more details.
8468
8469       This function returns a string, or NULL on error.  The caller must free
8470       the returned string after use.
8471
8472       (Added in 1.35.26)
8473
8474   guestfs_inspect_get_windows_systemroot
8475        char *
8476        guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8477                                                const char *root);
8478
8479       This returns the Windows systemroot of the inspected guest.  The
8480       systemroot is a directory path such as /WINDOWS.
8481
8482       This call assumes that the guest is Windows and that the systemroot
8483       could be determined by inspection.  If this is not the case then an
8484       error is returned.
8485
8486       Please read "INSPECTION" for more details.
8487
8488       This function returns a string, or NULL on error.  The caller must free
8489       the returned string after use.
8490
8491       (Added in 1.5.25)
8492
8493   guestfs_inspect_is_live
8494        int
8495        guestfs_inspect_is_live (guestfs_h *g,
8496                                 const char *root);
8497
8498       This function is deprecated.  There is no replacement.  Consult the API
8499       documentation in guestfs(3) for further information.
8500
8501       Deprecated functions will not be removed from the API, but the fact
8502       that they are deprecated indicates that there are problems with correct
8503       use of these functions.
8504
8505       This is deprecated and always returns "false".
8506
8507       Please read "INSPECTION" for more details.
8508
8509       This function returns a C truth value on success or -1 on error.
8510
8511       (Added in 1.9.4)
8512
8513   guestfs_inspect_is_multipart
8514        int
8515        guestfs_inspect_is_multipart (guestfs_h *g,
8516                                      const char *root);
8517
8518       This function is deprecated.  There is no replacement.  Consult the API
8519       documentation in guestfs(3) for further information.
8520
8521       Deprecated functions will not be removed from the API, but the fact
8522       that they are deprecated indicates that there are problems with correct
8523       use of these functions.
8524
8525       This is deprecated and always returns "false".
8526
8527       Please read "INSPECTION" for more details.
8528
8529       This function returns a C truth value on success or -1 on error.
8530
8531       (Added in 1.9.4)
8532
8533   guestfs_inspect_is_netinst
8534        int
8535        guestfs_inspect_is_netinst (guestfs_h *g,
8536                                    const char *root);
8537
8538       This function is deprecated.  There is no replacement.  Consult the API
8539       documentation in guestfs(3) for further information.
8540
8541       Deprecated functions will not be removed from the API, but the fact
8542       that they are deprecated indicates that there are problems with correct
8543       use of these functions.
8544
8545       This is deprecated and always returns "false".
8546
8547       Please read "INSPECTION" for more details.
8548
8549       This function returns a C truth value on success or -1 on error.
8550
8551       (Added in 1.9.4)
8552
8553   guestfs_inspect_list_applications
8554        struct guestfs_application_list *
8555        guestfs_inspect_list_applications (guestfs_h *g,
8556                                           const char *root);
8557
8558       This function is deprecated.  In new code, use the
8559       "guestfs_inspect_list_applications2" call instead.
8560
8561       Deprecated functions will not be removed from the API, but the fact
8562       that they are deprecated indicates that there are problems with correct
8563       use of these functions.
8564
8565       Return the list of applications installed in the operating system.
8566
8567       Note: This call works differently from other parts of the inspection
8568       API.  You have to call "guestfs_inspect_os", then
8569       "guestfs_inspect_get_mountpoints", then mount up the disks, before
8570       calling this.  Listing applications is a significantly more difficult
8571       operation which requires access to the full filesystem.  Also note that
8572       unlike the other "guestfs_inspect_get_*" calls which are just returning
8573       data cached in the libguestfs handle, this call actually reads parts of
8574       the mounted filesystems during the call.
8575
8576       This returns an empty list if the inspection code was not able to
8577       determine the list of applications.
8578
8579       The application structure contains the following fields:
8580
8581       "app_name"
8582           The name of the application.  For Linux guests, this is the package
8583           name.
8584
8585       "app_display_name"
8586           The display name of the application, sometimes localized to the
8587           install language of the guest operating system.
8588
8589           If unavailable this is returned as an empty string "".  Callers
8590           needing to display something can use "app_name" instead.
8591
8592       "app_epoch"
8593           For package managers which use epochs, this contains the epoch of
8594           the package (an integer).  If unavailable, this is returned as 0.
8595
8596       "app_version"
8597           The version string of the application or package.  If unavailable
8598           this is returned as an empty string "".
8599
8600       "app_release"
8601           The release string of the application or package, for package
8602           managers that use this.  If unavailable this is returned as an
8603           empty string "".
8604
8605       "app_install_path"
8606           The installation path of the application (on operating systems such
8607           as Windows which use installation paths).  This path is in the
8608           format used by the guest operating system, it is not a libguestfs
8609           path.
8610
8611           If unavailable this is returned as an empty string "".
8612
8613       "app_trans_path"
8614           The install path translated into a libguestfs path.  If unavailable
8615           this is returned as an empty string "".
8616
8617       "app_publisher"
8618           The name of the publisher of the application, for package managers
8619           that use this.  If unavailable this is returned as an empty string
8620           "".
8621
8622       "app_url"
8623           The URL (eg. upstream URL) of the application.  If unavailable this
8624           is returned as an empty string "".
8625
8626       "app_source_package"
8627           For packaging systems which support this, the name of the source
8628           package.  If unavailable this is returned as an empty string "".
8629
8630       "app_summary"
8631           A short (usually one line) description of the application or
8632           package.  If unavailable this is returned as an empty string "".
8633
8634       "app_description"
8635           A longer description of the application or package.  If unavailable
8636           this is returned as an empty string "".
8637
8638       Please read "INSPECTION" for more details.
8639
8640       This function returns a "struct guestfs_application_list *", or NULL if
8641       there was an error.  The caller must call
8642       "guestfs_free_application_list" after use.
8643
8644       (Added in 1.7.8)
8645
8646   guestfs_inspect_list_applications2
8647        struct guestfs_application2_list *
8648        guestfs_inspect_list_applications2 (guestfs_h *g,
8649                                            const char *root);
8650
8651       Return the list of applications installed in the operating system.
8652
8653       Note: This call works differently from other parts of the inspection
8654       API.  You have to call "guestfs_inspect_os", then
8655       "guestfs_inspect_get_mountpoints", then mount up the disks, before
8656       calling this.  Listing applications is a significantly more difficult
8657       operation which requires access to the full filesystem.  Also note that
8658       unlike the other "guestfs_inspect_get_*" calls which are just returning
8659       data cached in the libguestfs handle, this call actually reads parts of
8660       the mounted filesystems during the call.
8661
8662       This returns an empty list if the inspection code was not able to
8663       determine the list of applications.
8664
8665       The application structure contains the following fields:
8666
8667       "app2_name"
8668           The name of the application.  For Linux guests, this is the package
8669           name.
8670
8671       "app2_display_name"
8672           The display name of the application, sometimes localized to the
8673           install language of the guest operating system.
8674
8675           If unavailable this is returned as an empty string "".  Callers
8676           needing to display something can use "app2_name" instead.
8677
8678       "app2_epoch"
8679           For package managers which use epochs, this contains the epoch of
8680           the package (an integer).  If unavailable, this is returned as 0.
8681
8682       "app2_version"
8683           The version string of the application or package.  If unavailable
8684           this is returned as an empty string "".
8685
8686       "app2_release"
8687           The release string of the application or package, for package
8688           managers that use this.  If unavailable this is returned as an
8689           empty string "".
8690
8691       "app2_arch"
8692           The architecture string of the application or package, for package
8693           managers that use this.  If unavailable this is returned as an
8694           empty string "".
8695
8696       "app2_install_path"
8697           The installation path of the application (on operating systems such
8698           as Windows which use installation paths).  This path is in the
8699           format used by the guest operating system, it is not a libguestfs
8700           path.
8701
8702           If unavailable this is returned as an empty string "".
8703
8704       "app2_trans_path"
8705           The install path translated into a libguestfs path.  If unavailable
8706           this is returned as an empty string "".
8707
8708       "app2_publisher"
8709           The name of the publisher of the application, for package managers
8710           that use this.  If unavailable this is returned as an empty string
8711           "".
8712
8713       "app2_url"
8714           The URL (eg. upstream URL) of the application.  If unavailable this
8715           is returned as an empty string "".
8716
8717       "app2_source_package"
8718           For packaging systems which support this, the name of the source
8719           package.  If unavailable this is returned as an empty string "".
8720
8721       "app2_summary"
8722           A short (usually one line) description of the application or
8723           package.  If unavailable this is returned as an empty string "".
8724
8725       "app2_description"
8726           A longer description of the application or package.  If unavailable
8727           this is returned as an empty string "".
8728
8729       Please read "INSPECTION" for more details.
8730
8731       This function returns a "struct guestfs_application2_list *", or NULL
8732       if there was an error.  The caller must call
8733       "guestfs_free_application2_list" after use.
8734
8735       (Added in 1.19.56)
8736
8737   guestfs_inspect_os
8738        char **
8739        guestfs_inspect_os (guestfs_h *g);
8740
8741       This function uses other libguestfs functions and certain heuristics to
8742       inspect the disk(s) (usually disks belonging to a virtual machine),
8743       looking for operating systems.
8744
8745       The list returned is empty if no operating systems were found.
8746
8747       If one operating system was found, then this returns a list with a
8748       single element, which is the name of the root filesystem of this
8749       operating system.  It is also possible for this function to return a
8750       list containing more than one element, indicating a dual-boot or multi-
8751       boot virtual machine, with each element being the root filesystem of
8752       one of the operating systems.
8753
8754       You can pass the root string(s) returned to other
8755       "guestfs_inspect_get_*" functions in order to query further information
8756       about each operating system, such as the name and version.
8757
8758       This function uses other libguestfs features such as "guestfs_mount_ro"
8759       and "guestfs_umount_all" in order to mount and unmount filesystems and
8760       look at the contents.  This should be called with no disks currently
8761       mounted.  The function may also use Augeas, so any existing Augeas
8762       handle will be closed.
8763
8764       This function cannot decrypt encrypted disks.  The caller must do that
8765       first (supplying the necessary keys) if the disk is encrypted.
8766
8767       Please read "INSPECTION" for more details.
8768
8769       See also "guestfs_list_filesystems".
8770
8771       This function returns a NULL-terminated array of strings (like
8772       environ(3)), or NULL if there was an error.  The caller must free the
8773       strings and the array after use.
8774
8775       (Added in 1.5.3)
8776
8777   guestfs_is_blockdev
8778        int
8779        guestfs_is_blockdev (guestfs_h *g,
8780                             const char *path);
8781
8782       This function is provided for backwards compatibility with earlier
8783       versions of libguestfs.  It simply calls "guestfs_is_blockdev_opts"
8784       with no optional arguments.
8785
8786       (Added in 1.5.10)
8787
8788   guestfs_is_blockdev_opts
8789        int
8790        guestfs_is_blockdev_opts (guestfs_h *g,
8791                                  const char *path,
8792                                  ...);
8793
8794       You may supply a list of optional arguments to this call.  Use zero or
8795       more of the following pairs of parameters, and terminate the list with
8796       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8797
8798        GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8799
8800       This returns "true" if and only if there is a block device with the
8801       given "path" name.
8802
8803       If the optional flag "followsymlinks" is true, then a symlink (or chain
8804       of symlinks) that ends with a block device also causes the function to
8805       return true.
8806
8807       This call only looks at files within the guest filesystem.  Libguestfs
8808       partitions and block devices (eg. /dev/sda) cannot be used as the
8809       "path" parameter of this call.
8810
8811       See also "guestfs_stat".
8812
8813       This function returns a C truth value on success or -1 on error.
8814
8815       (Added in 1.5.10)
8816
8817   guestfs_is_blockdev_opts_va
8818        int
8819        guestfs_is_blockdev_opts_va (guestfs_h *g,
8820                                     const char *path,
8821                                     va_list args);
8822
8823       This is the "va_list variant" of "guestfs_is_blockdev_opts".
8824
8825       See "CALLS WITH OPTIONAL ARGUMENTS".
8826
8827   guestfs_is_blockdev_opts_argv
8828        int
8829        guestfs_is_blockdev_opts_argv (guestfs_h *g,
8830                                       const char *path,
8831                                       const struct guestfs_is_blockdev_opts_argv *optargs);
8832
8833       This is the "argv variant" of "guestfs_is_blockdev_opts".
8834
8835       See "CALLS WITH OPTIONAL ARGUMENTS".
8836
8837   guestfs_is_busy
8838        int
8839        guestfs_is_busy (guestfs_h *g);
8840
8841       This always returns false.  This function is deprecated with no
8842       replacement.  Do not use this function.
8843
8844       For more information on states, see guestfs(3).
8845
8846       This function returns a C truth value on success or -1 on error.
8847
8848       (Added in 1.0.2)
8849
8850   guestfs_is_chardev
8851        int
8852        guestfs_is_chardev (guestfs_h *g,
8853                            const char *path);
8854
8855       This function is provided for backwards compatibility with earlier
8856       versions of libguestfs.  It simply calls "guestfs_is_chardev_opts" with
8857       no optional arguments.
8858
8859       (Added in 1.5.10)
8860
8861   guestfs_is_chardev_opts
8862        int
8863        guestfs_is_chardev_opts (guestfs_h *g,
8864                                 const char *path,
8865                                 ...);
8866
8867       You may supply a list of optional arguments to this call.  Use zero or
8868       more of the following pairs of parameters, and terminate the list with
8869       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8870
8871        GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8872
8873       This returns "true" if and only if there is a character device with the
8874       given "path" name.
8875
8876       If the optional flag "followsymlinks" is true, then a symlink (or chain
8877       of symlinks) that ends with a chardev also causes the function to
8878       return true.
8879
8880       See also "guestfs_stat".
8881
8882       This function returns a C truth value on success or -1 on error.
8883
8884       (Added in 1.5.10)
8885
8886   guestfs_is_chardev_opts_va
8887        int
8888        guestfs_is_chardev_opts_va (guestfs_h *g,
8889                                    const char *path,
8890                                    va_list args);
8891
8892       This is the "va_list variant" of "guestfs_is_chardev_opts".
8893
8894       See "CALLS WITH OPTIONAL ARGUMENTS".
8895
8896   guestfs_is_chardev_opts_argv
8897        int
8898        guestfs_is_chardev_opts_argv (guestfs_h *g,
8899                                      const char *path,
8900                                      const struct guestfs_is_chardev_opts_argv *optargs);
8901
8902       This is the "argv variant" of "guestfs_is_chardev_opts".
8903
8904       See "CALLS WITH OPTIONAL ARGUMENTS".
8905
8906   guestfs_is_config
8907        int
8908        guestfs_is_config (guestfs_h *g);
8909
8910       This returns true iff this handle is being configured (in the "CONFIG"
8911       state).
8912
8913       For more information on states, see guestfs(3).
8914
8915       This function returns a C truth value on success or -1 on error.
8916
8917       (Added in 1.0.2)
8918
8919   guestfs_is_dir
8920        int
8921        guestfs_is_dir (guestfs_h *g,
8922                        const char *path);
8923
8924       This function is provided for backwards compatibility with earlier
8925       versions of libguestfs.  It simply calls "guestfs_is_dir_opts" with no
8926       optional arguments.
8927
8928       (Added in 0.8)
8929
8930   guestfs_is_dir_opts
8931        int
8932        guestfs_is_dir_opts (guestfs_h *g,
8933                             const char *path,
8934                             ...);
8935
8936       You may supply a list of optional arguments to this call.  Use zero or
8937       more of the following pairs of parameters, and terminate the list with
8938       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8939
8940        GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8941
8942       This returns "true" if and only if there is a directory with the given
8943       "path" name.  Note that it returns false for other objects like files.
8944
8945       If the optional flag "followsymlinks" is true, then a symlink (or chain
8946       of symlinks) that ends with a directory also causes the function to
8947       return true.
8948
8949       See also "guestfs_stat".
8950
8951       This function returns a C truth value on success or -1 on error.
8952
8953       (Added in 0.8)
8954
8955   guestfs_is_dir_opts_va
8956        int
8957        guestfs_is_dir_opts_va (guestfs_h *g,
8958                                const char *path,
8959                                va_list args);
8960
8961       This is the "va_list variant" of "guestfs_is_dir_opts".
8962
8963       See "CALLS WITH OPTIONAL ARGUMENTS".
8964
8965   guestfs_is_dir_opts_argv
8966        int
8967        guestfs_is_dir_opts_argv (guestfs_h *g,
8968                                  const char *path,
8969                                  const struct guestfs_is_dir_opts_argv *optargs);
8970
8971       This is the "argv variant" of "guestfs_is_dir_opts".
8972
8973       See "CALLS WITH OPTIONAL ARGUMENTS".
8974
8975   guestfs_is_fifo
8976        int
8977        guestfs_is_fifo (guestfs_h *g,
8978                         const char *path);
8979
8980       This function is provided for backwards compatibility with earlier
8981       versions of libguestfs.  It simply calls "guestfs_is_fifo_opts" with no
8982       optional arguments.
8983
8984       (Added in 1.5.10)
8985
8986   guestfs_is_fifo_opts
8987        int
8988        guestfs_is_fifo_opts (guestfs_h *g,
8989                              const char *path,
8990                              ...);
8991
8992       You may supply a list of optional arguments to this call.  Use zero or
8993       more of the following pairs of parameters, and terminate the list with
8994       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
8995
8996        GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8997
8998       This returns "true" if and only if there is a FIFO (named pipe) with
8999       the given "path" name.
9000
9001       If the optional flag "followsymlinks" is true, then a symlink (or chain
9002       of symlinks) that ends with a FIFO also causes the function to return
9003       true.
9004
9005       See also "guestfs_stat".
9006
9007       This function returns a C truth value on success or -1 on error.
9008
9009       (Added in 1.5.10)
9010
9011   guestfs_is_fifo_opts_va
9012        int
9013        guestfs_is_fifo_opts_va (guestfs_h *g,
9014                                 const char *path,
9015                                 va_list args);
9016
9017       This is the "va_list variant" of "guestfs_is_fifo_opts".
9018
9019       See "CALLS WITH OPTIONAL ARGUMENTS".
9020
9021   guestfs_is_fifo_opts_argv
9022        int
9023        guestfs_is_fifo_opts_argv (guestfs_h *g,
9024                                   const char *path,
9025                                   const struct guestfs_is_fifo_opts_argv *optargs);
9026
9027       This is the "argv variant" of "guestfs_is_fifo_opts".
9028
9029       See "CALLS WITH OPTIONAL ARGUMENTS".
9030
9031   guestfs_is_file
9032        int
9033        guestfs_is_file (guestfs_h *g,
9034                         const char *path);
9035
9036       This function is provided for backwards compatibility with earlier
9037       versions of libguestfs.  It simply calls "guestfs_is_file_opts" with no
9038       optional arguments.
9039
9040       (Added in 0.8)
9041
9042   guestfs_is_file_opts
9043        int
9044        guestfs_is_file_opts (guestfs_h *g,
9045                              const char *path,
9046                              ...);
9047
9048       You may supply a list of optional arguments to this call.  Use zero or
9049       more of the following pairs of parameters, and terminate the list with
9050       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
9051
9052        GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9053
9054       This returns "true" if and only if there is a regular file with the
9055       given "path" name.  Note that it returns false for other objects like
9056       directories.
9057
9058       If the optional flag "followsymlinks" is true, then a symlink (or chain
9059       of symlinks) that ends with a file also causes the function to return
9060       true.
9061
9062       See also "guestfs_stat".
9063
9064       This function returns a C truth value on success or -1 on error.
9065
9066       (Added in 0.8)
9067
9068   guestfs_is_file_opts_va
9069        int
9070        guestfs_is_file_opts_va (guestfs_h *g,
9071                                 const char *path,
9072                                 va_list args);
9073
9074       This is the "va_list variant" of "guestfs_is_file_opts".
9075
9076       See "CALLS WITH OPTIONAL ARGUMENTS".
9077
9078   guestfs_is_file_opts_argv
9079        int
9080        guestfs_is_file_opts_argv (guestfs_h *g,
9081                                   const char *path,
9082                                   const struct guestfs_is_file_opts_argv *optargs);
9083
9084       This is the "argv variant" of "guestfs_is_file_opts".
9085
9086       See "CALLS WITH OPTIONAL ARGUMENTS".
9087
9088   guestfs_is_launching
9089        int
9090        guestfs_is_launching (guestfs_h *g);
9091
9092       This returns true iff this handle is launching the subprocess (in the
9093       "LAUNCHING" state).
9094
9095       For more information on states, see guestfs(3).
9096
9097       This function returns a C truth value on success or -1 on error.
9098
9099       (Added in 1.0.2)
9100
9101   guestfs_is_lv
9102        int
9103        guestfs_is_lv (guestfs_h *g,
9104                       const char *mountable);
9105
9106       This command tests whether "mountable" is a logical volume, and returns
9107       true iff this is the case.
9108
9109       This function returns a C truth value on success or -1 on error.
9110
9111       (Added in 1.5.3)
9112
9113   guestfs_is_ready
9114        int
9115        guestfs_is_ready (guestfs_h *g);
9116
9117       This returns true iff this handle is ready to accept commands (in the
9118       "READY" state).
9119
9120       For more information on states, see guestfs(3).
9121
9122       This function returns a C truth value on success or -1 on error.
9123
9124       (Added in 1.0.2)
9125
9126   guestfs_is_socket
9127        int
9128        guestfs_is_socket (guestfs_h *g,
9129                           const char *path);
9130
9131       This function is provided for backwards compatibility with earlier
9132       versions of libguestfs.  It simply calls "guestfs_is_socket_opts" with
9133       no optional arguments.
9134
9135       (Added in 1.5.10)
9136
9137   guestfs_is_socket_opts
9138        int
9139        guestfs_is_socket_opts (guestfs_h *g,
9140                                const char *path,
9141                                ...);
9142
9143       You may supply a list of optional arguments to this call.  Use zero or
9144       more of the following pairs of parameters, and terminate the list with
9145       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
9146
9147        GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9148
9149       This returns "true" if and only if there is a Unix domain socket with
9150       the given "path" name.
9151
9152       If the optional flag "followsymlinks" is true, then a symlink (or chain
9153       of symlinks) that ends with a socket also causes the function to return
9154       true.
9155
9156       See also "guestfs_stat".
9157
9158       This function returns a C truth value on success or -1 on error.
9159
9160       (Added in 1.5.10)
9161
9162   guestfs_is_socket_opts_va
9163        int
9164        guestfs_is_socket_opts_va (guestfs_h *g,
9165                                   const char *path,
9166                                   va_list args);
9167
9168       This is the "va_list variant" of "guestfs_is_socket_opts".
9169
9170       See "CALLS WITH OPTIONAL ARGUMENTS".
9171
9172   guestfs_is_socket_opts_argv
9173        int
9174        guestfs_is_socket_opts_argv (guestfs_h *g,
9175                                     const char *path,
9176                                     const struct guestfs_is_socket_opts_argv *optargs);
9177
9178       This is the "argv variant" of "guestfs_is_socket_opts".
9179
9180       See "CALLS WITH OPTIONAL ARGUMENTS".
9181
9182   guestfs_is_symlink
9183        int
9184        guestfs_is_symlink (guestfs_h *g,
9185                            const char *path);
9186
9187       This returns "true" if and only if there is a symbolic link with the
9188       given "path" name.
9189
9190       See also "guestfs_stat".
9191
9192       This function returns a C truth value on success or -1 on error.
9193
9194       (Added in 1.5.10)
9195
9196   guestfs_is_whole_device
9197        int
9198        guestfs_is_whole_device (guestfs_h *g,
9199                                 const char *device);
9200
9201       This returns "true" if and only if "device" refers to a whole block
9202       device. That is, not a partition or a logical device.
9203
9204       This function returns a C truth value on success or -1 on error.
9205
9206       (Added in 1.21.9)
9207
9208   guestfs_is_zero
9209        int
9210        guestfs_is_zero (guestfs_h *g,
9211                         const char *path);
9212
9213       This returns true iff the file exists and the file is empty or it
9214       contains all zero bytes.
9215
9216       This function returns a C truth value on success or -1 on error.
9217
9218       (Added in 1.11.8)
9219
9220   guestfs_is_zero_device
9221        int
9222        guestfs_is_zero_device (guestfs_h *g,
9223                                const char *device);
9224
9225       This returns true iff the device exists and contains all zero bytes.
9226
9227       Note that for large devices this can take a long time to run.
9228
9229       This function returns a C truth value on success or -1 on error.
9230
9231       (Added in 1.11.8)
9232
9233   guestfs_isoinfo
9234        struct guestfs_isoinfo *
9235        guestfs_isoinfo (guestfs_h *g,
9236                         const char *isofile);
9237
9238       This is the same as "guestfs_isoinfo_device" except that it works for
9239       an ISO file located inside some other mounted filesystem.  Note that in
9240       the common case where you have added an ISO file as a libguestfs
9241       device, you would not call this.  Instead you would call
9242       "guestfs_isoinfo_device".
9243
9244       This function returns a "struct guestfs_isoinfo *", or NULL if there
9245       was an error.  The caller must call "guestfs_free_isoinfo" after use.
9246
9247       (Added in 1.17.19)
9248
9249   guestfs_isoinfo_device
9250        struct guestfs_isoinfo *
9251        guestfs_isoinfo_device (guestfs_h *g,
9252                                const char *device);
9253
9254       "device" is an ISO device.  This returns a struct of information read
9255       from the primary volume descriptor (the ISO equivalent of the
9256       superblock) of the device.
9257
9258       Usually it is more efficient to use the isoinfo(1) command with the -d
9259       option on the host to analyze ISO files, instead of going through
9260       libguestfs.
9261
9262       For information on the primary volume descriptor fields, see
9263       https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9264
9265       This function returns a "struct guestfs_isoinfo *", or NULL if there
9266       was an error.  The caller must call "guestfs_free_isoinfo" after use.
9267
9268       (Added in 1.17.19)
9269
9270   guestfs_journal_close
9271        int
9272        guestfs_journal_close (guestfs_h *g);
9273
9274       Close the journal handle.
9275
9276       This function returns 0 on success or -1 on error.
9277
9278       This function depends on the feature "journal".  See also
9279       "guestfs_feature_available".
9280
9281       (Added in 1.23.11)
9282
9283   guestfs_journal_get
9284        struct guestfs_xattr_list *
9285        guestfs_journal_get (guestfs_h *g);
9286
9287       Read the current journal entry.  This returns all the fields in the
9288       journal as a set of "(attrname, attrval)" pairs.  The "attrname" is the
9289       field name (a string).
9290
9291       The "attrval" is the field value (a binary blob, often but not always a
9292       string).  Please note that "attrval" is a byte array, not a
9293       \0-terminated C string.
9294
9295       The length of data may be truncated to the data threshold (see:
9296       "guestfs_journal_set_data_threshold",
9297       "guestfs_journal_get_data_threshold").
9298
9299       If you set the data threshold to unlimited (0) then this call can read
9300       a journal entry of any size, ie. it is not limited by the libguestfs
9301       protocol.
9302
9303       This function returns a "struct guestfs_xattr_list *", or NULL if there
9304       was an error.  The caller must call "guestfs_free_xattr_list" after
9305       use.
9306
9307       This function depends on the feature "journal".  See also
9308       "guestfs_feature_available".
9309
9310       (Added in 1.23.11)
9311
9312   guestfs_journal_get_data_threshold
9313        int64_t
9314        guestfs_journal_get_data_threshold (guestfs_h *g);
9315
9316       Get the current data threshold for reading journal entries.  This is a
9317       hint to the journal that it may truncate data fields to this size when
9318       reading them (note also that it may not truncate them).  If this
9319       returns 0, then the threshold is unlimited.
9320
9321       See also "guestfs_journal_set_data_threshold".
9322
9323       On error this function returns -1.
9324
9325       This function depends on the feature "journal".  See also
9326       "guestfs_feature_available".
9327
9328       (Added in 1.23.11)
9329
9330   guestfs_journal_get_realtime_usec
9331        int64_t
9332        guestfs_journal_get_realtime_usec (guestfs_h *g);
9333
9334       Get the realtime (wallclock) timestamp of the current journal entry.
9335
9336       On error this function returns -1.
9337
9338       This function depends on the feature "journal".  See also
9339       "guestfs_feature_available".
9340
9341       (Added in 1.27.18)
9342
9343   guestfs_journal_next
9344        int
9345        guestfs_journal_next (guestfs_h *g);
9346
9347       Move to the next journal entry.  You have to call this at least once
9348       after opening the handle before you are able to read data.
9349
9350       The returned boolean tells you if there are any more journal records to
9351       read.  "true" means you can read the next record (eg. using
9352       "guestfs_journal_get"), and "false" means you have reached the end of
9353       the journal.
9354
9355       This function returns a C truth value on success or -1 on error.
9356
9357       This function depends on the feature "journal".  See also
9358       "guestfs_feature_available".
9359
9360       (Added in 1.23.11)
9361
9362   guestfs_journal_open
9363        int
9364        guestfs_journal_open (guestfs_h *g,
9365                              const char *directory);
9366
9367       Open the systemd journal located in directory.  Any previously opened
9368       journal handle is closed.
9369
9370       The contents of the journal can be read using "guestfs_journal_next"
9371       and "guestfs_journal_get".
9372
9373       After you have finished using the journal, you should close the handle
9374       by calling "guestfs_journal_close".
9375
9376       This function returns 0 on success or -1 on error.
9377
9378       This function depends on the feature "journal".  See also
9379       "guestfs_feature_available".
9380
9381       (Added in 1.23.11)
9382
9383   guestfs_journal_set_data_threshold
9384        int
9385        guestfs_journal_set_data_threshold (guestfs_h *g,
9386                                            int64_t threshold);
9387
9388       Set the data threshold for reading journal entries.  This is a hint to
9389       the journal that it may truncate data fields to this size when reading
9390       them (note also that it may not truncate them).  If you set this to 0,
9391       then the threshold is unlimited.
9392
9393       See also "guestfs_journal_get_data_threshold".
9394
9395       This function returns 0 on success or -1 on error.
9396
9397       This function depends on the feature "journal".  See also
9398       "guestfs_feature_available".
9399
9400       (Added in 1.23.11)
9401
9402   guestfs_journal_skip
9403        int64_t
9404        guestfs_journal_skip (guestfs_h *g,
9405                              int64_t skip);
9406
9407       Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9408
9409       The number of entries actually skipped is returned (note "rskip ≥ 0").
9410       If this is not the same as the absolute value of the skip parameter
9411       ("|skip|") you passed in then it means you have reached the end or the
9412       start of the journal.
9413
9414       On error this function returns -1.
9415
9416       This function depends on the feature "journal".  See also
9417       "guestfs_feature_available".
9418
9419       (Added in 1.23.11)
9420
9421   guestfs_kill_subprocess
9422        int
9423        guestfs_kill_subprocess (guestfs_h *g);
9424
9425       This function is deprecated.  In new code, use the "guestfs_shutdown"
9426       call instead.
9427
9428       Deprecated functions will not be removed from the API, but the fact
9429       that they are deprecated indicates that there are problems with correct
9430       use of these functions.
9431
9432       This kills the hypervisor.
9433
9434       Do not call this.  See: "guestfs_shutdown" instead.
9435
9436       This function returns 0 on success or -1 on error.
9437
9438       (Added in 0.3)
9439
9440   guestfs_launch
9441        int
9442        guestfs_launch (guestfs_h *g);
9443
9444       You should call this after configuring the handle (eg. adding drives)
9445       but before performing any actions.
9446
9447       Do not call "guestfs_launch" twice on the same handle.  Although it
9448       will not give an error (for historical reasons), the precise behaviour
9449       when you do this is not well defined.  Handles are very cheap to
9450       create, so create a new one for each launch.
9451
9452       This function returns 0 on success or -1 on error.
9453
9454       This long-running command can generate progress notification messages
9455       so that the caller can display a progress bar or indicator.  To receive
9456       these messages, the caller must register a progress event callback.
9457       See "GUESTFS_EVENT_PROGRESS".
9458
9459       (Added in 0.3)
9460
9461   guestfs_lchown
9462        int
9463        guestfs_lchown (guestfs_h *g,
9464                        int owner,
9465                        int group,
9466                        const char *path);
9467
9468       Change the file owner to "owner" and group to "group".  This is like
9469       "guestfs_chown" but if "path" is a symlink then the link itself is
9470       changed, not the target.
9471
9472       Only numeric uid and gid are supported.  If you want to use names, you
9473       will need to locate and parse the password file yourself (Augeas
9474       support makes this relatively easy).
9475
9476       This function returns 0 on success or -1 on error.
9477
9478       (Added in 1.0.77)
9479
9480   guestfs_ldmtool_create_all
9481        int
9482        guestfs_ldmtool_create_all (guestfs_h *g);
9483
9484       This function scans all block devices looking for Windows dynamic disk
9485       volumes and partitions, and creates devices for any that were found.
9486
9487       Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9488       return all devices.
9489
9490       Note that you don't normally need to call this explicitly, since it is
9491       done automatically at "guestfs_launch" time.  However you might want to
9492       call this function if you have hotplugged disks or have just created a
9493       Windows dynamic disk.
9494
9495       This function returns 0 on success or -1 on error.
9496
9497       This function depends on the feature "ldm".  See also
9498       "guestfs_feature_available".
9499
9500       (Added in 1.20.0)
9501
9502   guestfs_ldmtool_diskgroup_disks
9503        char **
9504        guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9505                                         const char *diskgroup);
9506
9507       Return the disks in a Windows dynamic disk group.  The "diskgroup"
9508       parameter should be the GUID of a disk group, one element from the list
9509       returned by "guestfs_ldmtool_scan".
9510
9511       This function returns a NULL-terminated array of strings (like
9512       environ(3)), or NULL if there was an error.  The caller must free the
9513       strings and the array after use.
9514
9515       This function depends on the feature "ldm".  See also
9516       "guestfs_feature_available".
9517
9518       (Added in 1.20.0)
9519
9520   guestfs_ldmtool_diskgroup_name
9521        char *
9522        guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9523                                        const char *diskgroup);
9524
9525       Return the name of a Windows dynamic disk group.  The "diskgroup"
9526       parameter should be the GUID of a disk group, one element from the list
9527       returned by "guestfs_ldmtool_scan".
9528
9529       This function returns a string, or NULL on error.  The caller must free
9530       the returned string after use.
9531
9532       This function depends on the feature "ldm".  See also
9533       "guestfs_feature_available".
9534
9535       (Added in 1.20.0)
9536
9537   guestfs_ldmtool_diskgroup_volumes
9538        char **
9539        guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9540                                           const char *diskgroup);
9541
9542       Return the volumes in a Windows dynamic disk group.  The "diskgroup"
9543       parameter should be the GUID of a disk group, one element from the list
9544       returned by "guestfs_ldmtool_scan".
9545
9546       This function returns a NULL-terminated array of strings (like
9547       environ(3)), or NULL if there was an error.  The caller must free the
9548       strings and the array after use.
9549
9550       This function depends on the feature "ldm".  See also
9551       "guestfs_feature_available".
9552
9553       (Added in 1.20.0)
9554
9555   guestfs_ldmtool_remove_all
9556        int
9557        guestfs_ldmtool_remove_all (guestfs_h *g);
9558
9559       This is essentially the opposite of "guestfs_ldmtool_create_all".  It
9560       removes the device mapper mappings for all Windows dynamic disk volumes
9561
9562       This function returns 0 on success or -1 on error.
9563
9564       This function depends on the feature "ldm".  See also
9565       "guestfs_feature_available".
9566
9567       (Added in 1.20.0)
9568
9569   guestfs_ldmtool_scan
9570        char **
9571        guestfs_ldmtool_scan (guestfs_h *g);
9572
9573       This function scans for Windows dynamic disks.  It returns a list of
9574       identifiers (GUIDs) for all disk groups that were found.  These
9575       identifiers can be passed to other "guestfs_ldmtool_*" functions.
9576
9577       This function scans all block devices.  To scan a subset of block
9578       devices, call "guestfs_ldmtool_scan_devices" instead.
9579
9580       This function returns a NULL-terminated array of strings (like
9581       environ(3)), or NULL if there was an error.  The caller must free the
9582       strings and the array after use.
9583
9584       This function depends on the feature "ldm".  See also
9585       "guestfs_feature_available".
9586
9587       (Added in 1.20.0)
9588
9589   guestfs_ldmtool_scan_devices
9590        char **
9591        guestfs_ldmtool_scan_devices (guestfs_h *g,
9592                                      char *const *devices);
9593
9594       This function scans for Windows dynamic disks.  It returns a list of
9595       identifiers (GUIDs) for all disk groups that were found.  These
9596       identifiers can be passed to other "guestfs_ldmtool_*" functions.
9597
9598       The parameter "devices" is a list of block devices which are scanned.
9599       If this list is empty, all block devices are scanned.
9600
9601       This function returns a NULL-terminated array of strings (like
9602       environ(3)), or NULL if there was an error.  The caller must free the
9603       strings and the array after use.
9604
9605       This function depends on the feature "ldm".  See also
9606       "guestfs_feature_available".
9607
9608       (Added in 1.20.0)
9609
9610   guestfs_ldmtool_volume_hint
9611        char *
9612        guestfs_ldmtool_volume_hint (guestfs_h *g,
9613                                     const char *diskgroup,
9614                                     const char *volume);
9615
9616       Return the hint field of the volume named "volume" in the disk group
9617       with GUID "diskgroup".  This may not be defined, in which case the
9618       empty string is returned.  The hint field is often, though not always,
9619       the name of a Windows drive, eg. "E:".
9620
9621       This function returns a string, or NULL on error.  The caller must free
9622       the returned string after use.
9623
9624       This function depends on the feature "ldm".  See also
9625       "guestfs_feature_available".
9626
9627       (Added in 1.20.0)
9628
9629   guestfs_ldmtool_volume_partitions
9630        char **
9631        guestfs_ldmtool_volume_partitions (guestfs_h *g,
9632                                           const char *diskgroup,
9633                                           const char *volume);
9634
9635       Return the list of partitions in the volume named "volume" in the disk
9636       group with GUID "diskgroup".
9637
9638       This function returns a NULL-terminated array of strings (like
9639       environ(3)), or NULL if there was an error.  The caller must free the
9640       strings and the array after use.
9641
9642       This function depends on the feature "ldm".  See also
9643       "guestfs_feature_available".
9644
9645       (Added in 1.20.0)
9646
9647   guestfs_ldmtool_volume_type
9648        char *
9649        guestfs_ldmtool_volume_type (guestfs_h *g,
9650                                     const char *diskgroup,
9651                                     const char *volume);
9652
9653       Return the type of the volume named "volume" in the disk group with
9654       GUID "diskgroup".
9655
9656       Possible volume types that can be returned here include: "simple",
9657       "spanned", "striped", "mirrored", "raid5".  Other types may also be
9658       returned.
9659
9660       This function returns a string, or NULL on error.  The caller must free
9661       the returned string after use.
9662
9663       This function depends on the feature "ldm".  See also
9664       "guestfs_feature_available".
9665
9666       (Added in 1.20.0)
9667
9668   guestfs_lgetxattr
9669        char *
9670        guestfs_lgetxattr (guestfs_h *g,
9671                           const char *path,
9672                           const char *name,
9673                           size_t *size_r);
9674
9675       Get a single extended attribute from file "path" named "name".  If
9676       "path" is a symlink, then this call returns an extended attribute from
9677       the symlink.
9678
9679       Normally it is better to get all extended attributes from a file in one
9680       go by calling "guestfs_getxattrs".  However some Linux filesystem
9681       implementations are buggy and do not provide a way to list out
9682       attributes.  For these filesystems (notably ntfs-3g) you have to know
9683       the names of the extended attributes you want in advance and call this
9684       function.
9685
9686       Extended attribute values are blobs of binary data.  If there is no
9687       extended attribute named "name", this returns an error.
9688
9689       See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9690
9691       This function returns a buffer, or NULL on error.  The size of the
9692       returned buffer is written to *size_r.  The caller must free the
9693       returned buffer after use.
9694
9695       This function depends on the feature "linuxxattrs".  See also
9696       "guestfs_feature_available".
9697
9698       (Added in 1.7.24)
9699
9700   guestfs_lgetxattrs
9701        struct guestfs_xattr_list *
9702        guestfs_lgetxattrs (guestfs_h *g,
9703                            const char *path);
9704
9705       This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9706       link, then it returns the extended attributes of the link itself.
9707
9708       This function returns a "struct guestfs_xattr_list *", or NULL if there
9709       was an error.  The caller must call "guestfs_free_xattr_list" after
9710       use.
9711
9712       This function depends on the feature "linuxxattrs".  See also
9713       "guestfs_feature_available".
9714
9715       (Added in 1.0.59)
9716
9717   guestfs_list_9p
9718        char **
9719        guestfs_list_9p (guestfs_h *g);
9720
9721       List all 9p filesystems attached to the guest.  A list of mount tags is
9722       returned.
9723
9724       This function returns a NULL-terminated array of strings (like
9725       environ(3)), or NULL if there was an error.  The caller must free the
9726       strings and the array after use.
9727
9728       (Added in 1.11.12)
9729
9730   guestfs_list_devices
9731        char **
9732        guestfs_list_devices (guestfs_h *g);
9733
9734       List all the block devices.
9735
9736       The full block device names are returned, eg. /dev/sda.
9737
9738       See also "guestfs_list_filesystems".
9739
9740       This function returns a NULL-terminated array of strings (like
9741       environ(3)), or NULL if there was an error.  The caller must free the
9742       strings and the array after use.
9743
9744       (Added in 0.4)
9745
9746   guestfs_list_disk_labels
9747        char **
9748        guestfs_list_disk_labels (guestfs_h *g);
9749
9750       If you add drives using the optional "label" parameter of
9751       "guestfs_add_drive_opts", you can use this call to map between disk
9752       labels, and raw block device and partition names (like /dev/sda and
9753       /dev/sda1).
9754
9755       This returns a hashtable, where keys are the disk labels (without the
9756       /dev/disk/guestfs prefix), and the values are the full raw block device
9757       and partition names (eg. /dev/sda and /dev/sda1).
9758
9759       This function returns a NULL-terminated array of strings, or NULL if
9760       there was an error.  The array of strings will always have length
9761       "2n+1", where "n" keys and values alternate, followed by the trailing
9762       NULL entry.  The caller must free the strings and the array after use.
9763
9764       (Added in 1.19.49)
9765
9766   guestfs_list_dm_devices
9767        char **
9768        guestfs_list_dm_devices (guestfs_h *g);
9769
9770       List all device mapper devices.
9771
9772       The returned list contains /dev/mapper/* devices, eg. ones created by a
9773       previous call to "guestfs_luks_open".
9774
9775       Device mapper devices which correspond to logical volumes are not
9776       returned in this list.  Call "guestfs_lvs" if you want to list logical
9777       volumes.
9778
9779       This function returns a NULL-terminated array of strings (like
9780       environ(3)), or NULL if there was an error.  The caller must free the
9781       strings and the array after use.
9782
9783       (Added in 1.11.15)
9784
9785   guestfs_list_filesystems
9786        char **
9787        guestfs_list_filesystems (guestfs_h *g);
9788
9789       This inspection command looks for filesystems on partitions, block
9790       devices and logical volumes, returning a list of "mountables"
9791       containing filesystems and their type.
9792
9793       The return value is a hash, where the keys are the devices containing
9794       filesystems, and the values are the filesystem types.  For example:
9795
9796        "/dev/sda1" => "ntfs"
9797        "/dev/sda2" => "ext2"
9798        "/dev/vg_guest/lv_root" => "ext4"
9799        "/dev/vg_guest/lv_swap" => "swap"
9800
9801       The key is not necessarily a block device. It may also be an opaque
9802       ‘mountable’ string which can be passed to "guestfs_mount".
9803
9804       The value can have the special value "unknown", meaning the content of
9805       the device is undetermined or empty.  "swap" means a Linux swap
9806       partition.
9807
9808       In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9809       might have included "guestfs_mount" and "guestfs_umount", and therefore
9810       you had to use this soon after launch and only when nothing else was
9811       mounted.  This restriction is removed in libguestfs ≥ 1.38.
9812
9813       Not all of the filesystems returned will be mountable.  In particular,
9814       swap partitions are returned in the list.  Also this command does not
9815       check that each filesystem found is valid and mountable, and some
9816       filesystems might be mountable but require special options.
9817       Filesystems may not all belong to a single logical operating system
9818       (use "guestfs_inspect_os" to look for OSes).
9819
9820       This function returns a NULL-terminated array of strings, or NULL if
9821       there was an error.  The array of strings will always have length
9822       "2n+1", where "n" keys and values alternate, followed by the trailing
9823       NULL entry.  The caller must free the strings and the array after use.
9824
9825       (Added in 1.5.15)
9826
9827   guestfs_list_ldm_partitions
9828        char **
9829        guestfs_list_ldm_partitions (guestfs_h *g);
9830
9831       This function returns all Windows dynamic disk partitions that were
9832       found at launch time.  It returns a list of device names.
9833
9834       This function returns a NULL-terminated array of strings (like
9835       environ(3)), or NULL if there was an error.  The caller must free the
9836       strings and the array after use.
9837
9838       This function depends on the feature "ldm".  See also
9839       "guestfs_feature_available".
9840
9841       (Added in 1.20.0)
9842
9843   guestfs_list_ldm_volumes
9844        char **
9845        guestfs_list_ldm_volumes (guestfs_h *g);
9846
9847       This function returns all Windows dynamic disk volumes that were found
9848       at launch time.  It returns a list of device names.
9849
9850       This function returns a NULL-terminated array of strings (like
9851       environ(3)), or NULL if there was an error.  The caller must free the
9852       strings and the array after use.
9853
9854       This function depends on the feature "ldm".  See also
9855       "guestfs_feature_available".
9856
9857       (Added in 1.20.0)
9858
9859   guestfs_list_md_devices
9860        char **
9861        guestfs_list_md_devices (guestfs_h *g);
9862
9863       List all Linux md devices.
9864
9865       This function returns a NULL-terminated array of strings (like
9866       environ(3)), or NULL if there was an error.  The caller must free the
9867       strings and the array after use.
9868
9869       (Added in 1.15.4)
9870
9871   guestfs_list_partitions
9872        char **
9873        guestfs_list_partitions (guestfs_h *g);
9874
9875       List all the partitions detected on all block devices.
9876
9877       The full partition device names are returned, eg. /dev/sda1
9878
9879       This does not return logical volumes.  For that you will need to call
9880       "guestfs_lvs".
9881
9882       See also "guestfs_list_filesystems".
9883
9884       This function returns a NULL-terminated array of strings (like
9885       environ(3)), or NULL if there was an error.  The caller must free the
9886       strings and the array after use.
9887
9888       (Added in 0.4)
9889
9890   guestfs_ll
9891        char *
9892        guestfs_ll (guestfs_h *g,
9893                    const char *directory);
9894
9895       List the files in directory (relative to the root directory, there is
9896       no cwd) in the format of "ls -la".
9897
9898       This command is mostly useful for interactive sessions.  It is not
9899       intended that you try to parse the output string.
9900
9901       This function returns a string, or NULL on error.  The caller must free
9902       the returned string after use.
9903
9904       (Added in 0.4)
9905
9906   guestfs_llz
9907        char *
9908        guestfs_llz (guestfs_h *g,
9909                     const char *directory);
9910
9911       This function is deprecated.  In new code, use the "guestfs_lgetxattrs"
9912       call instead.
9913
9914       Deprecated functions will not be removed from the API, but the fact
9915       that they are deprecated indicates that there are problems with correct
9916       use of these functions.
9917
9918       List the files in directory in the format of "ls -laZ".
9919
9920       This command is mostly useful for interactive sessions.  It is not
9921       intended that you try to parse the output string.
9922
9923       This function returns a string, or NULL on error.  The caller must free
9924       the returned string after use.
9925
9926       (Added in 1.17.6)
9927
9928   guestfs_ln
9929        int
9930        guestfs_ln (guestfs_h *g,
9931                    const char *target,
9932                    const char *linkname);
9933
9934       This command creates a hard link.
9935
9936       This function returns 0 on success or -1 on error.
9937
9938       (Added in 1.0.66)
9939
9940   guestfs_ln_f
9941        int
9942        guestfs_ln_f (guestfs_h *g,
9943                      const char *target,
9944                      const char *linkname);
9945
9946       This command creates a hard link, removing the link "linkname" if it
9947       exists already.
9948
9949       This function returns 0 on success or -1 on error.
9950
9951       (Added in 1.0.66)
9952
9953   guestfs_ln_s
9954        int
9955        guestfs_ln_s (guestfs_h *g,
9956                      const char *target,
9957                      const char *linkname);
9958
9959       This command creates a symbolic link using the "ln -s" command.
9960
9961       This function returns 0 on success or -1 on error.
9962
9963       (Added in 1.0.66)
9964
9965   guestfs_ln_sf
9966        int
9967        guestfs_ln_sf (guestfs_h *g,
9968                       const char *target,
9969                       const char *linkname);
9970
9971       This command creates a symbolic link using the "ln -sf" command, The -f
9972       option removes the link ("linkname") if it exists already.
9973
9974       This function returns 0 on success or -1 on error.
9975
9976       (Added in 1.0.66)
9977
9978   guestfs_lremovexattr
9979        int
9980        guestfs_lremovexattr (guestfs_h *g,
9981                              const char *xattr,
9982                              const char *path);
9983
9984       This is the same as "guestfs_removexattr", but if "path" is a symbolic
9985       link, then it removes an extended attribute of the link itself.
9986
9987       This function returns 0 on success or -1 on error.
9988
9989       This function depends on the feature "linuxxattrs".  See also
9990       "guestfs_feature_available".
9991
9992       (Added in 1.0.59)
9993
9994   guestfs_ls
9995        char **
9996        guestfs_ls (guestfs_h *g,
9997                    const char *directory);
9998
9999       List the files in directory (relative to the root directory, there is
10000       no cwd).  The "." and ".." entries are not returned, but hidden files
10001       are shown.
10002
10003       This function returns a NULL-terminated array of strings (like
10004       environ(3)), or NULL if there was an error.  The caller must free the
10005       strings and the array after use.
10006
10007       (Added in 0.4)
10008
10009   guestfs_ls0
10010        int
10011        guestfs_ls0 (guestfs_h *g,
10012                     const char *dir,
10013                     const char *filenames);
10014
10015       This specialized command is used to get a listing of the filenames in
10016       the directory "dir".  The list of filenames is written to the local
10017       file filenames (on the host).
10018
10019       In the output file, the filenames are separated by "\0" characters.
10020
10021       "." and ".." are not returned.  The filenames are not sorted.
10022
10023       This function returns 0 on success or -1 on error.
10024
10025       (Added in 1.19.32)
10026
10027   guestfs_lsetxattr
10028        int
10029        guestfs_lsetxattr (guestfs_h *g,
10030                           const char *xattr,
10031                           const char *val,
10032                           int vallen,
10033                           const char *path);
10034
10035       This is the same as "guestfs_setxattr", but if "path" is a symbolic
10036       link, then it sets an extended attribute of the link itself.
10037
10038       This function returns 0 on success or -1 on error.
10039
10040       This function depends on the feature "linuxxattrs".  See also
10041       "guestfs_feature_available".
10042
10043       (Added in 1.0.59)
10044
10045   guestfs_lstat
10046        struct guestfs_stat *
10047        guestfs_lstat (guestfs_h *g,
10048                       const char *path);
10049
10050       This function is deprecated.  In new code, use the "guestfs_lstatns"
10051       call instead.
10052
10053       Deprecated functions will not be removed from the API, but the fact
10054       that they are deprecated indicates that there are problems with correct
10055       use of these functions.
10056
10057       Returns file information for the given "path".
10058
10059       This is the same as "guestfs_stat" except that if "path" is a symbolic
10060       link, then the link is stat-ed, not the file it refers to.
10061
10062       This is the same as the lstat(2) system call.
10063
10064       This function returns a "struct guestfs_stat *", or NULL if there was
10065       an error.  The caller must call "guestfs_free_stat" after use.
10066
10067       (Added in 1.9.2)
10068
10069   guestfs_lstatlist
10070        struct guestfs_stat_list *
10071        guestfs_lstatlist (guestfs_h *g,
10072                           const char *path,
10073                           char *const *names);
10074
10075       This function is deprecated.  In new code, use the
10076       "guestfs_lstatnslist" call instead.
10077
10078       Deprecated functions will not be removed from the API, but the fact
10079       that they are deprecated indicates that there are problems with correct
10080       use of these functions.
10081
10082       This call allows you to perform the "guestfs_lstat" operation on
10083       multiple files, where all files are in the directory "path".  "names"
10084       is the list of files from this directory.
10085
10086       On return you get a list of stat structs, with a one-to-one
10087       correspondence to the "names" list.  If any name did not exist or could
10088       not be lstat'd, then the "st_ino" field of that structure is set to
10089       "-1".
10090
10091       This call is intended for programs that want to efficiently list a
10092       directory contents without making many round-trips.  See also
10093       "guestfs_lxattrlist" for a similarly efficient call for getting
10094       extended attributes.
10095
10096       This function returns a "struct guestfs_stat_list *", or NULL if there
10097       was an error.  The caller must call "guestfs_free_stat_list" after use.
10098
10099       (Added in 1.0.77)
10100
10101   guestfs_lstatns
10102        struct guestfs_statns *
10103        guestfs_lstatns (guestfs_h *g,
10104                         const char *path);
10105
10106       Returns file information for the given "path".
10107
10108       This is the same as "guestfs_statns" except that if "path" is a
10109       symbolic link, then the link is stat-ed, not the file it refers to.
10110
10111       This is the same as the lstat(2) system call.
10112
10113       This function returns a "struct guestfs_statns *", or NULL if there was
10114       an error.  The caller must call "guestfs_free_statns" after use.
10115
10116       (Added in 1.27.53)
10117
10118   guestfs_lstatnslist
10119        struct guestfs_statns_list *
10120        guestfs_lstatnslist (guestfs_h *g,
10121                             const char *path,
10122                             char *const *names);
10123
10124       This call allows you to perform the "guestfs_lstatns" operation on
10125       multiple files, where all files are in the directory "path".  "names"
10126       is the list of files from this directory.
10127
10128       On return you get a list of stat structs, with a one-to-one
10129       correspondence to the "names" list.  If any name did not exist or could
10130       not be lstat'd, then the "st_ino" field of that structure is set to
10131       "-1".
10132
10133       This call is intended for programs that want to efficiently list a
10134       directory contents without making many round-trips.  See also
10135       "guestfs_lxattrlist" for a similarly efficient call for getting
10136       extended attributes.
10137
10138       This function returns a "struct guestfs_statns_list *", or NULL if
10139       there was an error.  The caller must call "guestfs_free_statns_list"
10140       after use.
10141
10142       (Added in 1.27.53)
10143
10144   guestfs_luks_add_key
10145        int
10146        guestfs_luks_add_key (guestfs_h *g,
10147                              const char *device,
10148                              const char *key,
10149                              const char *newkey,
10150                              int keyslot);
10151
10152       This command adds a new key on LUKS device "device".  "key" is any
10153       existing key, and is used to access the device.  "newkey" is the new
10154       key to add.  "keyslot" is the key slot that will be replaced.
10155
10156       Note that if "keyslot" already contains a key, then this command will
10157       fail.  You have to use "guestfs_luks_kill_slot" first to remove that
10158       key.
10159
10160       This function returns 0 on success or -1 on error.
10161
10162       This function takes a key or passphrase parameter which could contain
10163       sensitive material.  Read the section "KEYS AND PASSPHRASES" for more
10164       information.
10165
10166       This function depends on the feature "luks".  See also
10167       "guestfs_feature_available".
10168
10169       (Added in 1.5.2)
10170
10171   guestfs_luks_close
10172        int
10173        guestfs_luks_close (guestfs_h *g,
10174                            const char *device);
10175
10176       This function is deprecated.  In new code, use the
10177       "guestfs_cryptsetup_close" call instead.
10178
10179       Deprecated functions will not be removed from the API, but the fact
10180       that they are deprecated indicates that there are problems with correct
10181       use of these functions.
10182
10183       This closes a LUKS device that was created earlier by
10184       "guestfs_luks_open" or "guestfs_luks_open_ro".  The "device" parameter
10185       must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10186       and not the name of the underlying block device.
10187
10188       This function returns 0 on success or -1 on error.
10189
10190       This function depends on the feature "luks".  See also
10191       "guestfs_feature_available".
10192
10193       (Added in 1.5.1)
10194
10195   guestfs_luks_format
10196        int
10197        guestfs_luks_format (guestfs_h *g,
10198                             const char *device,
10199                             const char *key,
10200                             int keyslot);
10201
10202       This command erases existing data on "device" and formats the device as
10203       a LUKS encrypted device.  "key" is the initial key, which is added to
10204       key slot "keyslot".  (LUKS supports 8 key slots, numbered 0-7).
10205
10206       This function returns 0 on success or -1 on error.
10207
10208       This function takes a key or passphrase parameter which could contain
10209       sensitive material.  Read the section "KEYS AND PASSPHRASES" for more
10210       information.
10211
10212       This function depends on the feature "luks".  See also
10213       "guestfs_feature_available".
10214
10215       (Added in 1.5.2)
10216
10217   guestfs_luks_format_cipher
10218        int
10219        guestfs_luks_format_cipher (guestfs_h *g,
10220                                    const char *device,
10221                                    const char *key,
10222                                    int keyslot,
10223                                    const char *cipher);
10224
10225       This command is the same as "guestfs_luks_format" but it also allows
10226       you to set the "cipher" used.
10227
10228       This function returns 0 on success or -1 on error.
10229
10230       This function takes a key or passphrase parameter which could contain
10231       sensitive material.  Read the section "KEYS AND PASSPHRASES" for more
10232       information.
10233
10234       This function depends on the feature "luks".  See also
10235       "guestfs_feature_available".
10236
10237       (Added in 1.5.2)
10238
10239   guestfs_luks_kill_slot
10240        int
10241        guestfs_luks_kill_slot (guestfs_h *g,
10242                                const char *device,
10243                                const char *key,
10244                                int keyslot);
10245
10246       This command deletes the key in key slot "keyslot" from the encrypted
10247       LUKS device "device".  "key" must be one of the other keys.
10248
10249       This function returns 0 on success or -1 on error.
10250
10251       This function takes a key or passphrase parameter which could contain
10252       sensitive material.  Read the section "KEYS AND PASSPHRASES" for more
10253       information.
10254
10255       This function depends on the feature "luks".  See also
10256       "guestfs_feature_available".
10257
10258       (Added in 1.5.2)
10259
10260   guestfs_luks_open
10261        int
10262        guestfs_luks_open (guestfs_h *g,
10263                           const char *device,
10264                           const char *key,
10265                           const char *mapname);
10266
10267       This function is deprecated.  In new code, use the
10268       "guestfs_cryptsetup_open" call instead.
10269
10270       Deprecated functions will not be removed from the API, but the fact
10271       that they are deprecated indicates that there are problems with correct
10272       use of these functions.
10273
10274       This command opens a block device which has been encrypted according to
10275       the Linux Unified Key Setup (LUKS) standard.
10276
10277       "device" is the encrypted block device or partition.
10278
10279       The caller must supply one of the keys associated with the LUKS block
10280       device, in the "key" parameter.
10281
10282       This creates a new block device called /dev/mapper/mapname.  Reads and
10283       writes to this block device are decrypted from and encrypted to the
10284       underlying "device" respectively.
10285
10286       If this block device contains LVM volume groups, then calling
10287       "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10288       visible.
10289
10290       Use "guestfs_list_dm_devices" to list all device mapper devices.
10291
10292       This function returns 0 on success or -1 on error.
10293
10294       This function takes a key or passphrase parameter which could contain
10295       sensitive material.  Read the section "KEYS AND PASSPHRASES" for more
10296       information.
10297
10298       This function depends on the feature "luks".  See also
10299       "guestfs_feature_available".
10300
10301       (Added in 1.5.1)
10302
10303   guestfs_luks_open_ro
10304        int
10305        guestfs_luks_open_ro (guestfs_h *g,
10306                              const char *device,
10307                              const char *key,
10308                              const char *mapname);
10309
10310       This function is deprecated.  In new code, use the
10311       "guestfs_cryptsetup_open" call instead.
10312
10313       Deprecated functions will not be removed from the API, but the fact
10314       that they are deprecated indicates that there are problems with correct
10315       use of these functions.
10316
10317       This is the same as "guestfs_luks_open" except that a read-only mapping
10318       is created.
10319
10320       This function returns 0 on success or -1 on error.
10321
10322       This function takes a key or passphrase parameter which could contain
10323       sensitive material.  Read the section "KEYS AND PASSPHRASES" for more
10324       information.
10325
10326       This function depends on the feature "luks".  See also
10327       "guestfs_feature_available".
10328
10329       (Added in 1.5.1)
10330
10331   guestfs_luks_uuid
10332        char *
10333        guestfs_luks_uuid (guestfs_h *g,
10334                           const char *device);
10335
10336       This returns the UUID of the LUKS device "device".
10337
10338       This function returns a string, or NULL on error.  The caller must free
10339       the returned string after use.
10340
10341       This function depends on the feature "luks".  See also
10342       "guestfs_feature_available".
10343
10344       (Added in 1.41.9)
10345
10346   guestfs_lvcreate
10347        int
10348        guestfs_lvcreate (guestfs_h *g,
10349                          const char *logvol,
10350                          const char *volgroup,
10351                          int mbytes);
10352
10353       This creates an LVM logical volume called "logvol" on the volume group
10354       "volgroup", with "size" megabytes.
10355
10356       This function returns 0 on success or -1 on error.
10357
10358       This function depends on the feature "lvm2".  See also
10359       "guestfs_feature_available".
10360
10361       (Added in 0.8)
10362
10363   guestfs_lvcreate_free
10364        int
10365        guestfs_lvcreate_free (guestfs_h *g,
10366                               const char *logvol,
10367                               const char *volgroup,
10368                               int percent);
10369
10370       Create an LVM logical volume called /dev/volgroup/logvol, using
10371       approximately "percent" % of the free space remaining in the volume
10372       group.  Most usefully, when "percent" is 100 this will create the
10373       largest possible LV.
10374
10375       This function returns 0 on success or -1 on error.
10376
10377       This function depends on the feature "lvm2".  See also
10378       "guestfs_feature_available".
10379
10380       (Added in 1.17.18)
10381
10382   guestfs_lvm_canonical_lv_name
10383        char *
10384        guestfs_lvm_canonical_lv_name (guestfs_h *g,
10385                                       const char *lvname);
10386
10387       This converts alternative naming schemes for LVs that you might find to
10388       the canonical name.  For example, /dev/mapper/VG-LV is converted to
10389       /dev/VG/LV.
10390
10391       This command returns an error if the "lvname" parameter does not refer
10392       to a logical volume.  In this case errno will be set to "EINVAL".
10393
10394       See also "guestfs_is_lv", "guestfs_canonical_device_name".
10395
10396       This function returns a string, or NULL on error.  The caller must free
10397       the returned string after use.
10398
10399       (Added in 1.5.24)
10400
10401   guestfs_lvm_clear_filter
10402        int
10403        guestfs_lvm_clear_filter (guestfs_h *g);
10404
10405       This undoes the effect of "guestfs_lvm_set_filter".  LVM will be able
10406       to see every block device.
10407
10408       This command also clears the LVM cache and performs a volume group
10409       scan.
10410
10411       This function returns 0 on success or -1 on error.
10412
10413       (Added in 1.5.1)
10414
10415   guestfs_lvm_remove_all
10416        int
10417        guestfs_lvm_remove_all (guestfs_h *g);
10418
10419       This command removes all LVM logical volumes, volume groups and
10420       physical volumes.
10421
10422       This function returns 0 on success or -1 on error.
10423
10424       This function depends on the feature "lvm2".  See also
10425       "guestfs_feature_available".
10426
10427       (Added in 0.8)
10428
10429   guestfs_lvm_scan
10430        int
10431        guestfs_lvm_scan (guestfs_h *g,
10432                          int activate);
10433
10434       This scans all block devices and rebuilds the list of LVM physical
10435       volumes, volume groups and logical volumes.
10436
10437       If the "activate" parameter is "true" then newly found volume groups
10438       and logical volumes are activated, meaning the LV /dev/VG/LV devices
10439       become visible.
10440
10441       When a libguestfs handle is launched it scans for existing devices, so
10442       you do not normally need to use this API.  However it is useful when
10443       you have added a new device or deleted an existing device (such as when
10444       the "guestfs_luks_open" API is used).
10445
10446       This function returns 0 on success or -1 on error.
10447
10448       (Added in 1.39.8)
10449
10450   guestfs_lvm_set_filter
10451        int
10452        guestfs_lvm_set_filter (guestfs_h *g,
10453                                char *const *devices);
10454
10455       This sets the LVM device filter so that LVM will only be able to "see"
10456       the block devices in the list "devices", and will ignore all other
10457       attached block devices.
10458
10459       Where disk image(s) contain duplicate PVs or VGs, this command is
10460       useful to get LVM to ignore the duplicates, otherwise LVM can get
10461       confused.  Note also there are two types of duplication possible:
10462       either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10463       cloned but just happen to have the same name.  In normal operation you
10464       cannot create this situation, but you can do it outside LVM, eg.  by
10465       cloning disk images or by bit twiddling inside the LVM metadata.
10466
10467       This command also clears the LVM cache and performs a volume group
10468       scan.
10469
10470       You can filter whole block devices or individual partitions.
10471
10472       You cannot use this if any VG is currently in use (eg.  contains a
10473       mounted filesystem), even if you are not filtering out that VG.
10474
10475       This function returns 0 on success or -1 on error.
10476
10477       This function depends on the feature "lvm2".  See also
10478       "guestfs_feature_available".
10479
10480       (Added in 1.5.1)
10481
10482   guestfs_lvremove
10483        int
10484        guestfs_lvremove (guestfs_h *g,
10485                          const char *device);
10486
10487       Remove an LVM logical volume "device", where "device" is the path to
10488       the LV, such as /dev/VG/LV.
10489
10490       You can also remove all LVs in a volume group by specifying the VG
10491       name, /dev/VG.
10492
10493       This function returns 0 on success or -1 on error.
10494
10495       This function depends on the feature "lvm2".  See also
10496       "guestfs_feature_available".
10497
10498       (Added in 1.0.13)
10499
10500   guestfs_lvrename
10501        int
10502        guestfs_lvrename (guestfs_h *g,
10503                          const char *logvol,
10504                          const char *newlogvol);
10505
10506       Rename a logical volume "logvol" with the new name "newlogvol".
10507
10508       This function returns 0 on success or -1 on error.
10509
10510       (Added in 1.0.83)
10511
10512   guestfs_lvresize
10513        int
10514        guestfs_lvresize (guestfs_h *g,
10515                          const char *device,
10516                          int mbytes);
10517
10518       This resizes (expands or shrinks) an existing LVM logical volume to
10519       "mbytes".  When reducing, data in the reduced part is lost.
10520
10521       This function returns 0 on success or -1 on error.
10522
10523       This function depends on the feature "lvm2".  See also
10524       "guestfs_feature_available".
10525
10526       (Added in 1.0.27)
10527
10528   guestfs_lvresize_free
10529        int
10530        guestfs_lvresize_free (guestfs_h *g,
10531                               const char *lv,
10532                               int percent);
10533
10534       This expands an existing logical volume "lv" so that it fills "pc" % of
10535       the remaining free space in the volume group.  Commonly you would call
10536       this with pc = 100 which expands the logical volume as much as
10537       possible, using all remaining free space in the volume group.
10538
10539       This function returns 0 on success or -1 on error.
10540
10541       This function depends on the feature "lvm2".  See also
10542       "guestfs_feature_available".
10543
10544       (Added in 1.3.3)
10545
10546   guestfs_lvs
10547        char **
10548        guestfs_lvs (guestfs_h *g);
10549
10550       List all the logical volumes detected.  This is the equivalent of the
10551       lvs(8) command.
10552
10553       This returns a list of the logical volume device names (eg.
10554       /dev/VolGroup00/LogVol00).
10555
10556       See also "guestfs_lvs_full", "guestfs_list_filesystems".
10557
10558       This function returns a NULL-terminated array of strings (like
10559       environ(3)), or NULL if there was an error.  The caller must free the
10560       strings and the array after use.
10561
10562       This function depends on the feature "lvm2".  See also
10563       "guestfs_feature_available".
10564
10565       (Added in 0.4)
10566
10567   guestfs_lvs_full
10568        struct guestfs_lvm_lv_list *
10569        guestfs_lvs_full (guestfs_h *g);
10570
10571       List all the logical volumes detected.  This is the equivalent of the
10572       lvs(8) command.  The "full" version includes all fields.
10573
10574       This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10575       there was an error.  The caller must call "guestfs_free_lvm_lv_list"
10576       after use.
10577
10578       This function depends on the feature "lvm2".  See also
10579       "guestfs_feature_available".
10580
10581       (Added in 0.4)
10582
10583   guestfs_lvuuid
10584        char *
10585        guestfs_lvuuid (guestfs_h *g,
10586                        const char *device);
10587
10588       This command returns the UUID of the LVM LV "device".
10589
10590       This function returns a string, or NULL on error.  The caller must free
10591       the returned string after use.
10592
10593       (Added in 1.0.87)
10594
10595   guestfs_lxattrlist
10596        struct guestfs_xattr_list *
10597        guestfs_lxattrlist (guestfs_h *g,
10598                            const char *path,
10599                            char *const *names);
10600
10601       This call allows you to get the extended attributes of multiple files,
10602       where all files are in the directory "path".  "names" is the list of
10603       files from this directory.
10604
10605       On return you get a flat list of xattr structs which must be
10606       interpreted sequentially.  The first xattr struct always has a zero-
10607       length "attrname".  "attrval" in this struct is zero-length to indicate
10608       there was an error doing "guestfs_lgetxattr" for this file, or is a C
10609       string which is a decimal number (the number of following attributes
10610       for this file, which could be "0").  Then after the first xattr struct
10611       are the zero or more attributes for the first named file.  This repeats
10612       for the second and subsequent files.
10613
10614       This call is intended for programs that want to efficiently list a
10615       directory contents without making many round-trips.  See also
10616       "guestfs_lstatlist" for a similarly efficient call for getting standard
10617       stats.
10618
10619       This function returns a "struct guestfs_xattr_list *", or NULL if there
10620       was an error.  The caller must call "guestfs_free_xattr_list" after
10621       use.
10622
10623       This function depends on the feature "linuxxattrs".  See also
10624       "guestfs_feature_available".
10625
10626       (Added in 1.0.77)
10627
10628   guestfs_max_disks
10629        int
10630        guestfs_max_disks (guestfs_h *g);
10631
10632       Return the maximum number of disks that may be added to a handle (eg.
10633       by "guestfs_add_drive_opts" and similar calls).
10634
10635       This function was added in libguestfs 1.19.7.  In previous versions of
10636       libguestfs the limit was 25.
10637
10638       See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10639
10640       On error this function returns -1.
10641
10642       (Added in 1.19.7)
10643
10644   guestfs_md_create
10645        int
10646        guestfs_md_create (guestfs_h *g,
10647                           const char *name,
10648                           char *const *devices,
10649                           ...);
10650
10651       You may supply a list of optional arguments to this call.  Use zero or
10652       more of the following pairs of parameters, and terminate the list with
10653       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
10654
10655        GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10656        GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10657        GUESTFS_MD_CREATE_SPARE, int spare,
10658        GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10659        GUESTFS_MD_CREATE_LEVEL, const char *level,
10660
10661       Create a Linux md (RAID) device named "name" on the devices in the list
10662       "devices".
10663
10664       The optional parameters are:
10665
10666       "missingbitmap"
10667           A bitmap of missing devices.  If a bit is set it means that a
10668           missing device is added to the array.  The least significant bit
10669           corresponds to the first device in the array.
10670
10671           As examples:
10672
10673           If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10674           resulting array would be "[<missing>, "/dev/sda"]".
10675
10676           If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10677           resulting array would be "["/dev/sda", <missing>]".
10678
10679           This defaults to 0 (no missing devices).
10680
10681           The length of "devices" + the number of bits set in "missingbitmap"
10682           must equal "nrdevices" + "spare".
10683
10684       "nrdevices"
10685           The number of active RAID devices.
10686
10687           If not set, this defaults to the length of "devices" plus the
10688           number of bits set in "missingbitmap".
10689
10690       "spare"
10691           The number of spare devices.
10692
10693           If not set, this defaults to 0.
10694
10695       "chunk"
10696           The chunk size in bytes.
10697
10698       "level"
10699           The RAID level, which can be one of: "linear", "raid0", 0,
10700           "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
10701           "raid10", 10.  Some of these are synonymous, and more levels may be
10702           added in future.
10703
10704           If not set, this defaults to "raid1".
10705
10706       This function returns 0 on success or -1 on error.
10707
10708       This function depends on the feature "mdadm".  See also
10709       "guestfs_feature_available".
10710
10711       (Added in 1.15.6)
10712
10713   guestfs_md_create_va
10714        int
10715        guestfs_md_create_va (guestfs_h *g,
10716                              const char *name,
10717                              char *const *devices,
10718                              va_list args);
10719
10720       This is the "va_list variant" of "guestfs_md_create".
10721
10722       See "CALLS WITH OPTIONAL ARGUMENTS".
10723
10724   guestfs_md_create_argv
10725        int
10726        guestfs_md_create_argv (guestfs_h *g,
10727                                const char *name,
10728                                char *const *devices,
10729                                const struct guestfs_md_create_argv *optargs);
10730
10731       This is the "argv variant" of "guestfs_md_create".
10732
10733       See "CALLS WITH OPTIONAL ARGUMENTS".
10734
10735   guestfs_md_detail
10736        char **
10737        guestfs_md_detail (guestfs_h *g,
10738                           const char *md);
10739
10740       This command exposes the output of "mdadm -DY <md>".  The following
10741       fields are usually present in the returned hash.  Other fields may also
10742       be present.
10743
10744       "level"
10745           The raid level of the MD device.
10746
10747       "devices"
10748           The number of underlying devices in the MD device.
10749
10750       "metadata"
10751           The metadata version used.
10752
10753       "uuid"
10754           The UUID of the MD device.
10755
10756       "name"
10757           The name of the MD device.
10758
10759       This function returns a NULL-terminated array of strings, or NULL if
10760       there was an error.  The array of strings will always have length
10761       "2n+1", where "n" keys and values alternate, followed by the trailing
10762       NULL entry.  The caller must free the strings and the array after use.
10763
10764       This function depends on the feature "mdadm".  See also
10765       "guestfs_feature_available".
10766
10767       (Added in 1.15.6)
10768
10769   guestfs_md_stat
10770        struct guestfs_mdstat_list *
10771        guestfs_md_stat (guestfs_h *g,
10772                         const char *md);
10773
10774       This call returns a list of the underlying devices which make up the
10775       single software RAID array device "md".
10776
10777       To get a list of software RAID devices, call "guestfs_list_md_devices".
10778
10779       Each structure returned corresponds to one device along with additional
10780       status information:
10781
10782       "mdstat_device"
10783           The name of the underlying device.
10784
10785       "mdstat_index"
10786           The index of this device within the array.
10787
10788       "mdstat_flags"
10789           Flags associated with this device.  This is a string containing (in
10790           no specific order) zero or more of the following flags:
10791
10792           "W" write-mostly
10793
10794           "F" device is faulty
10795
10796           "S" device is a RAID spare
10797
10798           "R" replacement
10799
10800       This function returns a "struct guestfs_mdstat_list *", or NULL if
10801       there was an error.  The caller must call "guestfs_free_mdstat_list"
10802       after use.
10803
10804       This function depends on the feature "mdadm".  See also
10805       "guestfs_feature_available".
10806
10807       (Added in 1.17.21)
10808
10809   guestfs_md_stop
10810        int
10811        guestfs_md_stop (guestfs_h *g,
10812                         const char *md);
10813
10814       This command deactivates the MD array named "md".  The device is
10815       stopped, but it is not destroyed or zeroed.
10816
10817       This function returns 0 on success or -1 on error.
10818
10819       This function depends on the feature "mdadm".  See also
10820       "guestfs_feature_available".
10821
10822       (Added in 1.15.6)
10823
10824   guestfs_mkdir
10825        int
10826        guestfs_mkdir (guestfs_h *g,
10827                       const char *path);
10828
10829       Create a directory named "path".
10830
10831       This function returns 0 on success or -1 on error.
10832
10833       (Added in 0.8)
10834
10835   guestfs_mkdir_mode
10836        int
10837        guestfs_mkdir_mode (guestfs_h *g,
10838                            const char *path,
10839                            int mode);
10840
10841       This command creates a directory, setting the initial permissions of
10842       the directory to "mode".
10843
10844       For common Linux filesystems, the actual mode which is set will be
10845       "mode & ~umask & 01777".  Non-native-Linux filesystems may interpret
10846       the mode in other ways.
10847
10848       See also "guestfs_mkdir", "guestfs_umask"
10849
10850       This function returns 0 on success or -1 on error.
10851
10852       (Added in 1.0.77)
10853
10854   guestfs_mkdir_p
10855        int
10856        guestfs_mkdir_p (guestfs_h *g,
10857                         const char *path);
10858
10859       Create a directory named "path", creating any parent directories as
10860       necessary.  This is like the "mkdir -p" shell command.
10861
10862       This function returns 0 on success or -1 on error.
10863
10864       (Added in 0.8)
10865
10866   guestfs_mkdtemp
10867        char *
10868        guestfs_mkdtemp (guestfs_h *g,
10869                         const char *tmpl);
10870
10871       This command creates a temporary directory.  The "tmpl" parameter
10872       should be a full pathname for the temporary directory name with the
10873       final six characters being "XXXXXX".
10874
10875       For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10876       one being suitable for Windows filesystems.
10877
10878       The name of the temporary directory that was created is returned.
10879
10880       The temporary directory is created with mode 0700 and is owned by root.
10881
10882       The caller is responsible for deleting the temporary directory and its
10883       contents after use.
10884
10885       See also: mkdtemp(3)
10886
10887       This function returns a string, or NULL on error.  The caller must free
10888       the returned string after use.
10889
10890       (Added in 1.0.54)
10891
10892   guestfs_mke2fs
10893        int
10894        guestfs_mke2fs (guestfs_h *g,
10895                        const char *device,
10896                        ...);
10897
10898       You may supply a list of optional arguments to this call.  Use zero or
10899       more of the following pairs of parameters, and terminate the list with
10900       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
10901
10902        GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10903        GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10904        GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10905        GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10906        GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10907        GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10908        GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10909        GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10910        GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10911        GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10912        GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10913        GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10914        GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10915        GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10916        GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10917        GUESTFS_MKE2FS_LABEL, const char *label,
10918        GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10919        GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10920        GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10921        GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10922        GUESTFS_MKE2FS_UUID, const char *uuid,
10923        GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10924        GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10925        GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10926        GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10927        GUESTFS_MKE2FS_TESTFS, int testfs,
10928        GUESTFS_MKE2FS_DISCARD, int discard,
10929        GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10930        GUESTFS_MKE2FS_EXTENT, int extent,
10931        GUESTFS_MKE2FS_FILETYPE, int filetype,
10932        GUESTFS_MKE2FS_FLEXBG, int flexbg,
10933        GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10934        GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10935        GUESTFS_MKE2FS_LARGEFILE, int largefile,
10936        GUESTFS_MKE2FS_QUOTA, int quota,
10937        GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10938        GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10939        GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10940
10941       "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10942       "device".
10943
10944       The optional "blockscount" is the size of the filesystem in blocks.  If
10945       omitted it defaults to the size of "device".  Note if the filesystem is
10946       too small to contain a journal, "mke2fs" will silently create an ext2
10947       filesystem instead.
10948
10949       This function returns 0 on success or -1 on error.
10950
10951       (Added in 1.19.44)
10952
10953   guestfs_mke2fs_va
10954        int
10955        guestfs_mke2fs_va (guestfs_h *g,
10956                           const char *device,
10957                           va_list args);
10958
10959       This is the "va_list variant" of "guestfs_mke2fs".
10960
10961       See "CALLS WITH OPTIONAL ARGUMENTS".
10962
10963   guestfs_mke2fs_argv
10964        int
10965        guestfs_mke2fs_argv (guestfs_h *g,
10966                             const char *device,
10967                             const struct guestfs_mke2fs_argv *optargs);
10968
10969       This is the "argv variant" of "guestfs_mke2fs".
10970
10971       See "CALLS WITH OPTIONAL ARGUMENTS".
10972
10973   guestfs_mke2fs_J
10974        int
10975        guestfs_mke2fs_J (guestfs_h *g,
10976                          const char *fstype,
10977                          int blocksize,
10978                          const char *device,
10979                          const char *journal);
10980
10981       This function is deprecated.  In new code, use the "guestfs_mke2fs"
10982       call instead.
10983
10984       Deprecated functions will not be removed from the API, but the fact
10985       that they are deprecated indicates that there are problems with correct
10986       use of these functions.
10987
10988       This creates an ext2/3/4 filesystem on "device" with an external
10989       journal on "journal".  It is equivalent to the command:
10990
10991        mke2fs -t fstype -b blocksize -J device=<journal> <device>
10992
10993       See also "guestfs_mke2journal".
10994
10995       This function returns 0 on success or -1 on error.
10996
10997       (Added in 1.0.68)
10998
10999   guestfs_mke2fs_JL
11000        int
11001        guestfs_mke2fs_JL (guestfs_h *g,
11002                           const char *fstype,
11003                           int blocksize,
11004                           const char *device,
11005                           const char *label);
11006
11007       This function is deprecated.  In new code, use the "guestfs_mke2fs"
11008       call instead.
11009
11010       Deprecated functions will not be removed from the API, but the fact
11011       that they are deprecated indicates that there are problems with correct
11012       use of these functions.
11013
11014       This creates an ext2/3/4 filesystem on "device" with an external
11015       journal on the journal labeled "label".
11016
11017       See also "guestfs_mke2journal_L".
11018
11019       This function returns 0 on success or -1 on error.
11020
11021       (Added in 1.0.68)
11022
11023   guestfs_mke2fs_JU
11024        int
11025        guestfs_mke2fs_JU (guestfs_h *g,
11026                           const char *fstype,
11027                           int blocksize,
11028                           const char *device,
11029                           const char *uuid);
11030
11031       This function is deprecated.  In new code, use the "guestfs_mke2fs"
11032       call instead.
11033
11034       Deprecated functions will not be removed from the API, but the fact
11035       that they are deprecated indicates that there are problems with correct
11036       use of these functions.
11037
11038       This creates an ext2/3/4 filesystem on "device" with an external
11039       journal on the journal with UUID "uuid".
11040
11041       See also "guestfs_mke2journal_U".
11042
11043       This function returns 0 on success or -1 on error.
11044
11045       This function depends on the feature "linuxfsuuid".  See also
11046       "guestfs_feature_available".
11047
11048       (Added in 1.0.68)
11049
11050   guestfs_mke2journal
11051        int
11052        guestfs_mke2journal (guestfs_h *g,
11053                             int blocksize,
11054                             const char *device);
11055
11056       This function is deprecated.  In new code, use the "guestfs_mke2fs"
11057       call instead.
11058
11059       Deprecated functions will not be removed from the API, but the fact
11060       that they are deprecated indicates that there are problems with correct
11061       use of these functions.
11062
11063       This creates an ext2 external journal on "device".  It is equivalent to
11064       the command:
11065
11066        mke2fs -O journal_dev -b blocksize device
11067
11068       This function returns 0 on success or -1 on error.
11069
11070       (Added in 1.0.68)
11071
11072   guestfs_mke2journal_L
11073        int
11074        guestfs_mke2journal_L (guestfs_h *g,
11075                               int blocksize,
11076                               const char *label,
11077                               const char *device);
11078
11079       This function is deprecated.  In new code, use the "guestfs_mke2fs"
11080       call instead.
11081
11082       Deprecated functions will not be removed from the API, but the fact
11083       that they are deprecated indicates that there are problems with correct
11084       use of these functions.
11085
11086       This creates an ext2 external journal on "device" with label "label".
11087
11088       This function returns 0 on success or -1 on error.
11089
11090       (Added in 1.0.68)
11091
11092   guestfs_mke2journal_U
11093        int
11094        guestfs_mke2journal_U (guestfs_h *g,
11095                               int blocksize,
11096                               const char *uuid,
11097                               const char *device);
11098
11099       This function is deprecated.  In new code, use the "guestfs_mke2fs"
11100       call instead.
11101
11102       Deprecated functions will not be removed from the API, but the fact
11103       that they are deprecated indicates that there are problems with correct
11104       use of these functions.
11105
11106       This creates an ext2 external journal on "device" with UUID "uuid".
11107
11108       This function returns 0 on success or -1 on error.
11109
11110       This function depends on the feature "linuxfsuuid".  See also
11111       "guestfs_feature_available".
11112
11113       (Added in 1.0.68)
11114
11115   guestfs_mkfifo
11116        int
11117        guestfs_mkfifo (guestfs_h *g,
11118                        int mode,
11119                        const char *path);
11120
11121       This call creates a FIFO (named pipe) called "path" with mode "mode".
11122       It is just a convenient wrapper around "guestfs_mknod".
11123
11124       Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11125
11126       The mode actually set is affected by the umask.
11127
11128       This function returns 0 on success or -1 on error.
11129
11130       This function depends on the feature "mknod".  See also
11131       "guestfs_feature_available".
11132
11133       (Added in 1.0.55)
11134
11135   guestfs_mkfs
11136        int
11137        guestfs_mkfs (guestfs_h *g,
11138                      const char *fstype,
11139                      const char *device);
11140
11141       This function is provided for backwards compatibility with earlier
11142       versions of libguestfs.  It simply calls "guestfs_mkfs_opts" with no
11143       optional arguments.
11144
11145       (Added in 0.8)
11146
11147   guestfs_mkfs_opts
11148        int
11149        guestfs_mkfs_opts (guestfs_h *g,
11150                           const char *fstype,
11151                           const char *device,
11152                           ...);
11153
11154       You may supply a list of optional arguments to this call.  Use zero or
11155       more of the following pairs of parameters, and terminate the list with
11156       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
11157
11158        GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
11159        GUESTFS_MKFS_OPTS_FEATURES, const char *features,
11160        GUESTFS_MKFS_OPTS_INODE, int inode,
11161        GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
11162        GUESTFS_MKFS_OPTS_LABEL, const char *label,
11163
11164       This function creates a filesystem on "device".  The filesystem type is
11165       "fstype", for example "ext3".
11166
11167       The optional arguments are:
11168
11169       "blocksize"
11170           The filesystem block size.  Supported block sizes depend on the
11171           filesystem type, but typically they are 1024, 2048 or 4096 for
11172           Linux ext2/3 filesystems.
11173
11174           For VFAT and NTFS the "blocksize" parameter is treated as the
11175           requested cluster size.
11176
11177           For UFS block sizes, please see mkfs.ufs(8).
11178
11179       "features"
11180           This passes the -O parameter to the external mkfs program.
11181
11182           For certain filesystem types, this allows extra filesystem features
11183           to be selected.  See mke2fs(8) and mkfs.ufs(8) for more details.
11184
11185           You cannot use this optional parameter with the "gfs" or "gfs2"
11186           filesystem type.
11187
11188       "inode"
11189           This passes the -I parameter to the external mke2fs(8) program
11190           which sets the inode size (only for ext2/3/4 filesystems at
11191           present).
11192
11193       "sectorsize"
11194           This passes the -S parameter to external mkfs.ufs(8) program, which
11195           sets sector size for ufs filesystem.
11196
11197       This function returns 0 on success or -1 on error.
11198
11199       (Added in 0.8)
11200
11201   guestfs_mkfs_opts_va
11202        int
11203        guestfs_mkfs_opts_va (guestfs_h *g,
11204                              const char *fstype,
11205                              const char *device,
11206                              va_list args);
11207
11208       This is the "va_list variant" of "guestfs_mkfs_opts".
11209
11210       See "CALLS WITH OPTIONAL ARGUMENTS".
11211
11212   guestfs_mkfs_opts_argv
11213        int
11214        guestfs_mkfs_opts_argv (guestfs_h *g,
11215                                const char *fstype,
11216                                const char *device,
11217                                const struct guestfs_mkfs_opts_argv *optargs);
11218
11219       This is the "argv variant" of "guestfs_mkfs_opts".
11220
11221       See "CALLS WITH OPTIONAL ARGUMENTS".
11222
11223   guestfs_mkfs_b
11224        int
11225        guestfs_mkfs_b (guestfs_h *g,
11226                        const char *fstype,
11227                        int blocksize,
11228                        const char *device);
11229
11230       This function is deprecated.  In new code, use the "guestfs_mkfs" call
11231       instead.
11232
11233       Deprecated functions will not be removed from the API, but the fact
11234       that they are deprecated indicates that there are problems with correct
11235       use of these functions.
11236
11237       This call is similar to "guestfs_mkfs", but it allows you to control
11238       the block size of the resulting filesystem.  Supported block sizes
11239       depend on the filesystem type, but typically they are 1024, 2048 or
11240       4096 only.
11241
11242       For VFAT and NTFS the "blocksize" parameter is treated as the requested
11243       cluster size.
11244
11245       This function returns 0 on success or -1 on error.
11246
11247       (Added in 1.0.68)
11248
11249   guestfs_mkfs_btrfs
11250        int
11251        guestfs_mkfs_btrfs (guestfs_h *g,
11252                            char *const *devices,
11253                            ...);
11254
11255       You may supply a list of optional arguments to this call.  Use zero or
11256       more of the following pairs of parameters, and terminate the list with
11257       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
11258
11259        GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11260        GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11261        GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11262        GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11263        GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11264        GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11265        GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11266        GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11267
11268       Create a btrfs filesystem, allowing all configurables to be set.  For
11269       more information on the optional arguments, see mkfs.btrfs(8).
11270
11271       Since btrfs filesystems can span multiple devices, this takes a non-
11272       empty list of devices.
11273
11274       To create general filesystems, use "guestfs_mkfs".
11275
11276       This function returns 0 on success or -1 on error.
11277
11278       This function depends on the feature "btrfs".  See also
11279       "guestfs_feature_available".
11280
11281       (Added in 1.17.25)
11282
11283   guestfs_mkfs_btrfs_va
11284        int
11285        guestfs_mkfs_btrfs_va (guestfs_h *g,
11286                               char *const *devices,
11287                               va_list args);
11288
11289       This is the "va_list variant" of "guestfs_mkfs_btrfs".
11290
11291       See "CALLS WITH OPTIONAL ARGUMENTS".
11292
11293   guestfs_mkfs_btrfs_argv
11294        int
11295        guestfs_mkfs_btrfs_argv (guestfs_h *g,
11296                                 char *const *devices,
11297                                 const struct guestfs_mkfs_btrfs_argv *optargs);
11298
11299       This is the "argv variant" of "guestfs_mkfs_btrfs".
11300
11301       See "CALLS WITH OPTIONAL ARGUMENTS".
11302
11303   guestfs_mklost_and_found
11304        int
11305        guestfs_mklost_and_found (guestfs_h *g,
11306                                  const char *mountpoint);
11307
11308       Make the "lost+found" directory, normally in the root directory of an
11309       ext2/3/4 filesystem.  "mountpoint" is the directory under which we try
11310       to create the "lost+found" directory.
11311
11312       This function returns 0 on success or -1 on error.
11313
11314       (Added in 1.19.56)
11315
11316   guestfs_mkmountpoint
11317        int
11318        guestfs_mkmountpoint (guestfs_h *g,
11319                              const char *exemptpath);
11320
11321       "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11322       that can be used to create extra mountpoints before mounting the first
11323       filesystem.
11324
11325       These calls are only necessary in some very limited circumstances,
11326       mainly the case where you want to mount a mix of unrelated and/or read-
11327       only filesystems together.
11328
11329       For example, live CDs often contain a "Russian doll" nest of
11330       filesystems, an ISO outer layer, with a squashfs image inside, with an
11331       ext2/3 image inside that.  You can unpack this as follows in guestfish:
11332
11333        add-ro Fedora-11-i686-Live.iso
11334        run
11335        mkmountpoint /cd
11336        mkmountpoint /sqsh
11337        mkmountpoint /ext3fs
11338        mount /dev/sda /cd
11339        mount-loop /cd/LiveOS/squashfs.img /sqsh
11340        mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11341
11342       The inner filesystem is now unpacked under the /ext3fs mountpoint.
11343
11344       "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11345       You may get unexpected errors if you try to mix these calls.  It is
11346       safest to manually unmount filesystems and remove mountpoints after
11347       use.
11348
11349       "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11350       first, so for this to work for manual mountpoints, you must ensure that
11351       the innermost mountpoints have the longest pathnames, as in the example
11352       code above.
11353
11354       For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11355
11356       Autosync [see "guestfs_set_autosync", this is set by default on
11357       handles] can cause "guestfs_umount_all" to be called when the handle is
11358       closed which can also trigger these issues.
11359
11360       This function returns 0 on success or -1 on error.
11361
11362       (Added in 1.0.62)
11363
11364   guestfs_mknod
11365        int
11366        guestfs_mknod (guestfs_h *g,
11367                       int mode,
11368                       int devmajor,
11369                       int devminor,
11370                       const char *path);
11371
11372       This call creates block or character special devices, or named pipes
11373       (FIFOs).
11374
11375       The "mode" parameter should be the mode, using the standard constants.
11376       "devmajor" and "devminor" are the device major and minor numbers, only
11377       used when creating block and character special devices.
11378
11379       Note that, just like mknod(2), the mode must be bitwise OR'd with
11380       S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11381       a regular file).  These constants are available in the standard Linux
11382       header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11383       "guestfs_mkfifo" which are wrappers around this command which bitwise
11384       OR in the appropriate constant for you.
11385
11386       The mode actually set is affected by the umask.
11387
11388       This function returns 0 on success or -1 on error.
11389
11390       This function depends on the feature "mknod".  See also
11391       "guestfs_feature_available".
11392
11393       (Added in 1.0.55)
11394
11395   guestfs_mknod_b
11396        int
11397        guestfs_mknod_b (guestfs_h *g,
11398                         int mode,
11399                         int devmajor,
11400                         int devminor,
11401                         const char *path);
11402
11403       This call creates a block device node called "path" with mode "mode"
11404       and device major/minor "devmajor" and "devminor".  It is just a
11405       convenient wrapper around "guestfs_mknod".
11406
11407       Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11408
11409       The mode actually set is affected by the umask.
11410
11411       This function returns 0 on success or -1 on error.
11412
11413       This function depends on the feature "mknod".  See also
11414       "guestfs_feature_available".
11415
11416       (Added in 1.0.55)
11417
11418   guestfs_mknod_c
11419        int
11420        guestfs_mknod_c (guestfs_h *g,
11421                         int mode,
11422                         int devmajor,
11423                         int devminor,
11424                         const char *path);
11425
11426       This call creates a char device node called "path" with mode "mode" and
11427       device major/minor "devmajor" and "devminor".  It is just a convenient
11428       wrapper around "guestfs_mknod".
11429
11430       Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11431
11432       The mode actually set is affected by the umask.
11433
11434       This function returns 0 on success or -1 on error.
11435
11436       This function depends on the feature "mknod".  See also
11437       "guestfs_feature_available".
11438
11439       (Added in 1.0.55)
11440
11441   guestfs_mksquashfs
11442        int
11443        guestfs_mksquashfs (guestfs_h *g,
11444                            const char *path,
11445                            const char *filename,
11446                            ...);
11447
11448       You may supply a list of optional arguments to this call.  Use zero or
11449       more of the following pairs of parameters, and terminate the list with
11450       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
11451
11452        GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11453        GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11454
11455       Create a squashfs filesystem for the specified "path".
11456
11457       The optional "compress" flag controls compression.  If not given, then
11458       the output compressed using "gzip".  Otherwise one of the following
11459       strings may be given to select the compression type of the squashfs:
11460       "gzip", "lzma", "lzo", "lz4", "xz".
11461
11462       The other optional arguments are:
11463
11464       "excludes"
11465           A list of wildcards.  Files are excluded if they match any of the
11466           wildcards.
11467
11468       Please note that this API may fail when used to compress directories
11469       with large files, such as the resulting squashfs will be over 3GB big.
11470
11471       This function returns 0 on success or -1 on error.
11472
11473       This function depends on the feature "squashfs".  See also
11474       "guestfs_feature_available".
11475
11476       (Added in 1.35.25)
11477
11478   guestfs_mksquashfs_va
11479        int
11480        guestfs_mksquashfs_va (guestfs_h *g,
11481                               const char *path,
11482                               const char *filename,
11483                               va_list args);
11484
11485       This is the "va_list variant" of "guestfs_mksquashfs".
11486
11487       See "CALLS WITH OPTIONAL ARGUMENTS".
11488
11489   guestfs_mksquashfs_argv
11490        int
11491        guestfs_mksquashfs_argv (guestfs_h *g,
11492                                 const char *path,
11493                                 const char *filename,
11494                                 const struct guestfs_mksquashfs_argv *optargs);
11495
11496       This is the "argv variant" of "guestfs_mksquashfs".
11497
11498       See "CALLS WITH OPTIONAL ARGUMENTS".
11499
11500   guestfs_mkswap
11501        int
11502        guestfs_mkswap (guestfs_h *g,
11503                        const char *device);
11504
11505       This function is provided for backwards compatibility with earlier
11506       versions of libguestfs.  It simply calls "guestfs_mkswap_opts" with no
11507       optional arguments.
11508
11509       (Added in 1.0.55)
11510
11511   guestfs_mkswap_opts
11512        int
11513        guestfs_mkswap_opts (guestfs_h *g,
11514                             const char *device,
11515                             ...);
11516
11517       You may supply a list of optional arguments to this call.  Use zero or
11518       more of the following pairs of parameters, and terminate the list with
11519       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
11520
11521        GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11522        GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11523
11524       Create a Linux swap partition on "device".
11525
11526       The option arguments "label" and "uuid" allow you to set the label
11527       and/or UUID of the new swap partition.
11528
11529       This function returns 0 on success or -1 on error.
11530
11531       (Added in 1.0.55)
11532
11533   guestfs_mkswap_opts_va
11534        int
11535        guestfs_mkswap_opts_va (guestfs_h *g,
11536                                const char *device,
11537                                va_list args);
11538
11539       This is the "va_list variant" of "guestfs_mkswap_opts".
11540
11541       See "CALLS WITH OPTIONAL ARGUMENTS".
11542
11543   guestfs_mkswap_opts_argv
11544        int
11545        guestfs_mkswap_opts_argv (guestfs_h *g,
11546                                  const char *device,
11547                                  const struct guestfs_mkswap_opts_argv *optargs);
11548
11549       This is the "argv variant" of "guestfs_mkswap_opts".
11550
11551       See "CALLS WITH OPTIONAL ARGUMENTS".
11552
11553   guestfs_mkswap_L
11554        int
11555        guestfs_mkswap_L (guestfs_h *g,
11556                          const char *label,
11557                          const char *device);
11558
11559       This function is deprecated.  In new code, use the "guestfs_mkswap"
11560       call instead.
11561
11562       Deprecated functions will not be removed from the API, but the fact
11563       that they are deprecated indicates that there are problems with correct
11564       use of these functions.
11565
11566       Create a swap partition on "device" with label "label".
11567
11568       Note that you cannot attach a swap label to a block device (eg.
11569       /dev/sda), just to a partition.  This appears to be a limitation of the
11570       kernel or swap tools.
11571
11572       This function returns 0 on success or -1 on error.
11573
11574       (Added in 1.0.55)
11575
11576   guestfs_mkswap_U
11577        int
11578        guestfs_mkswap_U (guestfs_h *g,
11579                          const char *uuid,
11580                          const char *device);
11581
11582       This function is deprecated.  In new code, use the "guestfs_mkswap"
11583       call instead.
11584
11585       Deprecated functions will not be removed from the API, but the fact
11586       that they are deprecated indicates that there are problems with correct
11587       use of these functions.
11588
11589       Create a swap partition on "device" with UUID "uuid".
11590
11591       This function returns 0 on success or -1 on error.
11592
11593       This function depends on the feature "linuxfsuuid".  See also
11594       "guestfs_feature_available".
11595
11596       (Added in 1.0.55)
11597
11598   guestfs_mkswap_file
11599        int
11600        guestfs_mkswap_file (guestfs_h *g,
11601                             const char *path);
11602
11603       Create a swap file.
11604
11605       This command just writes a swap file signature to an existing file.  To
11606       create the file itself, use something like "guestfs_fallocate".
11607
11608       This function returns 0 on success or -1 on error.
11609
11610       (Added in 1.0.66)
11611
11612   guestfs_mktemp
11613        char *
11614        guestfs_mktemp (guestfs_h *g,
11615                        const char *tmpl,
11616                        ...);
11617
11618       You may supply a list of optional arguments to this call.  Use zero or
11619       more of the following pairs of parameters, and terminate the list with
11620       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
11621
11622        GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11623
11624       This command creates a temporary file.  The "tmpl" parameter should be
11625       a full pathname for the temporary directory name with the final six
11626       characters being "XXXXXX".
11627
11628       For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11629       one being suitable for Windows filesystems.
11630
11631       The name of the temporary file that was created is returned.
11632
11633       The temporary file is created with mode 0600 and is owned by root.
11634
11635       The caller is responsible for deleting the temporary file after use.
11636
11637       If the optional "suffix" parameter is given, then the suffix (eg.
11638       ".txt") is appended to the temporary name.
11639
11640       See also: "guestfs_mkdtemp".
11641
11642       This function returns a string, or NULL on error.  The caller must free
11643       the returned string after use.
11644
11645       (Added in 1.19.53)
11646
11647   guestfs_mktemp_va
11648        char *
11649        guestfs_mktemp_va (guestfs_h *g,
11650                           const char *tmpl,
11651                           va_list args);
11652
11653       This is the "va_list variant" of "guestfs_mktemp".
11654
11655       See "CALLS WITH OPTIONAL ARGUMENTS".
11656
11657   guestfs_mktemp_argv
11658        char *
11659        guestfs_mktemp_argv (guestfs_h *g,
11660                             const char *tmpl,
11661                             const struct guestfs_mktemp_argv *optargs);
11662
11663       This is the "argv variant" of "guestfs_mktemp".
11664
11665       See "CALLS WITH OPTIONAL ARGUMENTS".
11666
11667   guestfs_modprobe
11668        int
11669        guestfs_modprobe (guestfs_h *g,
11670                          const char *modulename);
11671
11672       This loads a kernel module in the appliance.
11673
11674       This function returns 0 on success or -1 on error.
11675
11676       This function depends on the feature "linuxmodules".  See also
11677       "guestfs_feature_available".
11678
11679       (Added in 1.0.68)
11680
11681   guestfs_mount
11682        int
11683        guestfs_mount (guestfs_h *g,
11684                       const char *mountable,
11685                       const char *mountpoint);
11686
11687       Mount a guest disk at a position in the filesystem.  Block devices are
11688       named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11689       If those block devices contain partitions, they will have the usual
11690       names (eg. /dev/sda1).  Also LVM /dev/VG/LV-style names can be used, or
11691       ‘mountable’ strings returned by "guestfs_list_filesystems" or
11692       "guestfs_inspect_get_mountpoints".
11693
11694       The rules are the same as for mount(2):  A filesystem must first be
11695       mounted on / before others can be mounted.  Other filesystems can only
11696       be mounted on directories which already exist.
11697
11698       The mounted filesystem is writable, if we have sufficient permissions
11699       on the underlying device.
11700
11701       Before libguestfs 1.13.16, this call implicitly added the options
11702       "sync" and "noatime".  The "sync" option greatly slowed writes and
11703       caused many problems for users.  If your program might need to work
11704       with older versions of libguestfs, use "guestfs_mount_options" instead
11705       (using an empty string for the first parameter if you don't want any
11706       options).
11707
11708       This function returns 0 on success or -1 on error.
11709
11710       (Added in 0.3)
11711
11712   guestfs_mount_9p
11713        int
11714        guestfs_mount_9p (guestfs_h *g,
11715                          const char *mounttag,
11716                          const char *mountpoint,
11717                          ...);
11718
11719       You may supply a list of optional arguments to this call.  Use zero or
11720       more of the following pairs of parameters, and terminate the list with
11721       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
11722
11723        GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11724
11725       Mount the virtio-9p filesystem with the tag "mounttag" on the directory
11726       "mountpoint".
11727
11728       If required, "trans=virtio" will be automatically added to the options.
11729       Any other options required can be passed in the optional "options"
11730       parameter.
11731
11732       This function returns 0 on success or -1 on error.
11733
11734       (Added in 1.11.12)
11735
11736   guestfs_mount_9p_va
11737        int
11738        guestfs_mount_9p_va (guestfs_h *g,
11739                             const char *mounttag,
11740                             const char *mountpoint,
11741                             va_list args);
11742
11743       This is the "va_list variant" of "guestfs_mount_9p".
11744
11745       See "CALLS WITH OPTIONAL ARGUMENTS".
11746
11747   guestfs_mount_9p_argv
11748        int
11749        guestfs_mount_9p_argv (guestfs_h *g,
11750                               const char *mounttag,
11751                               const char *mountpoint,
11752                               const struct guestfs_mount_9p_argv *optargs);
11753
11754       This is the "argv variant" of "guestfs_mount_9p".
11755
11756       See "CALLS WITH OPTIONAL ARGUMENTS".
11757
11758   guestfs_mount_local
11759        int
11760        guestfs_mount_local (guestfs_h *g,
11761                             const char *localmountpoint,
11762                             ...);
11763
11764       You may supply a list of optional arguments to this call.  Use zero or
11765       more of the following pairs of parameters, and terminate the list with
11766       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
11767
11768        GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11769        GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11770        GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11771        GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11772
11773       This call exports the libguestfs-accessible filesystem to a local
11774       mountpoint (directory) called "localmountpoint".  Ordinary reads and
11775       writes to files and directories under "localmountpoint" are redirected
11776       through libguestfs.
11777
11778       If the optional "readonly" flag is set to true, then writes to the
11779       filesystem return error "EROFS".
11780
11781       "options" is a comma-separated list of mount options.  See
11782       guestmount(1) for some useful options.
11783
11784       "cachetimeout" sets the timeout (in seconds) for cached directory
11785       entries.  The default is 60 seconds.  See guestmount(1) for further
11786       information.
11787
11788       If "debugcalls" is set to true, then additional debugging information
11789       is generated for every FUSE call.
11790
11791       When "guestfs_mount_local" returns, the filesystem is ready, but is not
11792       processing requests (access to it will block).  You have to call
11793       "guestfs_mount_local_run" to run the main loop.
11794
11795       See "MOUNT LOCAL" for full documentation.
11796
11797       This function returns 0 on success or -1 on error.
11798
11799       (Added in 1.17.22)
11800
11801   guestfs_mount_local_va
11802        int
11803        guestfs_mount_local_va (guestfs_h *g,
11804                                const char *localmountpoint,
11805                                va_list args);
11806
11807       This is the "va_list variant" of "guestfs_mount_local".
11808
11809       See "CALLS WITH OPTIONAL ARGUMENTS".
11810
11811   guestfs_mount_local_argv
11812        int
11813        guestfs_mount_local_argv (guestfs_h *g,
11814                                  const char *localmountpoint,
11815                                  const struct guestfs_mount_local_argv *optargs);
11816
11817       This is the "argv variant" of "guestfs_mount_local".
11818
11819       See "CALLS WITH OPTIONAL ARGUMENTS".
11820
11821   guestfs_mount_local_run
11822        int
11823        guestfs_mount_local_run (guestfs_h *g);
11824
11825       Run the main loop which translates kernel calls to libguestfs calls.
11826
11827       This should only be called after "guestfs_mount_local" returns
11828       successfully.  The call will not return until the filesystem is
11829       unmounted.
11830
11831       Note you must not make concurrent libguestfs calls on the same handle
11832       from another thread.
11833
11834       You may call this from a different thread than the one which called
11835       "guestfs_mount_local", subject to the usual rules for threads and
11836       libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11837
11838       See "MOUNT LOCAL" for full documentation.
11839
11840       This function returns 0 on success or -1 on error.
11841
11842       (Added in 1.17.22)
11843
11844   guestfs_mount_loop
11845        int
11846        guestfs_mount_loop (guestfs_h *g,
11847                            const char *file,
11848                            const char *mountpoint);
11849
11850       This command lets you mount file (a filesystem image in a file) on a
11851       mount point.  It is entirely equivalent to the command "mount -o loop
11852       file mountpoint".
11853
11854       This function returns 0 on success or -1 on error.
11855
11856       (Added in 1.0.54)
11857
11858   guestfs_mount_options
11859        int
11860        guestfs_mount_options (guestfs_h *g,
11861                               const char *options,
11862                               const char *mountable,
11863                               const char *mountpoint);
11864
11865       This is the same as the "guestfs_mount" command, but it allows you to
11866       set the mount options as for the mount(8) -o flag.
11867
11868       If the "options" parameter is an empty string, then no options are
11869       passed (all options default to whatever the filesystem uses).
11870
11871       This function returns 0 on success or -1 on error.
11872
11873       (Added in 1.0.10)
11874
11875   guestfs_mount_ro
11876        int
11877        guestfs_mount_ro (guestfs_h *g,
11878                          const char *mountable,
11879                          const char *mountpoint);
11880
11881       This is the same as the "guestfs_mount" command, but it mounts the
11882       filesystem with the read-only (-o ro) flag.
11883
11884       This function returns 0 on success or -1 on error.
11885
11886       (Added in 1.0.10)
11887
11888   guestfs_mount_vfs
11889        int
11890        guestfs_mount_vfs (guestfs_h *g,
11891                           const char *options,
11892                           const char *vfstype,
11893                           const char *mountable,
11894                           const char *mountpoint);
11895
11896       This is the same as the "guestfs_mount" command, but it allows you to
11897       set both the mount options and the vfstype as for the mount(8) -o and
11898       -t flags.
11899
11900       This function returns 0 on success or -1 on error.
11901
11902       (Added in 1.0.10)
11903
11904   guestfs_mountable_device
11905        char *
11906        guestfs_mountable_device (guestfs_h *g,
11907                                  const char *mountable);
11908
11909       Returns the device name of a mountable. In quite a lot of cases, the
11910       mountable is the device name.
11911
11912       However this doesn't apply for btrfs subvolumes, where the mountable is
11913       a combination of both the device name and the subvolume path (see also
11914       "guestfs_mountable_subvolume" to extract the subvolume path of the
11915       mountable if any).
11916
11917       This function returns a string, or NULL on error.  The caller must free
11918       the returned string after use.
11919
11920       (Added in 1.33.15)
11921
11922   guestfs_mountable_subvolume
11923        char *
11924        guestfs_mountable_subvolume (guestfs_h *g,
11925                                     const char *mountable);
11926
11927       Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11928       are a combination of both the device name and the subvolume path (see
11929       also "guestfs_mountable_device" to extract the device of the
11930       mountable).
11931
11932       If the mountable does not represent a btrfs subvolume, then this
11933       function fails and the "errno" is set to "EINVAL".
11934
11935       This function returns a string, or NULL on error.  The caller must free
11936       the returned string after use.
11937
11938       (Added in 1.33.15)
11939
11940   guestfs_mountpoints
11941        char **
11942        guestfs_mountpoints (guestfs_h *g);
11943
11944       This call is similar to "guestfs_mounts".  That call returns a list of
11945       devices.  This one returns a hash table (map) of device name to
11946       directory where the device is mounted.
11947
11948       This function returns a NULL-terminated array of strings, or NULL if
11949       there was an error.  The array of strings will always have length
11950       "2n+1", where "n" keys and values alternate, followed by the trailing
11951       NULL entry.  The caller must free the strings and the array after use.
11952
11953       (Added in 1.0.62)
11954
11955   guestfs_mounts
11956        char **
11957        guestfs_mounts (guestfs_h *g);
11958
11959       This returns the list of currently mounted filesystems.  It returns the
11960       list of devices (eg. /dev/sda1, /dev/VG/LV).
11961
11962       Some internal mounts are not shown.
11963
11964       See also: "guestfs_mountpoints"
11965
11966       This function returns a NULL-terminated array of strings (like
11967       environ(3)), or NULL if there was an error.  The caller must free the
11968       strings and the array after use.
11969
11970       (Added in 0.8)
11971
11972   guestfs_mv
11973        int
11974        guestfs_mv (guestfs_h *g,
11975                    const char *src,
11976                    const char *dest);
11977
11978       This moves a file from "src" to "dest" where "dest" is either a
11979       destination filename or destination directory.
11980
11981       See also: "guestfs_rename".
11982
11983       This function returns 0 on success or -1 on error.
11984
11985       (Added in 1.0.18)
11986
11987   guestfs_nr_devices
11988        int
11989        guestfs_nr_devices (guestfs_h *g);
11990
11991       This returns the number of whole block devices that were added.  This
11992       is the same as the number of devices that would be returned if you
11993       called "guestfs_list_devices".
11994
11995       To find out the maximum number of devices that could be added, call
11996       "guestfs_max_disks".
11997
11998       On error this function returns -1.
11999
12000       (Added in 1.19.15)
12001
12002   guestfs_ntfs_3g_probe
12003        int
12004        guestfs_ntfs_3g_probe (guestfs_h *g,
12005                               int rw,
12006                               const char *device);
12007
12008       This command runs the ntfs-3g.probe(8) command which probes an NTFS
12009       "device" for mountability.  (Not all NTFS volumes can be mounted read-
12010       write, and some cannot be mounted at all).
12011
12012       "rw" is a boolean flag.  Set it to true if you want to test if the
12013       volume can be mounted read-write.  Set it to false if you want to test
12014       if the volume can be mounted read-only.
12015
12016       The return value is an integer which 0 if the operation would succeed,
12017       or some non-zero value documented in the ntfs-3g.probe(8) manual page.
12018
12019       On error this function returns -1.
12020
12021       This function depends on the feature "ntfs3g".  See also
12022       "guestfs_feature_available".
12023
12024       (Added in 1.0.43)
12025
12026   guestfs_ntfscat_i
12027        int
12028        guestfs_ntfscat_i (guestfs_h *g,
12029                           const char *device,
12030                           int64_t inode,
12031                           const char *filename);
12032
12033       Download a file given its inode from a NTFS filesystem and save it as
12034       filename on the local machine.
12035
12036       This allows to download some otherwise inaccessible files such as the
12037       ones within the $Extend folder.
12038
12039       The filesystem from which to extract the file must be unmounted,
12040       otherwise the call will fail.
12041
12042       This function returns 0 on success or -1 on error.
12043
12044       This long-running command can generate progress notification messages
12045       so that the caller can display a progress bar or indicator.  To receive
12046       these messages, the caller must register a progress event callback.
12047       See "GUESTFS_EVENT_PROGRESS".
12048
12049       (Added in 1.33.14)
12050
12051   guestfs_ntfsclone_in
12052        int
12053        guestfs_ntfsclone_in (guestfs_h *g,
12054                              const char *backupfile,
12055                              const char *device);
12056
12057       Restore the "backupfile" (from a previous call to
12058       "guestfs_ntfsclone_out") to "device", overwriting any existing contents
12059       of this device.
12060
12061       This function returns 0 on success or -1 on error.
12062
12063       This function depends on the feature "ntfs3g".  See also
12064       "guestfs_feature_available".
12065
12066       (Added in 1.17.9)
12067
12068   guestfs_ntfsclone_out
12069        int
12070        guestfs_ntfsclone_out (guestfs_h *g,
12071                               const char *device,
12072                               const char *backupfile,
12073                               ...);
12074
12075       You may supply a list of optional arguments to this call.  Use zero or
12076       more of the following pairs of parameters, and terminate the list with
12077       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
12078
12079        GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
12080        GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
12081        GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
12082        GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
12083        GUESTFS_NTFSCLONE_OUT_FORCE, int force,
12084
12085       Stream the NTFS filesystem "device" to the local file "backupfile".
12086       The format used for the backup file is a special format used by the
12087       ntfsclone(8) tool.
12088
12089       If the optional "metadataonly" flag is true, then only the metadata is
12090       saved, losing all the user data (this is useful for diagnosing some
12091       filesystem problems).
12092
12093       The optional "rescue", "ignorefscheck", "preservetimestamps" and
12094       "force" flags have precise meanings detailed in the ntfsclone(8) man
12095       page.
12096
12097       Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
12098       device.
12099
12100       This function returns 0 on success or -1 on error.
12101
12102       This function depends on the feature "ntfs3g".  See also
12103       "guestfs_feature_available".
12104
12105       (Added in 1.17.9)
12106
12107   guestfs_ntfsclone_out_va
12108        int
12109        guestfs_ntfsclone_out_va (guestfs_h *g,
12110                                  const char *device,
12111                                  const char *backupfile,
12112                                  va_list args);
12113
12114       This is the "va_list variant" of "guestfs_ntfsclone_out".
12115
12116       See "CALLS WITH OPTIONAL ARGUMENTS".
12117
12118   guestfs_ntfsclone_out_argv
12119        int
12120        guestfs_ntfsclone_out_argv (guestfs_h *g,
12121                                    const char *device,
12122                                    const char *backupfile,
12123                                    const struct guestfs_ntfsclone_out_argv *optargs);
12124
12125       This is the "argv variant" of "guestfs_ntfsclone_out".
12126
12127       See "CALLS WITH OPTIONAL ARGUMENTS".
12128
12129   guestfs_ntfsfix
12130        int
12131        guestfs_ntfsfix (guestfs_h *g,
12132                         const char *device,
12133                         ...);
12134
12135       You may supply a list of optional arguments to this call.  Use zero or
12136       more of the following pairs of parameters, and terminate the list with
12137       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
12138
12139        GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
12140
12141       This command repairs some fundamental NTFS inconsistencies, resets the
12142       NTFS journal file, and schedules an NTFS consistency check for the
12143       first boot into Windows.
12144
12145       This is not an equivalent of Windows "chkdsk".  It does not scan the
12146       filesystem for inconsistencies.
12147
12148       The optional "clearbadsectors" flag clears the list of bad sectors.
12149       This is useful after cloning a disk with bad sectors to a new disk.
12150
12151       This function returns 0 on success or -1 on error.
12152
12153       This function depends on the feature "ntfs3g".  See also
12154       "guestfs_feature_available".
12155
12156       (Added in 1.17.9)
12157
12158   guestfs_ntfsfix_va
12159        int
12160        guestfs_ntfsfix_va (guestfs_h *g,
12161                            const char *device,
12162                            va_list args);
12163
12164       This is the "va_list variant" of "guestfs_ntfsfix".
12165
12166       See "CALLS WITH OPTIONAL ARGUMENTS".
12167
12168   guestfs_ntfsfix_argv
12169        int
12170        guestfs_ntfsfix_argv (guestfs_h *g,
12171                              const char *device,
12172                              const struct guestfs_ntfsfix_argv *optargs);
12173
12174       This is the "argv variant" of "guestfs_ntfsfix".
12175
12176       See "CALLS WITH OPTIONAL ARGUMENTS".
12177
12178   guestfs_ntfsresize
12179        int
12180        guestfs_ntfsresize (guestfs_h *g,
12181                            const char *device);
12182
12183       This function is provided for backwards compatibility with earlier
12184       versions of libguestfs.  It simply calls "guestfs_ntfsresize_opts" with
12185       no optional arguments.
12186
12187       (Added in 1.3.2)
12188
12189   guestfs_ntfsresize_opts
12190        int
12191        guestfs_ntfsresize_opts (guestfs_h *g,
12192                                 const char *device,
12193                                 ...);
12194
12195       You may supply a list of optional arguments to this call.  Use zero or
12196       more of the following pairs of parameters, and terminate the list with
12197       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
12198
12199        GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12200        GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12201
12202       This command resizes an NTFS filesystem, expanding or shrinking it to
12203       the size of the underlying device.
12204
12205       The optional parameters are:
12206
12207       "size"
12208           The new size (in bytes) of the filesystem.  If omitted, the
12209           filesystem is resized to fit the container (eg. partition).
12210
12211       "force"
12212           If this option is true, then force the resize of the filesystem
12213           even if the filesystem is marked as requiring a consistency check.
12214
12215           After the resize operation, the filesystem is always marked as
12216           requiring a consistency check (for safety).  You have to boot into
12217           Windows to perform this check and clear this condition.  If you
12218           don't set the "force" option then it is not possible to call
12219           "guestfs_ntfsresize" multiple times on a single filesystem without
12220           booting into Windows between each resize.
12221
12222       See also ntfsresize(8).
12223
12224       This function returns 0 on success or -1 on error.
12225
12226       This function depends on the feature "ntfsprogs".  See also
12227       "guestfs_feature_available".
12228
12229       (Added in 1.3.2)
12230
12231   guestfs_ntfsresize_opts_va
12232        int
12233        guestfs_ntfsresize_opts_va (guestfs_h *g,
12234                                    const char *device,
12235                                    va_list args);
12236
12237       This is the "va_list variant" of "guestfs_ntfsresize_opts".
12238
12239       See "CALLS WITH OPTIONAL ARGUMENTS".
12240
12241   guestfs_ntfsresize_opts_argv
12242        int
12243        guestfs_ntfsresize_opts_argv (guestfs_h *g,
12244                                      const char *device,
12245                                      const struct guestfs_ntfsresize_opts_argv *optargs);
12246
12247       This is the "argv variant" of "guestfs_ntfsresize_opts".
12248
12249       See "CALLS WITH OPTIONAL ARGUMENTS".
12250
12251   guestfs_ntfsresize_size
12252        int
12253        guestfs_ntfsresize_size (guestfs_h *g,
12254                                 const char *device,
12255                                 int64_t size);
12256
12257       This function is deprecated.  In new code, use the "guestfs_ntfsresize"
12258       call instead.
12259
12260       Deprecated functions will not be removed from the API, but the fact
12261       that they are deprecated indicates that there are problems with correct
12262       use of these functions.
12263
12264       This command is the same as "guestfs_ntfsresize" except that it allows
12265       you to specify the new size (in bytes) explicitly.
12266
12267       This function returns 0 on success or -1 on error.
12268
12269       This function depends on the feature "ntfsprogs".  See also
12270       "guestfs_feature_available".
12271
12272       (Added in 1.3.14)
12273
12274   guestfs_parse_environment
12275        int
12276        guestfs_parse_environment (guestfs_h *g);
12277
12278       Parse the program’s environment and set flags in the handle
12279       accordingly.  For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12280       flag is set in the handle.
12281
12282       Most programs do not need to call this.  It is done implicitly when you
12283       call "guestfs_create".
12284
12285       See "ENVIRONMENT VARIABLES" for a list of environment variables that
12286       can affect libguestfs handles.  See also "guestfs_create_flags", and
12287       "guestfs_parse_environment_list".
12288
12289       This function returns 0 on success or -1 on error.
12290
12291       (Added in 1.19.53)
12292
12293   guestfs_parse_environment_list
12294        int
12295        guestfs_parse_environment_list (guestfs_h *g,
12296                                        char *const *environment);
12297
12298       Parse the list of strings in the argument "environment" and set flags
12299       in the handle accordingly.  For example if "LIBGUESTFS_DEBUG=1" is a
12300       string in the list, then the ‘verbose’ flag is set in the handle.
12301
12302       This is the same as "guestfs_parse_environment" except that it parses
12303       an explicit list of strings instead of the program's environment.
12304
12305       This function returns 0 on success or -1 on error.
12306
12307       (Added in 1.19.53)
12308
12309   guestfs_part_add
12310        int
12311        guestfs_part_add (guestfs_h *g,
12312                          const char *device,
12313                          const char *prlogex,
12314                          int64_t startsect,
12315                          int64_t endsect);
12316
12317       This command adds a partition to "device".  If there is no partition
12318       table on the device, call "guestfs_part_init" first.
12319
12320       The "prlogex" parameter is the type of partition.  Normally you should
12321       pass "p" or "primary" here, but MBR partition tables also support "l"
12322       (or "logical") and "e" (or "extended") partition types.
12323
12324       "startsect" and "endsect" are the start and end of the partition in
12325       sectors.  "endsect" may be negative, which means it counts backwards
12326       from the end of the disk ("-1" is the last sector).
12327
12328       Creating a partition which covers the whole disk is not so easy.  Use
12329       "guestfs_part_disk" to do that.
12330
12331       This function returns 0 on success or -1 on error.
12332
12333       (Added in 1.0.78)
12334
12335   guestfs_part_del
12336        int
12337        guestfs_part_del (guestfs_h *g,
12338                          const char *device,
12339                          int partnum);
12340
12341       This command deletes the partition numbered "partnum" on "device".
12342
12343       Note that in the case of MBR partitioning, deleting an extended
12344       partition also deletes any logical partitions it contains.
12345
12346       This function returns 0 on success or -1 on error.
12347
12348       (Added in 1.3.2)
12349
12350   guestfs_part_disk
12351        int
12352        guestfs_part_disk (guestfs_h *g,
12353                           const char *device,
12354                           const char *parttype);
12355
12356       This command is simply a combination of "guestfs_part_init" followed by
12357       "guestfs_part_add" to create a single primary partition covering the
12358       whole disk.
12359
12360       "parttype" is the partition table type, usually "mbr" or "gpt", but
12361       other possible values are described in "guestfs_part_init".
12362
12363       This function returns 0 on success or -1 on error.
12364
12365       (Added in 1.0.78)
12366
12367   guestfs_part_expand_gpt
12368        int
12369        guestfs_part_expand_gpt (guestfs_h *g,
12370                                 const char *device);
12371
12372       Move backup GPT data structures to the end of the disk.  This is useful
12373       in case of in-place image expand since disk space after backup GPT
12374       header is not usable.  This is equivalent to "sgdisk -e".
12375
12376       See also sgdisk(8).
12377
12378       This function returns 0 on success or -1 on error.
12379
12380       This function depends on the feature "gdisk".  See also
12381       "guestfs_feature_available".
12382
12383       (Added in 1.33.2)
12384
12385   guestfs_part_get_bootable
12386        int
12387        guestfs_part_get_bootable (guestfs_h *g,
12388                                   const char *device,
12389                                   int partnum);
12390
12391       This command returns true if the partition "partnum" on "device" has
12392       the bootable flag set.
12393
12394       See also "guestfs_part_set_bootable".
12395
12396       This function returns a C truth value on success or -1 on error.
12397
12398       (Added in 1.3.2)
12399
12400   guestfs_part_get_disk_guid
12401        char *
12402        guestfs_part_get_disk_guid (guestfs_h *g,
12403                                    const char *device);
12404
12405       Return the disk identifier (GUID) of a GPT-partitioned "device".
12406       Behaviour is undefined for other partition types.
12407
12408       This function returns a string, or NULL on error.  The caller must free
12409       the returned string after use.
12410
12411       This function depends on the feature "gdisk".  See also
12412       "guestfs_feature_available".
12413
12414       (Added in 1.33.2)
12415
12416   guestfs_part_get_gpt_attributes
12417        int64_t
12418        guestfs_part_get_gpt_attributes (guestfs_h *g,
12419                                         const char *device,
12420                                         int partnum);
12421
12422       Return the attribute flags of numbered GPT partition "partnum".  An
12423       error is returned for MBR partitions.
12424
12425       On error this function returns -1.
12426
12427       This function depends on the feature "gdisk".  See also
12428       "guestfs_feature_available".
12429
12430       (Added in 1.21.1)
12431
12432   guestfs_part_get_gpt_guid
12433        char *
12434        guestfs_part_get_gpt_guid (guestfs_h *g,
12435                                   const char *device,
12436                                   int partnum);
12437
12438       Return the GUID of numbered GPT partition "partnum".
12439
12440       This function returns a string, or NULL on error.  The caller must free
12441       the returned string after use.
12442
12443       This function depends on the feature "gdisk".  See also
12444       "guestfs_feature_available".
12445
12446       (Added in 1.29.25)
12447
12448   guestfs_part_get_gpt_type
12449        char *
12450        guestfs_part_get_gpt_type (guestfs_h *g,
12451                                   const char *device,
12452                                   int partnum);
12453
12454       Return the type GUID of numbered GPT partition "partnum". For MBR
12455       partitions, return an appropriate GUID corresponding to the MBR type.
12456       Behaviour is undefined for other partition types.
12457
12458       This function returns a string, or NULL on error.  The caller must free
12459       the returned string after use.
12460
12461       This function depends on the feature "gdisk".  See also
12462       "guestfs_feature_available".
12463
12464       (Added in 1.21.1)
12465
12466   guestfs_part_get_mbr_id
12467        int
12468        guestfs_part_get_mbr_id (guestfs_h *g,
12469                                 const char *device,
12470                                 int partnum);
12471
12472       Returns the MBR type byte (also known as the ID byte) from the numbered
12473       partition "partnum".
12474
12475       Note that only MBR (old DOS-style) partitions have type bytes.  You
12476       will get undefined results for other partition table types (see
12477       "guestfs_part_get_parttype").
12478
12479       On error this function returns -1.
12480
12481       (Added in 1.3.2)
12482
12483   guestfs_part_get_mbr_part_type
12484        char *
12485        guestfs_part_get_mbr_part_type (guestfs_h *g,
12486                                        const char *device,
12487                                        int partnum);
12488
12489       This returns the partition type of an MBR partition numbered "partnum"
12490       on device "device".
12491
12492       It returns "primary", "logical", or "extended".
12493
12494       This function returns a string, or NULL on error.  The caller must free
12495       the returned string after use.
12496
12497       (Added in 1.29.32)
12498
12499   guestfs_part_get_name
12500        char *
12501        guestfs_part_get_name (guestfs_h *g,
12502                               const char *device,
12503                               int partnum);
12504
12505       This gets the partition name on partition numbered "partnum" on device
12506       "device".  Note that partitions are numbered from 1.
12507
12508       The partition name can only be read on certain types of partition
12509       table.  This works on "gpt" but not on "mbr" partitions.
12510
12511       This function returns a string, or NULL on error.  The caller must free
12512       the returned string after use.
12513
12514       (Added in 1.25.33)
12515
12516   guestfs_part_get_parttype
12517        char *
12518        guestfs_part_get_parttype (guestfs_h *g,
12519                                   const char *device);
12520
12521       This command examines the partition table on "device" and returns the
12522       partition table type (format) being used.
12523
12524       Common return values include: "msdos" (a DOS/Windows style MBR
12525       partition table), "gpt" (a GPT/EFI-style partition table).  Other
12526       values are possible, although unusual.  See "guestfs_part_init" for a
12527       full list.
12528
12529       This function returns a string, or NULL on error.  The caller must free
12530       the returned string after use.
12531
12532       (Added in 1.0.78)
12533
12534   guestfs_part_init
12535        int
12536        guestfs_part_init (guestfs_h *g,
12537                           const char *device,
12538                           const char *parttype);
12539
12540       This creates an empty partition table on "device" of one of the
12541       partition types listed below.  Usually "parttype" should be either
12542       "msdos" or "gpt" (for large disks).
12543
12544       Initially there are no partitions.  Following this, you should call
12545       "guestfs_part_add" for each partition required.
12546
12547       Possible values for "parttype" are:
12548
12549       "efi"
12550       "gpt"
12551           Intel EFI / GPT partition table.
12552
12553           This is recommended for >= 2 TB partitions that will be accessed
12554           from Linux and Intel-based Mac OS X.  It also has limited backwards
12555           compatibility with the "mbr" format.
12556
12557       "mbr"
12558       "msdos"
12559           The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12560           and Windows.  This partition type will only work for device sizes
12561           up to 2 TB.  For large disks we recommend using "gpt".
12562
12563       Other partition table types that may work but are not supported
12564       include:
12565
12566       "aix"
12567           AIX disk labels.
12568
12569       "amiga"
12570       "rdb"
12571           Amiga "Rigid Disk Block" format.
12572
12573       "bsd"
12574           BSD disk labels.
12575
12576       "dasd"
12577           DASD, used on IBM mainframes.
12578
12579       "dvh"
12580           MIPS/SGI volumes.
12581
12582       "mac"
12583           Old Mac partition format.  Modern Macs use "gpt".
12584
12585       "pc98"
12586           NEC PC-98 format, common in Japan apparently.
12587
12588       "sun"
12589           Sun disk labels.
12590
12591       This function returns 0 on success or -1 on error.
12592
12593       (Added in 1.0.78)
12594
12595   guestfs_part_list
12596        struct guestfs_partition_list *
12597        guestfs_part_list (guestfs_h *g,
12598                           const char *device);
12599
12600       This command parses the partition table on "device" and returns the
12601       list of partitions found.
12602
12603       The fields in the returned structure are:
12604
12605       "part_num"
12606           Partition number, counting from 1.
12607
12608       "part_start"
12609           Start of the partition in bytes.  To get sectors you have to divide
12610           by the device’s sector size, see "guestfs_blockdev_getss".
12611
12612       "part_end"
12613           End of the partition in bytes.
12614
12615       "part_size"
12616           Size of the partition in bytes.
12617
12618       This function returns a "struct guestfs_partition_list *", or NULL if
12619       there was an error.  The caller must call "guestfs_free_partition_list"
12620       after use.
12621
12622       (Added in 1.0.78)
12623
12624   guestfs_part_resize
12625        int
12626        guestfs_part_resize (guestfs_h *g,
12627                             const char *device,
12628                             int partnum,
12629                             int64_t endsect);
12630
12631       This command resizes the partition numbered "partnum" on "device" by
12632       moving the end position.
12633
12634       Note that this does not modify any filesystem present in the partition.
12635       If you wish to do this, you will need to use filesystem resizing
12636       commands like "guestfs_resize2fs".
12637
12638       When growing a partition you will want to grow the filesystem
12639       afterwards, but when shrinking, you need to shrink the filesystem
12640       before the partition.
12641
12642       This function returns 0 on success or -1 on error.
12643
12644       (Added in 1.37.20)
12645
12646   guestfs_part_set_bootable
12647        int
12648        guestfs_part_set_bootable (guestfs_h *g,
12649                                   const char *device,
12650                                   int partnum,
12651                                   int bootable);
12652
12653       This sets the bootable flag on partition numbered "partnum" on device
12654       "device".  Note that partitions are numbered from 1.
12655
12656       The bootable flag is used by some operating systems (notably Windows)
12657       to determine which partition to boot from.  It is by no means
12658       universally recognized.
12659
12660       This function returns 0 on success or -1 on error.
12661
12662       (Added in 1.0.78)
12663
12664   guestfs_part_set_disk_guid
12665        int
12666        guestfs_part_set_disk_guid (guestfs_h *g,
12667                                    const char *device,
12668                                    const char *guid);
12669
12670       Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12671       Return an error if the partition table of "device" isn't GPT, or if
12672       "guid" is not a valid GUID.
12673
12674       This function returns 0 on success or -1 on error.
12675
12676       This function depends on the feature "gdisk".  See also
12677       "guestfs_feature_available".
12678
12679       (Added in 1.33.2)
12680
12681   guestfs_part_set_disk_guid_random
12682        int
12683        guestfs_part_set_disk_guid_random (guestfs_h *g,
12684                                           const char *device);
12685
12686       Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12687       randomly generated value.  Return an error if the partition table of
12688       "device" isn't GPT.
12689
12690       This function returns 0 on success or -1 on error.
12691
12692       This function depends on the feature "gdisk".  See also
12693       "guestfs_feature_available".
12694
12695       (Added in 1.33.2)
12696
12697   guestfs_part_set_gpt_attributes
12698        int
12699        guestfs_part_set_gpt_attributes (guestfs_h *g,
12700                                         const char *device,
12701                                         int partnum,
12702                                         int64_t attributes);
12703
12704       Set the attribute flags of numbered GPT partition "partnum" to
12705       "attributes". Return an error if the partition table of "device" isn't
12706       GPT.
12707
12708       See
12709       https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12710       for a useful list of partition attributes.
12711
12712       This function returns 0 on success or -1 on error.
12713
12714       This function depends on the feature "gdisk".  See also
12715       "guestfs_feature_available".
12716
12717       (Added in 1.21.1)
12718
12719   guestfs_part_set_gpt_guid
12720        int
12721        guestfs_part_set_gpt_guid (guestfs_h *g,
12722                                   const char *device,
12723                                   int partnum,
12724                                   const char *guid);
12725
12726       Set the GUID of numbered GPT partition "partnum" to "guid".  Return an
12727       error if the partition table of "device" isn't GPT, or if "guid" is not
12728       a valid GUID.
12729
12730       This function returns 0 on success or -1 on error.
12731
12732       This function depends on the feature "gdisk".  See also
12733       "guestfs_feature_available".
12734
12735       (Added in 1.29.25)
12736
12737   guestfs_part_set_gpt_type
12738        int
12739        guestfs_part_set_gpt_type (guestfs_h *g,
12740                                   const char *device,
12741                                   int partnum,
12742                                   const char *guid);
12743
12744       Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12745       an error if the partition table of "device" isn't GPT, or if "guid" is
12746       not a valid GUID.
12747
12748       See
12749       https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12750       for a useful list of type GUIDs.
12751
12752       This function returns 0 on success or -1 on error.
12753
12754       This function depends on the feature "gdisk".  See also
12755       "guestfs_feature_available".
12756
12757       (Added in 1.21.1)
12758
12759   guestfs_part_set_mbr_id
12760        int
12761        guestfs_part_set_mbr_id (guestfs_h *g,
12762                                 const char *device,
12763                                 int partnum,
12764                                 int idbyte);
12765
12766       Sets the MBR type byte (also known as the ID byte) of the numbered
12767       partition "partnum" to "idbyte".  Note that the type bytes quoted in
12768       most documentation are in fact hexadecimal numbers, but usually
12769       documented without any leading "0x" which might be confusing.
12770
12771       Note that only MBR (old DOS-style) partitions have type bytes.  You
12772       will get undefined results for other partition table types (see
12773       "guestfs_part_get_parttype").
12774
12775       This function returns 0 on success or -1 on error.
12776
12777       (Added in 1.3.2)
12778
12779   guestfs_part_set_name
12780        int
12781        guestfs_part_set_name (guestfs_h *g,
12782                               const char *device,
12783                               int partnum,
12784                               const char *name);
12785
12786       This sets the partition name on partition numbered "partnum" on device
12787       "device".  Note that partitions are numbered from 1.
12788
12789       The partition name can only be set on certain types of partition table.
12790       This works on "gpt" but not on "mbr" partitions.
12791
12792       This function returns 0 on success or -1 on error.
12793
12794       (Added in 1.0.78)
12795
12796   guestfs_part_to_dev
12797        char *
12798        guestfs_part_to_dev (guestfs_h *g,
12799                             const char *partition);
12800
12801       This function takes a partition name (eg. "/dev/sdb1") and removes the
12802       partition number, returning the device name (eg. "/dev/sdb").
12803
12804       The named partition must exist, for example as a string returned from
12805       "guestfs_list_partitions".
12806
12807       See also "guestfs_part_to_partnum", "guestfs_device_index".
12808
12809       This function returns a string, or NULL on error.  The caller must free
12810       the returned string after use.
12811
12812       (Added in 1.5.15)
12813
12814   guestfs_part_to_partnum
12815        int
12816        guestfs_part_to_partnum (guestfs_h *g,
12817                                 const char *partition);
12818
12819       This function takes a partition name (eg. "/dev/sdb1") and returns the
12820       partition number (eg. 1).
12821
12822       The named partition must exist, for example as a string returned from
12823       "guestfs_list_partitions".
12824
12825       See also "guestfs_part_to_dev".
12826
12827       On error this function returns -1.
12828
12829       (Added in 1.13.25)
12830
12831   guestfs_ping_daemon
12832        int
12833        guestfs_ping_daemon (guestfs_h *g);
12834
12835       This is a test probe into the guestfs daemon running inside the
12836       libguestfs appliance.  Calling this function checks that the daemon
12837       responds to the ping message, without affecting the daemon or attached
12838       block device(s) in any other way.
12839
12840       This function returns 0 on success or -1 on error.
12841
12842       (Added in 1.0.18)
12843
12844   guestfs_pread
12845        char *
12846        guestfs_pread (guestfs_h *g,
12847                       const char *path,
12848                       int count,
12849                       int64_t offset,
12850                       size_t *size_r);
12851
12852       This command lets you read part of a file.  It reads "count" bytes of
12853       the file, starting at "offset", from file "path".
12854
12855       This may read fewer bytes than requested.  For further details see the
12856       pread(2) system call.
12857
12858       See also "guestfs_pwrite", "guestfs_pread_device".
12859
12860       This function returns a buffer, or NULL on error.  The size of the
12861       returned buffer is written to *size_r.  The caller must free the
12862       returned buffer after use.
12863
12864       Because of the message protocol, there is a transfer limit of somewhere
12865       between 2MB and 4MB.  See "PROTOCOL LIMITS".
12866
12867       (Added in 1.0.77)
12868
12869   guestfs_pread_device
12870        char *
12871        guestfs_pread_device (guestfs_h *g,
12872                              const char *device,
12873                              int count,
12874                              int64_t offset,
12875                              size_t *size_r);
12876
12877       This command lets you read part of a block device.  It reads "count"
12878       bytes of "device", starting at "offset".
12879
12880       This may read fewer bytes than requested.  For further details see the
12881       pread(2) system call.
12882
12883       See also "guestfs_pread".
12884
12885       This function returns a buffer, or NULL on error.  The size of the
12886       returned buffer is written to *size_r.  The caller must free the
12887       returned buffer after use.
12888
12889       Because of the message protocol, there is a transfer limit of somewhere
12890       between 2MB and 4MB.  See "PROTOCOL LIMITS".
12891
12892       (Added in 1.5.21)
12893
12894   guestfs_pvchange_uuid
12895        int
12896        guestfs_pvchange_uuid (guestfs_h *g,
12897                               const char *device);
12898
12899       Generate a new random UUID for the physical volume "device".
12900
12901       This function returns 0 on success or -1 on error.
12902
12903       This function depends on the feature "lvm2".  See also
12904       "guestfs_feature_available".
12905
12906       (Added in 1.19.26)
12907
12908   guestfs_pvchange_uuid_all
12909        int
12910        guestfs_pvchange_uuid_all (guestfs_h *g);
12911
12912       Generate new random UUIDs for all physical volumes.
12913
12914       This function returns 0 on success or -1 on error.
12915
12916       This function depends on the feature "lvm2".  See also
12917       "guestfs_feature_available".
12918
12919       (Added in 1.19.26)
12920
12921   guestfs_pvcreate
12922        int
12923        guestfs_pvcreate (guestfs_h *g,
12924                          const char *device);
12925
12926       This creates an LVM physical volume on the named "device", where
12927       "device" should usually be a partition name such as /dev/sda1.
12928
12929       This function returns 0 on success or -1 on error.
12930
12931       This function depends on the feature "lvm2".  See also
12932       "guestfs_feature_available".
12933
12934       (Added in 0.8)
12935
12936   guestfs_pvremove
12937        int
12938        guestfs_pvremove (guestfs_h *g,
12939                          const char *device);
12940
12941       This wipes a physical volume "device" so that LVM will no longer
12942       recognise it.
12943
12944       The implementation uses the pvremove(8) command which refuses to wipe
12945       physical volumes that contain any volume groups, so you have to remove
12946       those first.
12947
12948       This function returns 0 on success or -1 on error.
12949
12950       This function depends on the feature "lvm2".  See also
12951       "guestfs_feature_available".
12952
12953       (Added in 1.0.13)
12954
12955   guestfs_pvresize
12956        int
12957        guestfs_pvresize (guestfs_h *g,
12958                          const char *device);
12959
12960       This resizes (expands or shrinks) an existing LVM physical volume to
12961       match the new size of the underlying device.
12962
12963       This function returns 0 on success or -1 on error.
12964
12965       This function depends on the feature "lvm2".  See also
12966       "guestfs_feature_available".
12967
12968       (Added in 1.0.26)
12969
12970   guestfs_pvresize_size
12971        int
12972        guestfs_pvresize_size (guestfs_h *g,
12973                               const char *device,
12974                               int64_t size);
12975
12976       This command is the same as "guestfs_pvresize" except that it allows
12977       you to specify the new size (in bytes) explicitly.
12978
12979       This function returns 0 on success or -1 on error.
12980
12981       This function depends on the feature "lvm2".  See also
12982       "guestfs_feature_available".
12983
12984       (Added in 1.3.14)
12985
12986   guestfs_pvs
12987        char **
12988        guestfs_pvs (guestfs_h *g);
12989
12990       List all the physical volumes detected.  This is the equivalent of the
12991       pvs(8) command.
12992
12993       This returns a list of just the device names that contain PVs (eg.
12994       /dev/sda2).
12995
12996       See also "guestfs_pvs_full".
12997
12998       This function returns a NULL-terminated array of strings (like
12999       environ(3)), or NULL if there was an error.  The caller must free the
13000       strings and the array after use.
13001
13002       This function depends on the feature "lvm2".  See also
13003       "guestfs_feature_available".
13004
13005       (Added in 0.4)
13006
13007   guestfs_pvs_full
13008        struct guestfs_lvm_pv_list *
13009        guestfs_pvs_full (guestfs_h *g);
13010
13011       List all the physical volumes detected.  This is the equivalent of the
13012       pvs(8) command.  The "full" version includes all fields.
13013
13014       This function returns a "struct guestfs_lvm_pv_list *", or NULL if
13015       there was an error.  The caller must call "guestfs_free_lvm_pv_list"
13016       after use.
13017
13018       This function depends on the feature "lvm2".  See also
13019       "guestfs_feature_available".
13020
13021       (Added in 0.4)
13022
13023   guestfs_pvuuid
13024        char *
13025        guestfs_pvuuid (guestfs_h *g,
13026                        const char *device);
13027
13028       This command returns the UUID of the LVM PV "device".
13029
13030       This function returns a string, or NULL on error.  The caller must free
13031       the returned string after use.
13032
13033       (Added in 1.0.87)
13034
13035   guestfs_pwrite
13036        int
13037        guestfs_pwrite (guestfs_h *g,
13038                        const char *path,
13039                        const char *content,
13040                        size_t content_size,
13041                        int64_t offset);
13042
13043       This command writes to part of a file.  It writes the data buffer
13044       "content" to the file "path" starting at offset "offset".
13045
13046       This command implements the pwrite(2) system call, and like that system
13047       call it may not write the full data requested.  The return value is the
13048       number of bytes that were actually written to the file.  This could
13049       even be 0, although short writes are unlikely for regular files in
13050       ordinary circumstances.
13051
13052       See also "guestfs_pread", "guestfs_pwrite_device".
13053
13054       On error this function returns -1.
13055
13056       Because of the message protocol, there is a transfer limit of somewhere
13057       between 2MB and 4MB.  See "PROTOCOL LIMITS".
13058
13059       (Added in 1.3.14)
13060
13061   guestfs_pwrite_device
13062        int
13063        guestfs_pwrite_device (guestfs_h *g,
13064                               const char *device,
13065                               const char *content,
13066                               size_t content_size,
13067                               int64_t offset);
13068
13069       This command writes to part of a device.  It writes the data buffer
13070       "content" to "device" starting at offset "offset".
13071
13072       This command implements the pwrite(2) system call, and like that system
13073       call it may not write the full data requested (although short writes to
13074       disk devices and partitions are probably impossible with standard Linux
13075       kernels).
13076
13077       See also "guestfs_pwrite".
13078
13079       On error this function returns -1.
13080
13081       Because of the message protocol, there is a transfer limit of somewhere
13082       between 2MB and 4MB.  See "PROTOCOL LIMITS".
13083
13084       (Added in 1.5.20)
13085
13086   guestfs_read_file
13087        char *
13088        guestfs_read_file (guestfs_h *g,
13089                           const char *path,
13090                           size_t *size_r);
13091
13092       This calls returns the contents of the file "path" as a buffer.
13093
13094       Unlike "guestfs_cat", this function can correctly handle files that
13095       contain embedded ASCII NUL characters.
13096
13097       This function returns a buffer, or NULL on error.  The size of the
13098       returned buffer is written to *size_r.  The caller must free the
13099       returned buffer after use.
13100
13101       (Added in 1.0.63)
13102
13103   guestfs_read_lines
13104        char **
13105        guestfs_read_lines (guestfs_h *g,
13106                            const char *path);
13107
13108       Return the contents of the file named "path".
13109
13110       The file contents are returned as a list of lines.  Trailing "LF" and
13111       "CRLF" character sequences are not returned.
13112
13113       Note that this function cannot correctly handle binary files
13114       (specifically, files containing "\0" character which is treated as end
13115       of string).  For those you need to use the "guestfs_read_file" function
13116       and split the buffer into lines yourself.
13117
13118       This function returns a NULL-terminated array of strings (like
13119       environ(3)), or NULL if there was an error.  The caller must free the
13120       strings and the array after use.
13121
13122       (Added in 0.7)
13123
13124   guestfs_readdir
13125        struct guestfs_dirent_list *
13126        guestfs_readdir (guestfs_h *g,
13127                         const char *dir);
13128
13129       This returns the list of directory entries in directory "dir".
13130
13131       All entries in the directory are returned, including "." and "..".  The
13132       entries are not sorted, but returned in the same order as the
13133       underlying filesystem.
13134
13135       Also this call returns basic file type information about each file.
13136       The "ftyp" field will contain one of the following characters:
13137
13138       'b' Block special
13139
13140       'c' Char special
13141
13142       'd' Directory
13143
13144       'f' FIFO (named pipe)
13145
13146       'l' Symbolic link
13147
13148       'r' Regular file
13149
13150       's' Socket
13151
13152       'u' Unknown file type
13153
13154       '?' The readdir(3) call returned a "d_type" field with an unexpected
13155           value
13156
13157       This function is primarily intended for use by programs.  To get a
13158       simple list of names, use "guestfs_ls".  To get a printable directory
13159       for human consumption, use "guestfs_ll".
13160
13161       This function returns a "struct guestfs_dirent_list *", or NULL if
13162       there was an error.  The caller must call "guestfs_free_dirent_list"
13163       after use.
13164
13165       Because of the message protocol, there is a transfer limit of somewhere
13166       between 2MB and 4MB.  See "PROTOCOL LIMITS".
13167
13168       (Added in 1.0.55)
13169
13170   guestfs_readlink
13171        char *
13172        guestfs_readlink (guestfs_h *g,
13173                          const char *path);
13174
13175       This command reads the target of a symbolic link.
13176
13177       This function returns a string, or NULL on error.  The caller must free
13178       the returned string after use.
13179
13180       (Added in 1.0.66)
13181
13182   guestfs_readlinklist
13183        char **
13184        guestfs_readlinklist (guestfs_h *g,
13185                              const char *path,
13186                              char *const *names);
13187
13188       This call allows you to do a "readlink" operation on multiple files,
13189       where all files are in the directory "path".  "names" is the list of
13190       files from this directory.
13191
13192       On return you get a list of strings, with a one-to-one correspondence
13193       to the "names" list.  Each string is the value of the symbolic link.
13194
13195       If the readlink(2) operation fails on any name, then the corresponding
13196       result string is the empty string "".  However the whole operation is
13197       completed even if there were readlink(2) errors, and so you can call
13198       this function with names where you don't know if they are symbolic
13199       links already (albeit slightly less efficient).
13200
13201       This call is intended for programs that want to efficiently list a
13202       directory contents without making many round-trips.
13203
13204       This function returns a NULL-terminated array of strings (like
13205       environ(3)), or NULL if there was an error.  The caller must free the
13206       strings and the array after use.
13207
13208       (Added in 1.0.77)
13209
13210   guestfs_realpath
13211        char *
13212        guestfs_realpath (guestfs_h *g,
13213                          const char *path);
13214
13215       Return the canonicalized absolute pathname of "path".  The returned
13216       path has no ".", ".." or symbolic link path elements.
13217
13218       This function returns a string, or NULL on error.  The caller must free
13219       the returned string after use.
13220
13221       (Added in 1.0.66)
13222
13223   guestfs_remount
13224        int
13225        guestfs_remount (guestfs_h *g,
13226                         const char *mountpoint,
13227                         ...);
13228
13229       You may supply a list of optional arguments to this call.  Use zero or
13230       more of the following pairs of parameters, and terminate the list with
13231       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
13232
13233        GUESTFS_REMOUNT_RW, int rw,
13234
13235       This call allows you to change the "rw" (readonly/read-write) flag on
13236       an already mounted filesystem at "mountpoint", converting a readonly
13237       filesystem to be read-write, or vice-versa.
13238
13239       Note that at the moment you must supply the "optional" "rw" parameter.
13240       In future we may allow other flags to be adjusted.
13241
13242       This function returns 0 on success or -1 on error.
13243
13244       (Added in 1.23.2)
13245
13246   guestfs_remount_va
13247        int
13248        guestfs_remount_va (guestfs_h *g,
13249                            const char *mountpoint,
13250                            va_list args);
13251
13252       This is the "va_list variant" of "guestfs_remount".
13253
13254       See "CALLS WITH OPTIONAL ARGUMENTS".
13255
13256   guestfs_remount_argv
13257        int
13258        guestfs_remount_argv (guestfs_h *g,
13259                              const char *mountpoint,
13260                              const struct guestfs_remount_argv *optargs);
13261
13262       This is the "argv variant" of "guestfs_remount".
13263
13264       See "CALLS WITH OPTIONAL ARGUMENTS".
13265
13266   guestfs_remove_drive
13267        int
13268        guestfs_remove_drive (guestfs_h *g,
13269                              const char *label);
13270
13271       This function is conceptually the opposite of "guestfs_add_drive_opts".
13272       It removes the drive that was previously added with label "label".
13273
13274       Note that in order to remove drives, you have to add them with labels
13275       (see the optional "label" argument to "guestfs_add_drive_opts").  If
13276       you didn't use a label, then they cannot be removed.
13277
13278       You can call this function before or after launching the handle.  If
13279       called after launch, if the backend supports it, we try to hot unplug
13280       the drive: see "HOTPLUGGING".  The disk must not be in use (eg.
13281       mounted) when you do this.  We try to detect if the disk is in use and
13282       stop you from doing this.
13283
13284       This function returns 0 on success or -1 on error.
13285
13286       (Added in 1.19.49)
13287
13288   guestfs_removexattr
13289        int
13290        guestfs_removexattr (guestfs_h *g,
13291                             const char *xattr,
13292                             const char *path);
13293
13294       This call removes the extended attribute named "xattr" of the file
13295       "path".
13296
13297       See also: "guestfs_lremovexattr", attr(5).
13298
13299       This function returns 0 on success or -1 on error.
13300
13301       This function depends on the feature "linuxxattrs".  See also
13302       "guestfs_feature_available".
13303
13304       (Added in 1.0.59)
13305
13306   guestfs_rename
13307        int
13308        guestfs_rename (guestfs_h *g,
13309                        const char *oldpath,
13310                        const char *newpath);
13311
13312       Rename a file to a new place on the same filesystem.  This is the same
13313       as the Linux rename(2) system call.  In most cases you are better to
13314       use "guestfs_mv" instead.
13315
13316       This function returns 0 on success or -1 on error.
13317
13318       (Added in 1.21.5)
13319
13320   guestfs_resize2fs
13321        int
13322        guestfs_resize2fs (guestfs_h *g,
13323                           const char *device);
13324
13325       This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13326       underlying device.
13327
13328       See also "RESIZE2FS ERRORS".
13329
13330       This function returns 0 on success or -1 on error.
13331
13332       (Added in 1.0.27)
13333
13334   guestfs_resize2fs_M
13335        int
13336        guestfs_resize2fs_M (guestfs_h *g,
13337                             const char *device);
13338
13339       This command is the same as "guestfs_resize2fs", but the filesystem is
13340       resized to its minimum size.  This works like the -M option to the
13341       resize2fs(8) command.
13342
13343       To get the resulting size of the filesystem you should call
13344       "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13345       These two numbers, multiplied together, give the resulting size of the
13346       minimal filesystem in bytes.
13347
13348       See also "RESIZE2FS ERRORS".
13349
13350       This function returns 0 on success or -1 on error.
13351
13352       (Added in 1.9.4)
13353
13354   guestfs_resize2fs_size
13355        int
13356        guestfs_resize2fs_size (guestfs_h *g,
13357                                const char *device,
13358                                int64_t size);
13359
13360       This command is the same as "guestfs_resize2fs" except that it allows
13361       you to specify the new size (in bytes) explicitly.
13362
13363       See also "RESIZE2FS ERRORS".
13364
13365       This function returns 0 on success or -1 on error.
13366
13367       (Added in 1.3.14)
13368
13369   guestfs_rm
13370        int
13371        guestfs_rm (guestfs_h *g,
13372                    const char *path);
13373
13374       Remove the single file "path".
13375
13376       This function returns 0 on success or -1 on error.
13377
13378       (Added in 0.8)
13379
13380   guestfs_rm_f
13381        int
13382        guestfs_rm_f (guestfs_h *g,
13383                      const char *path);
13384
13385       Remove the file "path".
13386
13387       If the file doesn't exist, that error is ignored.  (Other errors, eg.
13388       I/O errors or bad paths, are not ignored)
13389
13390       This call cannot remove directories.  Use "guestfs_rmdir" to remove an
13391       empty directory, or "guestfs_rm_rf" to remove directories recursively.
13392
13393       This function returns 0 on success or -1 on error.
13394
13395       (Added in 1.19.42)
13396
13397   guestfs_rm_rf
13398        int
13399        guestfs_rm_rf (guestfs_h *g,
13400                       const char *path);
13401
13402       Remove the file or directory "path", recursively removing the contents
13403       if its a directory.  This is like the "rm -rf" shell command.
13404
13405       This function returns 0 on success or -1 on error.
13406
13407       (Added in 0.8)
13408
13409   guestfs_rmdir
13410        int
13411        guestfs_rmdir (guestfs_h *g,
13412                       const char *path);
13413
13414       Remove the single directory "path".
13415
13416       This function returns 0 on success or -1 on error.
13417
13418       (Added in 0.8)
13419
13420   guestfs_rmmountpoint
13421        int
13422        guestfs_rmmountpoint (guestfs_h *g,
13423                              const char *exemptpath);
13424
13425       This call removes a mountpoint that was previously created with
13426       "guestfs_mkmountpoint".  See "guestfs_mkmountpoint" for full details.
13427
13428       This function returns 0 on success or -1 on error.
13429
13430       (Added in 1.0.62)
13431
13432   guestfs_rsync
13433        int
13434        guestfs_rsync (guestfs_h *g,
13435                       const char *src,
13436                       const char *dest,
13437                       ...);
13438
13439       You may supply a list of optional arguments to this call.  Use zero or
13440       more of the following pairs of parameters, and terminate the list with
13441       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
13442
13443        GUESTFS_RSYNC_ARCHIVE, int archive,
13444        GUESTFS_RSYNC_DELETEDEST, int deletedest,
13445
13446       This call may be used to copy or synchronize two directories under the
13447       same libguestfs handle.  This uses the rsync(1) program which uses a
13448       fast algorithm that avoids copying files unnecessarily.
13449
13450       "src" and "dest" are the source and destination directories.  Files are
13451       copied from "src" to "dest".
13452
13453       The optional arguments are:
13454
13455       "archive"
13456           Turns on archive mode.  This is the same as passing the --archive
13457           flag to "rsync".
13458
13459       "deletedest"
13460           Delete files at the destination that do not exist at the source.
13461
13462       This function returns 0 on success or -1 on error.
13463
13464       This function depends on the feature "rsync".  See also
13465       "guestfs_feature_available".
13466
13467       (Added in 1.19.29)
13468
13469   guestfs_rsync_va
13470        int
13471        guestfs_rsync_va (guestfs_h *g,
13472                          const char *src,
13473                          const char *dest,
13474                          va_list args);
13475
13476       This is the "va_list variant" of "guestfs_rsync".
13477
13478       See "CALLS WITH OPTIONAL ARGUMENTS".
13479
13480   guestfs_rsync_argv
13481        int
13482        guestfs_rsync_argv (guestfs_h *g,
13483                            const char *src,
13484                            const char *dest,
13485                            const struct guestfs_rsync_argv *optargs);
13486
13487       This is the "argv variant" of "guestfs_rsync".
13488
13489       See "CALLS WITH OPTIONAL ARGUMENTS".
13490
13491   guestfs_rsync_in
13492        int
13493        guestfs_rsync_in (guestfs_h *g,
13494                          const char *remote,
13495                          const char *dest,
13496                          ...);
13497
13498       You may supply a list of optional arguments to this call.  Use zero or
13499       more of the following pairs of parameters, and terminate the list with
13500       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
13501
13502        GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13503        GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13504
13505       This call may be used to copy or synchronize the filesystem on the host
13506       or on a remote computer with the filesystem within libguestfs.  This
13507       uses the rsync(1) program which uses a fast algorithm that avoids
13508       copying files unnecessarily.
13509
13510       This call only works if the network is enabled.  See
13511       "guestfs_set_network" or the --network option to various tools like
13512       guestfish(1).
13513
13514       Files are copied from the remote server and directory specified by
13515       "remote" to the destination directory "dest".
13516
13517       The format of the remote server string is defined by rsync(1).  Note
13518       that there is no way to supply a password or passphrase so the target
13519       must be set up not to require one.
13520
13521       The optional arguments are the same as those of "guestfs_rsync".
13522
13523       This function returns 0 on success or -1 on error.
13524
13525       This function depends on the feature "rsync".  See also
13526       "guestfs_feature_available".
13527
13528       (Added in 1.19.29)
13529
13530   guestfs_rsync_in_va
13531        int
13532        guestfs_rsync_in_va (guestfs_h *g,
13533                             const char *remote,
13534                             const char *dest,
13535                             va_list args);
13536
13537       This is the "va_list variant" of "guestfs_rsync_in".
13538
13539       See "CALLS WITH OPTIONAL ARGUMENTS".
13540
13541   guestfs_rsync_in_argv
13542        int
13543        guestfs_rsync_in_argv (guestfs_h *g,
13544                               const char *remote,
13545                               const char *dest,
13546                               const struct guestfs_rsync_in_argv *optargs);
13547
13548       This is the "argv variant" of "guestfs_rsync_in".
13549
13550       See "CALLS WITH OPTIONAL ARGUMENTS".
13551
13552   guestfs_rsync_out
13553        int
13554        guestfs_rsync_out (guestfs_h *g,
13555                           const char *src,
13556                           const char *remote,
13557                           ...);
13558
13559       You may supply a list of optional arguments to this call.  Use zero or
13560       more of the following pairs of parameters, and terminate the list with
13561       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
13562
13563        GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13564        GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13565
13566       This call may be used to copy or synchronize the filesystem within
13567       libguestfs with a filesystem on the host or on a remote computer.  This
13568       uses the rsync(1) program which uses a fast algorithm that avoids
13569       copying files unnecessarily.
13570
13571       This call only works if the network is enabled.  See
13572       "guestfs_set_network" or the --network option to various tools like
13573       guestfish(1).
13574
13575       Files are copied from the source directory "src" to the remote server
13576       and directory specified by "remote".
13577
13578       The format of the remote server string is defined by rsync(1).  Note
13579       that there is no way to supply a password or passphrase so the target
13580       must be set up not to require one.
13581
13582       The optional arguments are the same as those of "guestfs_rsync".
13583
13584       Globbing does not happen on the "src" parameter.  In programs which use
13585       the API directly you have to expand wildcards yourself (see
13586       "guestfs_glob_expand").  In guestfish you can use the "glob" command
13587       (see "glob" in guestfish(1)), for example:
13588
13589        ><fs> glob rsync-out /* rsync://remote/
13590
13591       This function returns 0 on success or -1 on error.
13592
13593       This function depends on the feature "rsync".  See also
13594       "guestfs_feature_available".
13595
13596       (Added in 1.19.29)
13597
13598   guestfs_rsync_out_va
13599        int
13600        guestfs_rsync_out_va (guestfs_h *g,
13601                              const char *src,
13602                              const char *remote,
13603                              va_list args);
13604
13605       This is the "va_list variant" of "guestfs_rsync_out".
13606
13607       See "CALLS WITH OPTIONAL ARGUMENTS".
13608
13609   guestfs_rsync_out_argv
13610        int
13611        guestfs_rsync_out_argv (guestfs_h *g,
13612                                const char *src,
13613                                const char *remote,
13614                                const struct guestfs_rsync_out_argv *optargs);
13615
13616       This is the "argv variant" of "guestfs_rsync_out".
13617
13618       See "CALLS WITH OPTIONAL ARGUMENTS".
13619
13620   guestfs_scrub_device
13621        int
13622        guestfs_scrub_device (guestfs_h *g,
13623                              const char *device);
13624
13625       This command writes patterns over "device" to make data retrieval more
13626       difficult.
13627
13628       It is an interface to the scrub(1) program.  See that manual page for
13629       more details.
13630
13631       This function returns 0 on success or -1 on error.
13632
13633       This function depends on the feature "scrub".  See also
13634       "guestfs_feature_available".
13635
13636       (Added in 1.0.52)
13637
13638   guestfs_scrub_file
13639        int
13640        guestfs_scrub_file (guestfs_h *g,
13641                            const char *file);
13642
13643       This command writes patterns over a file to make data retrieval more
13644       difficult.
13645
13646       The file is removed after scrubbing.
13647
13648       It is an interface to the scrub(1) program.  See that manual page for
13649       more details.
13650
13651       This function returns 0 on success or -1 on error.
13652
13653       This function depends on the feature "scrub".  See also
13654       "guestfs_feature_available".
13655
13656       (Added in 1.0.52)
13657
13658   guestfs_scrub_freespace
13659        int
13660        guestfs_scrub_freespace (guestfs_h *g,
13661                                 const char *dir);
13662
13663       This command creates the directory "dir" and then fills it with files
13664       until the filesystem is full, and scrubs the files as for
13665       "guestfs_scrub_file", and deletes them.  The intention is to scrub any
13666       free space on the partition containing "dir".
13667
13668       It is an interface to the scrub(1) program.  See that manual page for
13669       more details.
13670
13671       This function returns 0 on success or -1 on error.
13672
13673       This function depends on the feature "scrub".  See also
13674       "guestfs_feature_available".
13675
13676       (Added in 1.0.52)
13677
13678   guestfs_selinux_relabel
13679        int
13680        guestfs_selinux_relabel (guestfs_h *g,
13681                                 const char *specfile,
13682                                 const char *path,
13683                                 ...);
13684
13685       You may supply a list of optional arguments to this call.  Use zero or
13686       more of the following pairs of parameters, and terminate the list with
13687       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
13688
13689        GUESTFS_SELINUX_RELABEL_FORCE, int force,
13690
13691       SELinux relabel parts of the filesystem.
13692
13693       The "specfile" parameter controls the policy spec file used.  You have
13694       to parse "/etc/selinux/config" to find the correct SELinux policy and
13695       then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13696       "/contexts/files/file_contexts".
13697
13698       The required "path" parameter is the top level directory where
13699       relabelling starts.  Normally you should pass "path" as "/" to relabel
13700       the whole guest filesystem.
13701
13702       The optional "force" boolean controls whether the context is reset for
13703       customizable files, and also whether the user, role and range parts of
13704       the file context is changed.
13705
13706       This function returns 0 on success or -1 on error.
13707
13708       This function depends on the feature "selinuxrelabel".  See also
13709       "guestfs_feature_available".
13710
13711       (Added in 1.33.43)
13712
13713   guestfs_selinux_relabel_va
13714        int
13715        guestfs_selinux_relabel_va (guestfs_h *g,
13716                                    const char *specfile,
13717                                    const char *path,
13718                                    va_list args);
13719
13720       This is the "va_list variant" of "guestfs_selinux_relabel".
13721
13722       See "CALLS WITH OPTIONAL ARGUMENTS".
13723
13724   guestfs_selinux_relabel_argv
13725        int
13726        guestfs_selinux_relabel_argv (guestfs_h *g,
13727                                      const char *specfile,
13728                                      const char *path,
13729                                      const struct guestfs_selinux_relabel_argv *optargs);
13730
13731       This is the "argv variant" of "guestfs_selinux_relabel".
13732
13733       See "CALLS WITH OPTIONAL ARGUMENTS".
13734
13735   guestfs_set_append
13736        int
13737        guestfs_set_append (guestfs_h *g,
13738                            const char *append);
13739
13740       This function is used to add additional options to the libguestfs
13741       appliance kernel command line.
13742
13743       The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13744       environment variable.
13745
13746       Setting "append" to "NULL" means no additional options are passed
13747       (libguestfs always adds a few of its own).
13748
13749       This function returns 0 on success or -1 on error.
13750
13751       (Added in 1.0.26)
13752
13753   guestfs_set_attach_method
13754        int
13755        guestfs_set_attach_method (guestfs_h *g,
13756                                   const char *backend);
13757
13758       This function is deprecated.  In new code, use the
13759       "guestfs_set_backend" call instead.
13760
13761       Deprecated functions will not be removed from the API, but the fact
13762       that they are deprecated indicates that there are problems with correct
13763       use of these functions.
13764
13765       Set the method that libguestfs uses to connect to the backend guestfsd
13766       daemon.
13767
13768       See "BACKEND".
13769
13770       This function returns 0 on success or -1 on error.
13771
13772       (Added in 1.9.8)
13773
13774   guestfs_set_autosync
13775        int
13776        guestfs_set_autosync (guestfs_h *g,
13777                              int autosync);
13778
13779       If "autosync" is true, this enables autosync.  Libguestfs will make a
13780       best effort attempt to make filesystems consistent and synchronized
13781       when the handle is closed (also if the program exits without closing
13782       handles).
13783
13784       This is enabled by default (since libguestfs 1.5.24, previously it was
13785       disabled by default).
13786
13787       This function returns 0 on success or -1 on error.
13788
13789       (Added in 0.3)
13790
13791   guestfs_set_backend
13792        int
13793        guestfs_set_backend (guestfs_h *g,
13794                             const char *backend);
13795
13796       Set the method that libguestfs uses to connect to the backend guestfsd
13797       daemon.
13798
13799       This handle property was previously called the "attach method".
13800
13801       See "BACKEND".
13802
13803       This function returns 0 on success or -1 on error.
13804
13805       (Added in 1.21.26)
13806
13807   guestfs_set_backend_setting
13808        int
13809        guestfs_set_backend_setting (guestfs_h *g,
13810                                     const char *name,
13811                                     const char *val);
13812
13813       Append "name=value" to the backend settings string list.  However if a
13814       string already exists matching "name" or beginning with "name=", then
13815       that setting is replaced.
13816
13817       See "BACKEND", "BACKEND SETTINGS".
13818
13819       This function returns 0 on success or -1 on error.
13820
13821       (Added in 1.27.2)
13822
13823   guestfs_set_backend_settings
13824        int
13825        guestfs_set_backend_settings (guestfs_h *g,
13826                                      char *const *settings);
13827
13828       Set a list of zero or more settings which are passed through to the
13829       current backend.  Each setting is a string which is interpreted in a
13830       backend-specific way, or ignored if not understood by the backend.
13831
13832       The default value is an empty list, unless the environment variable
13833       "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13834       This environment variable contains a colon-separated list of settings.
13835
13836       This call replaces all backend settings.  If you want to replace a
13837       single backend setting, see "guestfs_set_backend_setting".  If you want
13838       to clear a single backend setting, see "guestfs_clear_backend_setting".
13839
13840       See "BACKEND", "BACKEND SETTINGS".
13841
13842       This function returns 0 on success or -1 on error.
13843
13844       (Added in 1.25.24)
13845
13846   guestfs_set_cachedir
13847        int
13848        guestfs_set_cachedir (guestfs_h *g,
13849                              const char *cachedir);
13850
13851       Set the directory used by the handle to store the appliance cache, when
13852       using a supermin appliance.  The appliance is cached and shared between
13853       all handles which have the same effective user ID.
13854
13855       The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13856       the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13857       default.  Else if "TMPDIR" is set, then that is the default.  Else
13858       /var/tmp is the default.
13859
13860       This function returns 0 on success or -1 on error.
13861
13862       (Added in 1.19.58)
13863
13864   guestfs_set_direct
13865        int
13866        guestfs_set_direct (guestfs_h *g,
13867                            int direct);
13868
13869       This function is deprecated.  In new code, use the
13870       "guestfs_internal_get_console_socket" call instead.
13871
13872       Deprecated functions will not be removed from the API, but the fact
13873       that they are deprecated indicates that there are problems with correct
13874       use of these functions.
13875
13876       If the direct appliance mode flag is enabled, then stdin and stdout are
13877       passed directly through to the appliance once it is launched.
13878
13879       One consequence of this is that log messages aren't caught by the
13880       library and handled by "guestfs_set_log_message_callback", but go
13881       straight to stdout.
13882
13883       You probably don't want to use this unless you know what you are doing.
13884
13885       The default is disabled.
13886
13887       This function returns 0 on success or -1 on error.
13888
13889       (Added in 1.0.72)
13890
13891   guestfs_set_e2attrs
13892        int
13893        guestfs_set_e2attrs (guestfs_h *g,
13894                             const char *file,
13895                             const char *attrs,
13896                             ...);
13897
13898       You may supply a list of optional arguments to this call.  Use zero or
13899       more of the following pairs of parameters, and terminate the list with
13900       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
13901
13902        GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13903
13904       This sets or clears the file attributes "attrs" associated with the
13905       inode file.
13906
13907       "attrs" is a string of characters representing file attributes.  See
13908       "guestfs_get_e2attrs" for a list of possible attributes.  Not all
13909       attributes can be changed.
13910
13911       If optional boolean "clear" is not present or false, then the "attrs"
13912       listed are set in the inode.
13913
13914       If "clear" is true, then the "attrs" listed are cleared in the inode.
13915
13916       In both cases, other attributes not present in the "attrs" string are
13917       left unchanged.
13918
13919       These attributes are only present when the file is located on an
13920       ext2/3/4 filesystem.  Using this call on other filesystem types will
13921       result in an error.
13922
13923       This function returns 0 on success or -1 on error.
13924
13925       (Added in 1.17.31)
13926
13927   guestfs_set_e2attrs_va
13928        int
13929        guestfs_set_e2attrs_va (guestfs_h *g,
13930                                const char *file,
13931                                const char *attrs,
13932                                va_list args);
13933
13934       This is the "va_list variant" of "guestfs_set_e2attrs".
13935
13936       See "CALLS WITH OPTIONAL ARGUMENTS".
13937
13938   guestfs_set_e2attrs_argv
13939        int
13940        guestfs_set_e2attrs_argv (guestfs_h *g,
13941                                  const char *file,
13942                                  const char *attrs,
13943                                  const struct guestfs_set_e2attrs_argv *optargs);
13944
13945       This is the "argv variant" of "guestfs_set_e2attrs".
13946
13947       See "CALLS WITH OPTIONAL ARGUMENTS".
13948
13949   guestfs_set_e2generation
13950        int
13951        guestfs_set_e2generation (guestfs_h *g,
13952                                  const char *file,
13953                                  int64_t generation);
13954
13955       This sets the ext2 file generation of a file.
13956
13957       See "guestfs_get_e2generation".
13958
13959       This function returns 0 on success or -1 on error.
13960
13961       (Added in 1.17.31)
13962
13963   guestfs_set_e2label
13964        int
13965        guestfs_set_e2label (guestfs_h *g,
13966                             const char *device,
13967                             const char *label);
13968
13969       This function is deprecated.  In new code, use the "guestfs_set_label"
13970       call instead.
13971
13972       Deprecated functions will not be removed from the API, but the fact
13973       that they are deprecated indicates that there are problems with correct
13974       use of these functions.
13975
13976       This sets the ext2/3/4 filesystem label of the filesystem on "device"
13977       to "label".  Filesystem labels are limited to 16 characters.
13978
13979       You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13980       return the existing label on a filesystem.
13981
13982       This function returns 0 on success or -1 on error.
13983
13984       (Added in 1.0.15)
13985
13986   guestfs_set_e2uuid
13987        int
13988        guestfs_set_e2uuid (guestfs_h *g,
13989                            const char *device,
13990                            const char *uuid);
13991
13992       This function is deprecated.  In new code, use the "guestfs_set_uuid"
13993       call instead.
13994
13995       Deprecated functions will not be removed from the API, but the fact
13996       that they are deprecated indicates that there are problems with correct
13997       use of these functions.
13998
13999       This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
14000       "uuid".  The format of the UUID and alternatives such as "clear",
14001       "random" and "time" are described in the tune2fs(8) manpage.
14002
14003       You can use "guestfs_vfs_uuid" to return the existing UUID of a
14004       filesystem.
14005
14006       This function returns 0 on success or -1 on error.
14007
14008       (Added in 1.0.15)
14009
14010   guestfs_set_hv
14011        int
14012        guestfs_set_hv (guestfs_h *g,
14013                        const char *hv);
14014
14015       Set the hypervisor binary that we will use.  The hypervisor depends on
14016       the backend, but is usually the location of the qemu/KVM hypervisor.
14017       For the uml backend, it is the location of the "linux" or "vmlinux"
14018       binary.
14019
14020       The default is chosen when the library was compiled by the configure
14021       script.
14022
14023       You can also override this by setting the "LIBGUESTFS_HV" environment
14024       variable.
14025
14026       Note that you should call this function as early as possible after
14027       creating the handle.  This is because some pre-launch operations depend
14028       on testing qemu features (by running "qemu -help").  If the qemu binary
14029       changes, we don't retest features, and so you might see inconsistent
14030       results.  Using the environment variable "LIBGUESTFS_HV" is safest of
14031       all since that picks the qemu binary at the same time as the handle is
14032       created.
14033
14034       This function returns 0 on success or -1 on error.
14035
14036       (Added in 1.23.17)
14037
14038   guestfs_set_identifier
14039        int
14040        guestfs_set_identifier (guestfs_h *g,
14041                                const char *identifier);
14042
14043       This is an informative string which the caller may optionally set in
14044       the handle.  It is printed in various places, allowing the current
14045       handle to be identified in debugging output.
14046
14047       One important place is when tracing is enabled.  If the identifier
14048       string is not an empty string, then trace messages change from this:
14049
14050        libguestfs: trace: get_tmpdir
14051        libguestfs: trace: get_tmpdir = "/tmp"
14052
14053       to this:
14054
14055        libguestfs: trace: ID: get_tmpdir
14056        libguestfs: trace: ID: get_tmpdir = "/tmp"
14057
14058       where "ID" is the identifier string set by this call.
14059
14060       The identifier must only contain alphanumeric ASCII characters,
14061       underscore and minus sign.  The default is the empty string.
14062
14063       See also "guestfs_set_program", "guestfs_set_trace",
14064       "guestfs_get_identifier".
14065
14066       This function returns 0 on success or -1 on error.
14067
14068       (Added in 1.31.14)
14069
14070   guestfs_set_label
14071        int
14072        guestfs_set_label (guestfs_h *g,
14073                           const char *mountable,
14074                           const char *label);
14075
14076       Set the filesystem label on "mountable" to "label".
14077
14078       Only some filesystem types support labels, and libguestfs supports
14079       setting labels on only a subset of these.
14080
14081       ext2, ext3, ext4
14082           Labels are limited to 16 bytes.
14083
14084       NTFS
14085           Labels are limited to 128 unicode characters.
14086
14087       XFS The label is limited to 12 bytes.  The filesystem must not be
14088           mounted when trying to set the label.
14089
14090       btrfs
14091           The label is limited to 255 bytes and some characters are not
14092           allowed.  Setting the label on a btrfs subvolume will set the label
14093           on its parent filesystem.  The filesystem must not be mounted when
14094           trying to set the label.
14095
14096       fat The label is limited to 11 bytes.
14097
14098       swap
14099           The label is limited to 16 bytes.
14100
14101       If there is no support for changing the label for the type of the
14102       specified filesystem, set_label will fail and set errno as ENOTSUP.
14103
14104       To read the label on a filesystem, call "guestfs_vfs_label".
14105
14106       This function returns 0 on success or -1 on error.
14107
14108       (Added in 1.17.9)
14109
14110   guestfs_set_libvirt_requested_credential
14111        int
14112        guestfs_set_libvirt_requested_credential (guestfs_h *g,
14113                                                  int index,
14114                                                  const char *cred,
14115                                                  size_t cred_size);
14116
14117       After requesting the "index"'th credential from the user, call this
14118       function to pass the answer back to libvirt.
14119
14120       See "LIBVIRT AUTHENTICATION" for documentation and example code.
14121
14122       This function returns 0 on success or -1 on error.
14123
14124       (Added in 1.19.52)
14125
14126   guestfs_set_libvirt_supported_credentials
14127        int
14128        guestfs_set_libvirt_supported_credentials (guestfs_h *g,
14129                                                   char *const *creds);
14130
14131       Call this function before setting an event handler for
14132       "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
14133       that the program knows how to process.
14134
14135       The "creds" list must be a non-empty list of strings.  Possible strings
14136       are:
14137
14138       "username"
14139       "authname"
14140       "language"
14141       "cnonce"
14142       "passphrase"
14143       "echoprompt"
14144       "noechoprompt"
14145       "realm"
14146       "external"
14147
14148       See libvirt documentation for the meaning of these credential types.
14149
14150       See "LIBVIRT AUTHENTICATION" for documentation and example code.
14151
14152       This function returns 0 on success or -1 on error.
14153
14154       (Added in 1.19.52)
14155
14156   guestfs_set_memsize
14157        int
14158        guestfs_set_memsize (guestfs_h *g,
14159                             int memsize);
14160
14161       This sets the memory size in megabytes allocated to the hypervisor.
14162       This only has any effect if called before "guestfs_launch".
14163
14164       You can also change this by setting the environment variable
14165       "LIBGUESTFS_MEMSIZE" before the handle is created.
14166
14167       For more information on the architecture of libguestfs, see guestfs(3).
14168
14169       This function returns 0 on success or -1 on error.
14170
14171       (Added in 1.0.55)
14172
14173   guestfs_set_network
14174        int
14175        guestfs_set_network (guestfs_h *g,
14176                             int network);
14177
14178       If "network" is true, then the network is enabled in the libguestfs
14179       appliance.  The default is false.
14180
14181       This affects whether commands are able to access the network (see
14182       "RUNNING COMMANDS").
14183
14184       You must call this before calling "guestfs_launch", otherwise it has no
14185       effect.
14186
14187       This function returns 0 on success or -1 on error.
14188
14189       (Added in 1.5.4)
14190
14191   guestfs_set_path
14192        int
14193        guestfs_set_path (guestfs_h *g,
14194                          const char *searchpath);
14195
14196       Set the path that libguestfs searches for kernel and initrd.img.
14197
14198       The default is "$libdir/guestfs" unless overridden by setting
14199       "LIBGUESTFS_PATH" environment variable.
14200
14201       Setting "path" to "NULL" restores the default path.
14202
14203       This function returns 0 on success or -1 on error.
14204
14205       (Added in 0.3)
14206
14207   guestfs_set_pgroup
14208        int
14209        guestfs_set_pgroup (guestfs_h *g,
14210                            int pgroup);
14211
14212       If "pgroup" is true, child processes are placed into their own process
14213       group.
14214
14215       The practical upshot of this is that signals like "SIGINT" (from users
14216       pressing "^C") won't be received by the child process.
14217
14218       The default for this flag is false, because usually you want "^C" to
14219       kill the subprocess.  Guestfish sets this flag to true when used
14220       interactively, so that "^C" can cancel long-running commands gracefully
14221       (see "guestfs_user_cancel").
14222
14223       This function returns 0 on success or -1 on error.
14224
14225       (Added in 1.11.18)
14226
14227   guestfs_set_program
14228        int
14229        guestfs_set_program (guestfs_h *g,
14230                             const char *program);
14231
14232       Set the program name.  This is an informative string which the main
14233       program may optionally set in the handle.
14234
14235       When the handle is created, the program name in the handle is set to
14236       the basename from "argv[0]".  The program name can never be "NULL".
14237
14238       This function returns 0 on success or -1 on error.
14239
14240       (Added in 1.21.29)
14241
14242   guestfs_set_qemu
14243        int
14244        guestfs_set_qemu (guestfs_h *g,
14245                          const char *hv);
14246
14247       This function is deprecated.  In new code, use the "guestfs_set_hv"
14248       call instead.
14249
14250       Deprecated functions will not be removed from the API, but the fact
14251       that they are deprecated indicates that there are problems with correct
14252       use of these functions.
14253
14254       Set the hypervisor binary (usually qemu) that we will use.
14255
14256       The default is chosen when the library was compiled by the configure
14257       script.
14258
14259       You can also override this by setting the "LIBGUESTFS_HV" environment
14260       variable.
14261
14262       Setting "hv" to "NULL" restores the default qemu binary.
14263
14264       Note that you should call this function as early as possible after
14265       creating the handle.  This is because some pre-launch operations depend
14266       on testing qemu features (by running "qemu -help").  If the qemu binary
14267       changes, we don't retest features, and so you might see inconsistent
14268       results.  Using the environment variable "LIBGUESTFS_HV" is safest of
14269       all since that picks the qemu binary at the same time as the handle is
14270       created.
14271
14272       This function returns 0 on success or -1 on error.
14273
14274       (Added in 1.0.6)
14275
14276   guestfs_set_recovery_proc
14277        int
14278        guestfs_set_recovery_proc (guestfs_h *g,
14279                                   int recoveryproc);
14280
14281       If this is called with the parameter "false" then "guestfs_launch" does
14282       not create a recovery process.  The purpose of the recovery process is
14283       to stop runaway hypervisor processes in the case where the main program
14284       aborts abruptly.
14285
14286       This only has any effect if called before "guestfs_launch", and the
14287       default is true.
14288
14289       About the only time when you would want to disable this is if the main
14290       process will fork itself into the background ("daemonize" itself).  In
14291       this case the recovery process thinks that the main program has
14292       disappeared and so kills the hypervisor, which is not very helpful.
14293
14294       This function returns 0 on success or -1 on error.
14295
14296       (Added in 1.0.77)
14297
14298   guestfs_set_selinux
14299        int
14300        guestfs_set_selinux (guestfs_h *g,
14301                             int selinux);
14302
14303       This function is deprecated.  In new code, use the
14304       "guestfs_selinux_relabel" call instead.
14305
14306       Deprecated functions will not be removed from the API, but the fact
14307       that they are deprecated indicates that there are problems with correct
14308       use of these functions.
14309
14310       This sets the selinux flag that is passed to the appliance at boot
14311       time.  The default is "selinux=0" (disabled).
14312
14313       Note that if SELinux is enabled, it is always in Permissive mode
14314       ("enforcing=0").
14315
14316       For more information on the architecture of libguestfs, see guestfs(3).
14317
14318       This function returns 0 on success or -1 on error.
14319
14320       (Added in 1.0.67)
14321
14322   guestfs_set_smp
14323        int
14324        guestfs_set_smp (guestfs_h *g,
14325                         int smp);
14326
14327       Change the number of virtual CPUs assigned to the appliance.  The
14328       default is 1.  Increasing this may improve performance, though often it
14329       has no effect.
14330
14331       This function must be called before "guestfs_launch".
14332
14333       This function returns 0 on success or -1 on error.
14334
14335       (Added in 1.13.15)
14336
14337   guestfs_set_tmpdir
14338        int
14339        guestfs_set_tmpdir (guestfs_h *g,
14340                            const char *tmpdir);
14341
14342       Set the directory used by the handle to store temporary files.
14343
14344       The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14345       default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14346       Else if "TMPDIR" is set, then that is the default.  Else /tmp is the
14347       default.
14348
14349       This function returns 0 on success or -1 on error.
14350
14351       (Added in 1.19.58)
14352
14353   guestfs_set_trace
14354        int
14355        guestfs_set_trace (guestfs_h *g,
14356                           int trace);
14357
14358       If the command trace flag is set to 1, then libguestfs calls,
14359       parameters and return values are traced.
14360
14361       If you want to trace C API calls into libguestfs (and other libraries)
14362       then possibly a better way is to use the external ltrace(1) command.
14363
14364       Command traces are disabled unless the environment variable
14365       "LIBGUESTFS_TRACE" is defined and set to 1.
14366
14367       Trace messages are normally sent to "stderr", unless you register a
14368       callback to send them somewhere else (see
14369       "guestfs_set_event_callback").
14370
14371       This function returns 0 on success or -1 on error.
14372
14373       (Added in 1.0.69)
14374
14375   guestfs_set_uuid
14376        int
14377        guestfs_set_uuid (guestfs_h *g,
14378                          const char *device,
14379                          const char *uuid);
14380
14381       Set the filesystem UUID on "device" to "uuid".  If this fails and the
14382       errno is ENOTSUP, means that there is no support for changing the UUID
14383       for the type of the specified filesystem.
14384
14385       Only some filesystem types support setting UUIDs.
14386
14387       To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14388
14389       This function returns 0 on success or -1 on error.
14390
14391       (Added in 1.23.10)
14392
14393   guestfs_set_uuid_random
14394        int
14395        guestfs_set_uuid_random (guestfs_h *g,
14396                                 const char *device);
14397
14398       Set the filesystem UUID on "device" to a random UUID.  If this fails
14399       and the errno is ENOTSUP, means that there is no support for changing
14400       the UUID for the type of the specified filesystem.
14401
14402       Only some filesystem types support setting UUIDs.
14403
14404       To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14405
14406       This function returns 0 on success or -1 on error.
14407
14408       (Added in 1.29.50)
14409
14410   guestfs_set_verbose
14411        int
14412        guestfs_set_verbose (guestfs_h *g,
14413                             int verbose);
14414
14415       If "verbose" is true, this turns on verbose messages.
14416
14417       Verbose messages are disabled unless the environment variable
14418       "LIBGUESTFS_DEBUG" is defined and set to 1.
14419
14420       Verbose messages are normally sent to "stderr", unless you register a
14421       callback to send them somewhere else (see
14422       "guestfs_set_event_callback").
14423
14424       This function returns 0 on success or -1 on error.
14425
14426       (Added in 0.3)
14427
14428   guestfs_setcon
14429        int
14430        guestfs_setcon (guestfs_h *g,
14431                        const char *context);
14432
14433       This function is deprecated.  In new code, use the
14434       "guestfs_selinux_relabel" call instead.
14435
14436       Deprecated functions will not be removed from the API, but the fact
14437       that they are deprecated indicates that there are problems with correct
14438       use of these functions.
14439
14440       This sets the SELinux security context of the daemon to the string
14441       "context".
14442
14443       See the documentation about SELINUX in guestfs(3).
14444
14445       This function returns 0 on success or -1 on error.
14446
14447       This function depends on the feature "selinux".  See also
14448       "guestfs_feature_available".
14449
14450       (Added in 1.0.67)
14451
14452   guestfs_setxattr
14453        int
14454        guestfs_setxattr (guestfs_h *g,
14455                          const char *xattr,
14456                          const char *val,
14457                          int vallen,
14458                          const char *path);
14459
14460       This call sets the extended attribute named "xattr" of the file "path"
14461       to the value "val" (of length "vallen").  The value is arbitrary 8 bit
14462       data.
14463
14464       See also: "guestfs_lsetxattr", attr(5).
14465
14466       This function returns 0 on success or -1 on error.
14467
14468       This function depends on the feature "linuxxattrs".  See also
14469       "guestfs_feature_available".
14470
14471       (Added in 1.0.59)
14472
14473   guestfs_sfdisk
14474        int
14475        guestfs_sfdisk (guestfs_h *g,
14476                        const char *device,
14477                        int cyls,
14478                        int heads,
14479                        int sectors,
14480                        char *const *lines);
14481
14482       This function is deprecated.  In new code, use the "guestfs_part_add"
14483       call instead.
14484
14485       Deprecated functions will not be removed from the API, but the fact
14486       that they are deprecated indicates that there are problems with correct
14487       use of these functions.
14488
14489       This is a direct interface to the sfdisk(8) program for creating
14490       partitions on block devices.
14491
14492       "device" should be a block device, for example /dev/sda.
14493
14494       "cyls", "heads" and "sectors" are the number of cylinders, heads and
14495       sectors on the device, which are passed directly to sfdisk(8) as the
14496       -C, -H and -S parameters.  If you pass 0 for any of these, then the
14497       corresponding parameter is omitted.  Usually for ‘large’ disks, you can
14498       just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
14499       (or rather, the kernel) cannot work out the right geometry and you will
14500       need to tell it.
14501
14502       "lines" is a list of lines that we feed to sfdisk(8).  For more
14503       information refer to the sfdisk(8) manpage.
14504
14505       To create a single partition occupying the whole disk, you would pass
14506       "lines" as a single element list, when the single element being the
14507       string "," (comma).
14508
14509       See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14510
14511       This function returns 0 on success or -1 on error.
14512
14513       (Added in 0.8)
14514
14515   guestfs_sfdiskM
14516        int
14517        guestfs_sfdiskM (guestfs_h *g,
14518                         const char *device,
14519                         char *const *lines);
14520
14521       This function is deprecated.  In new code, use the "guestfs_part_add"
14522       call instead.
14523
14524       Deprecated functions will not be removed from the API, but the fact
14525       that they are deprecated indicates that there are problems with correct
14526       use of these functions.
14527
14528       This is a simplified interface to the "guestfs_sfdisk" command, where
14529       partition sizes are specified in megabytes only (rounded to the nearest
14530       cylinder) and you don't need to specify the cyls, heads and sectors
14531       parameters which were rarely if ever used anyway.
14532
14533       See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14534       "guestfs_part_disk"
14535
14536       This function returns 0 on success or -1 on error.
14537
14538       (Added in 1.0.55)
14539
14540   guestfs_sfdisk_N
14541        int
14542        guestfs_sfdisk_N (guestfs_h *g,
14543                          const char *device,
14544                          int partnum,
14545                          int cyls,
14546                          int heads,
14547                          int sectors,
14548                          const char *line);
14549
14550       This function is deprecated.  In new code, use the "guestfs_part_add"
14551       call instead.
14552
14553       Deprecated functions will not be removed from the API, but the fact
14554       that they are deprecated indicates that there are problems with correct
14555       use of these functions.
14556
14557       This runs sfdisk(8) option to modify just the single partition "n"
14558       (note: "n" counts from 1).
14559
14560       For other parameters, see "guestfs_sfdisk".  You should usually pass 0
14561       for the cyls/heads/sectors parameters.
14562
14563       See also: "guestfs_part_add"
14564
14565       This function returns 0 on success or -1 on error.
14566
14567       (Added in 1.0.26)
14568
14569   guestfs_sfdisk_disk_geometry
14570        char *
14571        guestfs_sfdisk_disk_geometry (guestfs_h *g,
14572                                      const char *device);
14573
14574       This displays the disk geometry of "device" read from the partition
14575       table.  Especially in the case where the underlying block device has
14576       been resized, this can be different from the kernel’s idea of the
14577       geometry (see "guestfs_sfdisk_kernel_geometry").
14578
14579       The result is in human-readable format, and not designed to be parsed.
14580
14581       This function returns a string, or NULL on error.  The caller must free
14582       the returned string after use.
14583
14584       (Added in 1.0.26)
14585
14586   guestfs_sfdisk_kernel_geometry
14587        char *
14588        guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14589                                        const char *device);
14590
14591       This displays the kernel’s idea of the geometry of "device".
14592
14593       The result is in human-readable format, and not designed to be parsed.
14594
14595       This function returns a string, or NULL on error.  The caller must free
14596       the returned string after use.
14597
14598       (Added in 1.0.26)
14599
14600   guestfs_sfdisk_l
14601        char *
14602        guestfs_sfdisk_l (guestfs_h *g,
14603                          const char *device);
14604
14605       This function is deprecated.  In new code, use the "guestfs_part_list"
14606       call instead.
14607
14608       Deprecated functions will not be removed from the API, but the fact
14609       that they are deprecated indicates that there are problems with correct
14610       use of these functions.
14611
14612       This displays the partition table on "device", in the human-readable
14613       output of the sfdisk(8) command.  It is not intended to be parsed.
14614
14615       See also: "guestfs_part_list"
14616
14617       This function returns a string, or NULL on error.  The caller must free
14618       the returned string after use.
14619
14620       (Added in 1.0.26)
14621
14622   guestfs_sh
14623        char *
14624        guestfs_sh (guestfs_h *g,
14625                    const char *command);
14626
14627       This call runs a command from the guest filesystem via the guest’s
14628       /bin/sh.
14629
14630       This is like "guestfs_command", but passes the command to:
14631
14632        /bin/sh -c "command"
14633
14634       Depending on the guest’s shell, this usually results in wildcards being
14635       expanded, shell expressions being interpolated and so on.
14636
14637       All the provisos about "guestfs_command" apply to this call.
14638
14639       This function returns a string, or NULL on error.  The caller must free
14640       the returned string after use.
14641
14642       (Added in 1.0.50)
14643
14644   guestfs_sh_lines
14645        char **
14646        guestfs_sh_lines (guestfs_h *g,
14647                          const char *command);
14648
14649       This is the same as "guestfs_sh", but splits the result into a list of
14650       lines.
14651
14652       See also: "guestfs_command_lines"
14653
14654       This function returns a NULL-terminated array of strings (like
14655       environ(3)), or NULL if there was an error.  The caller must free the
14656       strings and the array after use.
14657
14658       (Added in 1.0.50)
14659
14660   guestfs_shutdown
14661        int
14662        guestfs_shutdown (guestfs_h *g);
14663
14664       This is the opposite of "guestfs_launch".  It performs an orderly
14665       shutdown of the backend process(es).  If the autosync flag is set
14666       (which is the default) then the disk image is synchronized.
14667
14668       If the subprocess exits with an error then this function will return an
14669       error, which should not be ignored (it may indicate that the disk image
14670       could not be written out properly).
14671
14672       It is safe to call this multiple times.  Extra calls are ignored.
14673
14674       This call does not close or free up the handle.  You still need to call
14675       "guestfs_close" afterwards.
14676
14677       "guestfs_close" will call this if you don't do it explicitly, but note
14678       that any errors are ignored in that case.
14679
14680       This function returns 0 on success or -1 on error.
14681
14682       (Added in 1.19.16)
14683
14684   guestfs_sleep
14685        int
14686        guestfs_sleep (guestfs_h *g,
14687                       int secs);
14688
14689       Sleep for "secs" seconds.
14690
14691       This function returns 0 on success or -1 on error.
14692
14693       (Added in 1.0.41)
14694
14695   guestfs_stat
14696        struct guestfs_stat *
14697        guestfs_stat (guestfs_h *g,
14698                      const char *path);
14699
14700       This function is deprecated.  In new code, use the "guestfs_statns"
14701       call instead.
14702
14703       Deprecated functions will not be removed from the API, but the fact
14704       that they are deprecated indicates that there are problems with correct
14705       use of these functions.
14706
14707       Returns file information for the given "path".
14708
14709       This is the same as the stat(2) system call.
14710
14711       This function returns a "struct guestfs_stat *", or NULL if there was
14712       an error.  The caller must call "guestfs_free_stat" after use.
14713
14714       (Added in 1.9.2)
14715
14716   guestfs_statns
14717        struct guestfs_statns *
14718        guestfs_statns (guestfs_h *g,
14719                        const char *path);
14720
14721       Returns file information for the given "path".
14722
14723       This is the same as the stat(2) system call.
14724
14725       This function returns a "struct guestfs_statns *", or NULL if there was
14726       an error.  The caller must call "guestfs_free_statns" after use.
14727
14728       (Added in 1.27.53)
14729
14730   guestfs_statvfs
14731        struct guestfs_statvfs *
14732        guestfs_statvfs (guestfs_h *g,
14733                         const char *path);
14734
14735       Returns file system statistics for any mounted file system.  "path"
14736       should be a file or directory in the mounted file system (typically it
14737       is the mount point itself, but it doesn't need to be).
14738
14739       This is the same as the statvfs(2) system call.
14740
14741       This function returns a "struct guestfs_statvfs *", or NULL if there
14742       was an error.  The caller must call "guestfs_free_statvfs" after use.
14743
14744       (Added in 1.9.2)
14745
14746   guestfs_strings
14747        char **
14748        guestfs_strings (guestfs_h *g,
14749                         const char *path);
14750
14751       This runs the strings(1) command on a file and returns the list of
14752       printable strings found.
14753
14754       The "strings" command has, in the past, had problems with parsing
14755       untrusted files.  These are mitigated in the current version of
14756       libguestfs, but see "CVE-2014-8484".
14757
14758       This function returns a NULL-terminated array of strings (like
14759       environ(3)), or NULL if there was an error.  The caller must free the
14760       strings and the array after use.
14761
14762       Because of the message protocol, there is a transfer limit of somewhere
14763       between 2MB and 4MB.  See "PROTOCOL LIMITS".
14764
14765       (Added in 1.0.22)
14766
14767   guestfs_strings_e
14768        char **
14769        guestfs_strings_e (guestfs_h *g,
14770                           const char *encoding,
14771                           const char *path);
14772
14773       This is like the "guestfs_strings" command, but allows you to specify
14774       the encoding of strings that are looked for in the source file "path".
14775
14776       Allowed encodings are:
14777
14778       s   Single 7-bit-byte characters like ASCII and the ASCII-compatible
14779           parts of ISO-8859-X (this is what "guestfs_strings" uses).
14780
14781       S   Single 8-bit-byte characters.
14782
14783       b   16-bit big endian strings such as those encoded in UTF-16BE or
14784           UCS-2BE.
14785
14786       l (lower case letter L)
14787           16-bit little endian such as UTF-16LE and UCS-2LE.  This is useful
14788           for examining binaries in Windows guests.
14789
14790       B   32-bit big endian such as UCS-4BE.
14791
14792       L   32-bit little endian such as UCS-4LE.
14793
14794       The returned strings are transcoded to UTF-8.
14795
14796       The "strings" command has, in the past, had problems with parsing
14797       untrusted files.  These are mitigated in the current version of
14798       libguestfs, but see "CVE-2014-8484".
14799
14800       This function returns a NULL-terminated array of strings (like
14801       environ(3)), or NULL if there was an error.  The caller must free the
14802       strings and the array after use.
14803
14804       Because of the message protocol, there is a transfer limit of somewhere
14805       between 2MB and 4MB.  See "PROTOCOL LIMITS".
14806
14807       (Added in 1.0.22)
14808
14809   guestfs_swapoff_device
14810        int
14811        guestfs_swapoff_device (guestfs_h *g,
14812                                const char *device);
14813
14814       This command disables the libguestfs appliance swap device or partition
14815       named "device".  See "guestfs_swapon_device".
14816
14817       This function returns 0 on success or -1 on error.
14818
14819       (Added in 1.0.66)
14820
14821   guestfs_swapoff_file
14822        int
14823        guestfs_swapoff_file (guestfs_h *g,
14824                              const char *file);
14825
14826       This command disables the libguestfs appliance swap on file.
14827
14828       This function returns 0 on success or -1 on error.
14829
14830       (Added in 1.0.66)
14831
14832   guestfs_swapoff_label
14833        int
14834        guestfs_swapoff_label (guestfs_h *g,
14835                               const char *label);
14836
14837       This command disables the libguestfs appliance swap on labeled swap
14838       partition.
14839
14840       This function returns 0 on success or -1 on error.
14841
14842       (Added in 1.0.66)
14843
14844   guestfs_swapoff_uuid
14845        int
14846        guestfs_swapoff_uuid (guestfs_h *g,
14847                              const char *uuid);
14848
14849       This command disables the libguestfs appliance swap partition with the
14850       given UUID.
14851
14852       This function returns 0 on success or -1 on error.
14853
14854       This function depends on the feature "linuxfsuuid".  See also
14855       "guestfs_feature_available".
14856
14857       (Added in 1.0.66)
14858
14859   guestfs_swapon_device
14860        int
14861        guestfs_swapon_device (guestfs_h *g,
14862                               const char *device);
14863
14864       This command enables the libguestfs appliance to use the swap device or
14865       partition named "device".  The increased memory is made available for
14866       all commands, for example those run using "guestfs_command" or
14867       "guestfs_sh".
14868
14869       Note that you should not swap to existing guest swap partitions unless
14870       you know what you are doing.  They may contain hibernation information,
14871       or other information that the guest doesn't want you to trash.  You
14872       also risk leaking information about the host to the guest this way.
14873       Instead, attach a new host device to the guest and swap on that.
14874
14875       This function returns 0 on success or -1 on error.
14876
14877       (Added in 1.0.66)
14878
14879   guestfs_swapon_file
14880        int
14881        guestfs_swapon_file (guestfs_h *g,
14882                             const char *file);
14883
14884       This command enables swap to a file.  See "guestfs_swapon_device" for
14885       other notes.
14886
14887       This function returns 0 on success or -1 on error.
14888
14889       (Added in 1.0.66)
14890
14891   guestfs_swapon_label
14892        int
14893        guestfs_swapon_label (guestfs_h *g,
14894                              const char *label);
14895
14896       This command enables swap to a labeled swap partition.  See
14897       "guestfs_swapon_device" for other notes.
14898
14899       This function returns 0 on success or -1 on error.
14900
14901       (Added in 1.0.66)
14902
14903   guestfs_swapon_uuid
14904        int
14905        guestfs_swapon_uuid (guestfs_h *g,
14906                             const char *uuid);
14907
14908       This command enables swap to a swap partition with the given UUID.  See
14909       "guestfs_swapon_device" for other notes.
14910
14911       This function returns 0 on success or -1 on error.
14912
14913       This function depends on the feature "linuxfsuuid".  See also
14914       "guestfs_feature_available".
14915
14916       (Added in 1.0.66)
14917
14918   guestfs_sync
14919        int
14920        guestfs_sync (guestfs_h *g);
14921
14922       This syncs the disk, so that any writes are flushed through to the
14923       underlying disk image.
14924
14925       You should always call this if you have modified a disk image, before
14926       closing the handle.
14927
14928       This function returns 0 on success or -1 on error.
14929
14930       (Added in 0.3)
14931
14932   guestfs_syslinux
14933        int
14934        guestfs_syslinux (guestfs_h *g,
14935                          const char *device,
14936                          ...);
14937
14938       You may supply a list of optional arguments to this call.  Use zero or
14939       more of the following pairs of parameters, and terminate the list with
14940       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
14941
14942        GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14943
14944       Install the SYSLINUX bootloader on "device".
14945
14946       The device parameter must be either a whole disk formatted as a FAT
14947       filesystem, or a partition formatted as a FAT filesystem.  In the
14948       latter case, the partition should be marked as "active"
14949       ("guestfs_part_set_bootable") and a Master Boot Record must be
14950       installed (eg. using "guestfs_pwrite_device") on the first sector of
14951       the whole disk.  The SYSLINUX package comes with some suitable Master
14952       Boot Records.  See the syslinux(1) man page for further information.
14953
14954       The optional arguments are:
14955
14956       directory
14957           Install SYSLINUX in the named subdirectory, instead of in the root
14958           directory of the FAT filesystem.
14959
14960       Additional configuration can be supplied to SYSLINUX by placing a file
14961       called syslinux.cfg on the FAT filesystem, either in the root
14962       directory, or under directory if that optional argument is being used.
14963       For further information about the contents of this file, see
14964       syslinux(1).
14965
14966       See also "guestfs_extlinux".
14967
14968       This function returns 0 on success or -1 on error.
14969
14970       This function depends on the feature "syslinux".  See also
14971       "guestfs_feature_available".
14972
14973       (Added in 1.21.27)
14974
14975   guestfs_syslinux_va
14976        int
14977        guestfs_syslinux_va (guestfs_h *g,
14978                             const char *device,
14979                             va_list args);
14980
14981       This is the "va_list variant" of "guestfs_syslinux".
14982
14983       See "CALLS WITH OPTIONAL ARGUMENTS".
14984
14985   guestfs_syslinux_argv
14986        int
14987        guestfs_syslinux_argv (guestfs_h *g,
14988                               const char *device,
14989                               const struct guestfs_syslinux_argv *optargs);
14990
14991       This is the "argv variant" of "guestfs_syslinux".
14992
14993       See "CALLS WITH OPTIONAL ARGUMENTS".
14994
14995   guestfs_tail
14996        char **
14997        guestfs_tail (guestfs_h *g,
14998                      const char *path);
14999
15000       This command returns up to the last 10 lines of a file as a list of
15001       strings.
15002
15003       This function returns a NULL-terminated array of strings (like
15004       environ(3)), or NULL if there was an error.  The caller must free the
15005       strings and the array after use.
15006
15007       Because of the message protocol, there is a transfer limit of somewhere
15008       between 2MB and 4MB.  See "PROTOCOL LIMITS".
15009
15010       (Added in 1.0.54)
15011
15012   guestfs_tail_n
15013        char **
15014        guestfs_tail_n (guestfs_h *g,
15015                        int nrlines,
15016                        const char *path);
15017
15018       If the parameter "nrlines" is a positive number, this returns the last
15019       "nrlines" lines of the file "path".
15020
15021       If the parameter "nrlines" is a negative number, this returns lines
15022       from the file "path", starting with the "-nrlines"'th line.
15023
15024       If the parameter "nrlines" is zero, this returns an empty list.
15025
15026       This function returns a NULL-terminated array of strings (like
15027       environ(3)), or NULL if there was an error.  The caller must free the
15028       strings and the array after use.
15029
15030       Because of the message protocol, there is a transfer limit of somewhere
15031       between 2MB and 4MB.  See "PROTOCOL LIMITS".
15032
15033       (Added in 1.0.54)
15034
15035   guestfs_tar_in
15036        int
15037        guestfs_tar_in (guestfs_h *g,
15038                        const char *tarfile,
15039                        const char *directory);
15040
15041       This function is provided for backwards compatibility with earlier
15042       versions of libguestfs.  It simply calls "guestfs_tar_in_opts" with no
15043       optional arguments.
15044
15045       (Added in 1.0.3)
15046
15047   guestfs_tar_in_opts
15048        int
15049        guestfs_tar_in_opts (guestfs_h *g,
15050                             const char *tarfile,
15051                             const char *directory,
15052                             ...);
15053
15054       You may supply a list of optional arguments to this call.  Use zero or
15055       more of the following pairs of parameters, and terminate the list with
15056       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
15057
15058        GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
15059        GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
15060        GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
15061        GUESTFS_TAR_IN_OPTS_ACLS, int acls,
15062
15063       This command uploads and unpacks local file "tarfile" into directory.
15064
15065       The optional "compress" flag controls compression.  If not given, then
15066       the input should be an uncompressed tar file.  Otherwise one of the
15067       following strings may be given to select the compression type of the
15068       input file: "compress", "gzip", "bzip2", "xz", "lzop".  (Note that not
15069       all builds of libguestfs will support all of these compression types).
15070
15071       The other optional arguments are:
15072
15073       "xattrs"
15074           If set to true, extended attributes are restored from the tar file.
15075
15076       "selinux"
15077           If set to true, SELinux contexts are restored from the tar file.
15078
15079       "acls"
15080           If set to true, POSIX ACLs are restored from the tar file.
15081
15082       This function returns 0 on success or -1 on error.
15083
15084       (Added in 1.0.3)
15085
15086   guestfs_tar_in_opts_va
15087        int
15088        guestfs_tar_in_opts_va (guestfs_h *g,
15089                                const char *tarfile,
15090                                const char *directory,
15091                                va_list args);
15092
15093       This is the "va_list variant" of "guestfs_tar_in_opts".
15094
15095       See "CALLS WITH OPTIONAL ARGUMENTS".
15096
15097   guestfs_tar_in_opts_argv
15098        int
15099        guestfs_tar_in_opts_argv (guestfs_h *g,
15100                                  const char *tarfile,
15101                                  const char *directory,
15102                                  const struct guestfs_tar_in_opts_argv *optargs);
15103
15104       This is the "argv variant" of "guestfs_tar_in_opts".
15105
15106       See "CALLS WITH OPTIONAL ARGUMENTS".
15107
15108   guestfs_tar_out
15109        int
15110        guestfs_tar_out (guestfs_h *g,
15111                         const char *directory,
15112                         const char *tarfile);
15113
15114       This function is provided for backwards compatibility with earlier
15115       versions of libguestfs.  It simply calls "guestfs_tar_out_opts" with no
15116       optional arguments.
15117
15118       (Added in 1.0.3)
15119
15120   guestfs_tar_out_opts
15121        int
15122        guestfs_tar_out_opts (guestfs_h *g,
15123                              const char *directory,
15124                              const char *tarfile,
15125                              ...);
15126
15127       You may supply a list of optional arguments to this call.  Use zero or
15128       more of the following pairs of parameters, and terminate the list with
15129       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
15130
15131        GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
15132        GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
15133        GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
15134        GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
15135        GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
15136        GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
15137
15138       This command packs the contents of directory and downloads it to local
15139       file "tarfile".
15140
15141       The optional "compress" flag controls compression.  If not given, then
15142       the output will be an uncompressed tar file.  Otherwise one of the
15143       following strings may be given to select the compression type of the
15144       output file: "compress", "gzip", "bzip2", "xz", "lzop".  (Note that not
15145       all builds of libguestfs will support all of these compression types).
15146
15147       The other optional arguments are:
15148
15149       "excludes"
15150           A list of wildcards.  Files are excluded if they match any of the
15151           wildcards.
15152
15153       "numericowner"
15154           If set to true, the output tar file will contain UID/GID numbers
15155           instead of user/group names.
15156
15157       "xattrs"
15158           If set to true, extended attributes are saved in the output tar.
15159
15160       "selinux"
15161           If set to true, SELinux contexts are saved in the output tar.
15162
15163       "acls"
15164           If set to true, POSIX ACLs are saved in the output tar.
15165
15166       This function returns 0 on success or -1 on error.
15167
15168       (Added in 1.0.3)
15169
15170   guestfs_tar_out_opts_va
15171        int
15172        guestfs_tar_out_opts_va (guestfs_h *g,
15173                                 const char *directory,
15174                                 const char *tarfile,
15175                                 va_list args);
15176
15177       This is the "va_list variant" of "guestfs_tar_out_opts".
15178
15179       See "CALLS WITH OPTIONAL ARGUMENTS".
15180
15181   guestfs_tar_out_opts_argv
15182        int
15183        guestfs_tar_out_opts_argv (guestfs_h *g,
15184                                   const char *directory,
15185                                   const char *tarfile,
15186                                   const struct guestfs_tar_out_opts_argv *optargs);
15187
15188       This is the "argv variant" of "guestfs_tar_out_opts".
15189
15190       See "CALLS WITH OPTIONAL ARGUMENTS".
15191
15192   guestfs_tgz_in
15193        int
15194        guestfs_tgz_in (guestfs_h *g,
15195                        const char *tarball,
15196                        const char *directory);
15197
15198       This function is deprecated.  In new code, use the "guestfs_tar_in"
15199       call instead.
15200
15201       Deprecated functions will not be removed from the API, but the fact
15202       that they are deprecated indicates that there are problems with correct
15203       use of these functions.
15204
15205       This command uploads and unpacks local file "tarball" (a gzip
15206       compressed tar file) into directory.
15207
15208       This function returns 0 on success or -1 on error.
15209
15210       (Added in 1.0.3)
15211
15212   guestfs_tgz_out
15213        int
15214        guestfs_tgz_out (guestfs_h *g,
15215                         const char *directory,
15216                         const char *tarball);
15217
15218       This function is deprecated.  In new code, use the "guestfs_tar_out"
15219       call instead.
15220
15221       Deprecated functions will not be removed from the API, but the fact
15222       that they are deprecated indicates that there are problems with correct
15223       use of these functions.
15224
15225       This command packs the contents of directory and downloads it to local
15226       file "tarball".
15227
15228       This function returns 0 on success or -1 on error.
15229
15230       (Added in 1.0.3)
15231
15232   guestfs_touch
15233        int
15234        guestfs_touch (guestfs_h *g,
15235                       const char *path);
15236
15237       Touch acts like the touch(1) command.  It can be used to update the
15238       timestamps on a file, or, if the file does not exist, to create a new
15239       zero-length file.
15240
15241       This command only works on regular files, and will fail on other file
15242       types such as directories, symbolic links, block special etc.
15243
15244       This function returns 0 on success or -1 on error.
15245
15246       (Added in 0.3)
15247
15248   guestfs_truncate
15249        int
15250        guestfs_truncate (guestfs_h *g,
15251                          const char *path);
15252
15253       This command truncates "path" to a zero-length file.  The file must
15254       exist already.
15255
15256       This function returns 0 on success or -1 on error.
15257
15258       (Added in 1.0.77)
15259
15260   guestfs_truncate_size
15261        int
15262        guestfs_truncate_size (guestfs_h *g,
15263                               const char *path,
15264                               int64_t size);
15265
15266       This command truncates "path" to size "size" bytes.  The file must
15267       exist already.
15268
15269       If the current file size is less than "size" then the file is extended
15270       to the required size with zero bytes.  This creates a sparse file (ie.
15271       disk blocks are not allocated for the file until you write to it).  To
15272       create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15273
15274       This function returns 0 on success or -1 on error.
15275
15276       (Added in 1.0.77)
15277
15278   guestfs_tune2fs
15279        int
15280        guestfs_tune2fs (guestfs_h *g,
15281                         const char *device,
15282                         ...);
15283
15284       You may supply a list of optional arguments to this call.  Use zero or
15285       more of the following pairs of parameters, and terminate the list with
15286       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
15287
15288        GUESTFS_TUNE2FS_FORCE, int force,
15289        GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15290        GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15291        GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15292        GUESTFS_TUNE2FS_GROUP, int64_t group,
15293        GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15294        GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15295        GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15296        GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15297        GUESTFS_TUNE2FS_USER, int64_t user,
15298
15299       This call allows you to adjust various filesystem parameters of an
15300       ext2/ext3/ext4 filesystem called "device".
15301
15302       The optional parameters are:
15303
15304       "force"
15305           Force tune2fs to complete the operation even in the face of errors.
15306           This is the same as the tune2fs(8) "-f" option.
15307
15308       "maxmountcount"
15309           Set the number of mounts after which the filesystem is checked by
15310           e2fsck(8).  If this is 0 then the number of mounts is disregarded.
15311           This is the same as the tune2fs(8) "-c" option.
15312
15313       "mountcount"
15314           Set the number of times the filesystem has been mounted.  This is
15315           the same as the tune2fs(8) "-C" option.
15316
15317       "errorbehavior"
15318           Change the behavior of the kernel code when errors are detected.
15319           Possible values currently are: "continue", "remount-ro", "panic".
15320           In practice these options don't really make any difference,
15321           particularly for write errors.
15322
15323           This is the same as the tune2fs(8) "-e" option.
15324
15325       "group"
15326           Set the group which can use reserved filesystem blocks.  This is
15327           the same as the tune2fs(8) "-g" option except that it can only be
15328           specified as a number.
15329
15330       "intervalbetweenchecks"
15331           Adjust the maximal time between two filesystem checks (in seconds).
15332           If the option is passed as 0 then time-dependent checking is
15333           disabled.
15334
15335           This is the same as the tune2fs(8) "-i" option.
15336
15337       "reservedblockspercentage"
15338           Set the percentage of the filesystem which may only be allocated by
15339           privileged processes.  This is the same as the tune2fs(8) "-m"
15340           option.
15341
15342       "lastmounteddirectory"
15343           Set the last mounted directory.  This is the same as the tune2fs(8)
15344           "-M" option.
15345
15346       "reservedblockscount" Set the number of reserved filesystem blocks.
15347       This is the same as the tune2fs(8) "-r" option.
15348       "user"
15349           Set the user who can use the reserved filesystem blocks.  This is
15350           the same as the tune2fs(8) "-u" option except that it can only be
15351           specified as a number.
15352
15353       To get the current values of filesystem parameters, see
15354       "guestfs_tune2fs_l".  For precise details of how tune2fs works, see the
15355       tune2fs(8) man page.
15356
15357       This function returns 0 on success or -1 on error.
15358
15359       (Added in 1.15.4)
15360
15361   guestfs_tune2fs_va
15362        int
15363        guestfs_tune2fs_va (guestfs_h *g,
15364                            const char *device,
15365                            va_list args);
15366
15367       This is the "va_list variant" of "guestfs_tune2fs".
15368
15369       See "CALLS WITH OPTIONAL ARGUMENTS".
15370
15371   guestfs_tune2fs_argv
15372        int
15373        guestfs_tune2fs_argv (guestfs_h *g,
15374                              const char *device,
15375                              const struct guestfs_tune2fs_argv *optargs);
15376
15377       This is the "argv variant" of "guestfs_tune2fs".
15378
15379       See "CALLS WITH OPTIONAL ARGUMENTS".
15380
15381   guestfs_tune2fs_l
15382        char **
15383        guestfs_tune2fs_l (guestfs_h *g,
15384                           const char *device);
15385
15386       This returns the contents of the ext2, ext3 or ext4 filesystem
15387       superblock on "device".
15388
15389       It is the same as running "tune2fs -l device".  See tune2fs(8) manpage
15390       for more details.  The list of fields returned isn't clearly defined,
15391       and depends on both the version of "tune2fs" that libguestfs was built
15392       against, and the filesystem itself.
15393
15394       This function returns a NULL-terminated array of strings, or NULL if
15395       there was an error.  The array of strings will always have length
15396       "2n+1", where "n" keys and values alternate, followed by the trailing
15397       NULL entry.  The caller must free the strings and the array after use.
15398
15399       (Added in 1.9.2)
15400
15401   guestfs_txz_in
15402        int
15403        guestfs_txz_in (guestfs_h *g,
15404                        const char *tarball,
15405                        const char *directory);
15406
15407       This function is deprecated.  In new code, use the "guestfs_tar_in"
15408       call instead.
15409
15410       Deprecated functions will not be removed from the API, but the fact
15411       that they are deprecated indicates that there are problems with correct
15412       use of these functions.
15413
15414       This command uploads and unpacks local file "tarball" (an xz compressed
15415       tar file) into directory.
15416
15417       This function returns 0 on success or -1 on error.
15418
15419       This function depends on the feature "xz".  See also
15420       "guestfs_feature_available".
15421
15422       (Added in 1.3.2)
15423
15424   guestfs_txz_out
15425        int
15426        guestfs_txz_out (guestfs_h *g,
15427                         const char *directory,
15428                         const char *tarball);
15429
15430       This function is deprecated.  In new code, use the "guestfs_tar_out"
15431       call instead.
15432
15433       Deprecated functions will not be removed from the API, but the fact
15434       that they are deprecated indicates that there are problems with correct
15435       use of these functions.
15436
15437       This command packs the contents of directory and downloads it to local
15438       file "tarball" (as an xz compressed tar archive).
15439
15440       This function returns 0 on success or -1 on error.
15441
15442       This function depends on the feature "xz".  See also
15443       "guestfs_feature_available".
15444
15445       (Added in 1.3.2)
15446
15447   guestfs_umask
15448        int
15449        guestfs_umask (guestfs_h *g,
15450                       int mask);
15451
15452       This function sets the mask used for creating new files and device
15453       nodes to "mask & 0777".
15454
15455       Typical umask values would be 022 which creates new files with
15456       permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15457       new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15458
15459       The default umask is 022.  This is important because it means that
15460       directories and device nodes will be created with 0644 or 0755 mode
15461       even if you specify 0777.
15462
15463       See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15464       "guestfs_mkdir".
15465
15466       This call returns the previous umask.
15467
15468       On error this function returns -1.
15469
15470       (Added in 1.0.55)
15471
15472   guestfs_umount
15473        int
15474        guestfs_umount (guestfs_h *g,
15475                        const char *pathordevice);
15476
15477       This function is provided for backwards compatibility with earlier
15478       versions of libguestfs.  It simply calls "guestfs_umount_opts" with no
15479       optional arguments.
15480
15481       (Added in 0.8)
15482
15483   guestfs_umount_opts
15484        int
15485        guestfs_umount_opts (guestfs_h *g,
15486                             const char *pathordevice,
15487                             ...);
15488
15489       You may supply a list of optional arguments to this call.  Use zero or
15490       more of the following pairs of parameters, and terminate the list with
15491       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
15492
15493        GUESTFS_UMOUNT_OPTS_FORCE, int force,
15494        GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15495
15496       This unmounts the given filesystem.  The filesystem may be specified
15497       either by its mountpoint (path) or the device which contains the
15498       filesystem.
15499
15500       This function returns 0 on success or -1 on error.
15501
15502       (Added in 0.8)
15503
15504   guestfs_umount_opts_va
15505        int
15506        guestfs_umount_opts_va (guestfs_h *g,
15507                                const char *pathordevice,
15508                                va_list args);
15509
15510       This is the "va_list variant" of "guestfs_umount_opts".
15511
15512       See "CALLS WITH OPTIONAL ARGUMENTS".
15513
15514   guestfs_umount_opts_argv
15515        int
15516        guestfs_umount_opts_argv (guestfs_h *g,
15517                                  const char *pathordevice,
15518                                  const struct guestfs_umount_opts_argv *optargs);
15519
15520       This is the "argv variant" of "guestfs_umount_opts".
15521
15522       See "CALLS WITH OPTIONAL ARGUMENTS".
15523
15524   guestfs_umount_all
15525        int
15526        guestfs_umount_all (guestfs_h *g);
15527
15528       This unmounts all mounted filesystems.
15529
15530       Some internal mounts are not unmounted by this call.
15531
15532       This function returns 0 on success or -1 on error.
15533
15534       (Added in 0.8)
15535
15536   guestfs_umount_local
15537        int
15538        guestfs_umount_local (guestfs_h *g,
15539                              ...);
15540
15541       You may supply a list of optional arguments to this call.  Use zero or
15542       more of the following pairs of parameters, and terminate the list with
15543       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
15544
15545        GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15546
15547       If libguestfs is exporting the filesystem on a local mountpoint, then
15548       this unmounts it.
15549
15550       See "MOUNT LOCAL" for full documentation.
15551
15552       This function returns 0 on success or -1 on error.
15553
15554       (Added in 1.17.22)
15555
15556   guestfs_umount_local_va
15557        int
15558        guestfs_umount_local_va (guestfs_h *g,
15559                                 va_list args);
15560
15561       This is the "va_list variant" of "guestfs_umount_local".
15562
15563       See "CALLS WITH OPTIONAL ARGUMENTS".
15564
15565   guestfs_umount_local_argv
15566        int
15567        guestfs_umount_local_argv (guestfs_h *g,
15568                                   const struct guestfs_umount_local_argv *optargs);
15569
15570       This is the "argv variant" of "guestfs_umount_local".
15571
15572       See "CALLS WITH OPTIONAL ARGUMENTS".
15573
15574   guestfs_upload
15575        int
15576        guestfs_upload (guestfs_h *g,
15577                        const char *filename,
15578                        const char *remotefilename);
15579
15580       Upload local file filename to remotefilename on the filesystem.
15581
15582       filename can also be a named pipe.
15583
15584       See also "guestfs_download".
15585
15586       This function returns 0 on success or -1 on error.
15587
15588       This long-running command can generate progress notification messages
15589       so that the caller can display a progress bar or indicator.  To receive
15590       these messages, the caller must register a progress event callback.
15591       See "GUESTFS_EVENT_PROGRESS".
15592
15593       (Added in 1.0.2)
15594
15595   guestfs_upload_offset
15596        int
15597        guestfs_upload_offset (guestfs_h *g,
15598                               const char *filename,
15599                               const char *remotefilename,
15600                               int64_t offset);
15601
15602       Upload local file filename to remotefilename on the filesystem.
15603
15604       remotefilename is overwritten starting at the byte "offset" specified.
15605       The intention is to overwrite parts of existing files or devices,
15606       although if a non-existent file is specified then it is created with a
15607       "hole" before "offset".  The size of the data written is implicit in
15608       the size of the source filename.
15609
15610       Note that there is no limit on the amount of data that can be uploaded
15611       with this call, unlike with "guestfs_pwrite", and this call always
15612       writes the full amount unless an error occurs.
15613
15614       See also "guestfs_upload", "guestfs_pwrite".
15615
15616       This function returns 0 on success or -1 on error.
15617
15618       This long-running command can generate progress notification messages
15619       so that the caller can display a progress bar or indicator.  To receive
15620       these messages, the caller must register a progress event callback.
15621       See "GUESTFS_EVENT_PROGRESS".
15622
15623       (Added in 1.5.17)
15624
15625   guestfs_user_cancel
15626        int
15627        guestfs_user_cancel (guestfs_h *g);
15628
15629       This function cancels the current upload or download operation.
15630
15631       Unlike most other libguestfs calls, this function is signal safe and
15632       thread safe.  You can call it from a signal handler or from another
15633       thread, without needing to do any locking.
15634
15635       The transfer that was in progress (if there is one) will stop shortly
15636       afterwards, and will return an error.  The errno (see
15637       "guestfs_last_errno") is set to "EINTR", so you can test for this to
15638       find out if the operation was cancelled or failed because of another
15639       error.
15640
15641       No cleanup is performed: for example, if a file was being uploaded then
15642       after cancellation there may be a partially uploaded file.  It is the
15643       caller’s responsibility to clean up if necessary.
15644
15645       There are two common places that you might call "guestfs_user_cancel":
15646
15647       In an interactive text-based program, you might call it from a "SIGINT"
15648       signal handler so that pressing "^C" cancels the current operation.
15649       (You also need to call "guestfs_set_pgroup" so that child processes
15650       don't receive the "^C" signal).
15651
15652       In a graphical program, when the main thread is displaying a progress
15653       bar with a cancel button, wire up the cancel button to call this
15654       function.
15655
15656       This function returns 0 on success or -1 on error.
15657
15658       (Added in 1.11.18)
15659
15660   guestfs_utimens
15661        int
15662        guestfs_utimens (guestfs_h *g,
15663                         const char *path,
15664                         int64_t atsecs,
15665                         int64_t atnsecs,
15666                         int64_t mtsecs,
15667                         int64_t mtnsecs);
15668
15669       This command sets the timestamps of a file with nanosecond precision.
15670
15671       "atsecs", "atnsecs" are the last access time (atime) in secs and
15672       nanoseconds from the epoch.
15673
15674       "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
15675       nanoseconds from the epoch.
15676
15677       If the *nsecs field contains the special value "-1" then the
15678       corresponding timestamp is set to the current time.  (The *secs field
15679       is ignored in this case).
15680
15681       If the *nsecs field contains the special value "-2" then the
15682       corresponding timestamp is left unchanged.  (The *secs field is ignored
15683       in this case).
15684
15685       This function returns 0 on success or -1 on error.
15686
15687       (Added in 1.0.77)
15688
15689   guestfs_utsname
15690        struct guestfs_utsname *
15691        guestfs_utsname (guestfs_h *g);
15692
15693       This returns the kernel version of the appliance, where this is
15694       available.  This information is only useful for debugging.  Nothing in
15695       the returned structure is defined by the API.
15696
15697       This function returns a "struct guestfs_utsname *", or NULL if there
15698       was an error.  The caller must call "guestfs_free_utsname" after use.
15699
15700       (Added in 1.19.27)
15701
15702   guestfs_version
15703        struct guestfs_version *
15704        guestfs_version (guestfs_h *g);
15705
15706       Return the libguestfs version number that the program is linked
15707       against.
15708
15709       Note that because of dynamic linking this is not necessarily the
15710       version of libguestfs that you compiled against.  You can compile the
15711       program, and then at runtime dynamically link against a completely
15712       different libguestfs.so library.
15713
15714       This call was added in version 1.0.58.  In previous versions of
15715       libguestfs there was no way to get the version number.  From C code you
15716       can use dynamic linker functions to find out if this symbol exists (if
15717       it doesn't, then it’s an earlier version).
15718
15719       The call returns a structure with four elements.  The first three
15720       ("major", "minor" and "release") are numbers and correspond to the
15721       usual version triplet.  The fourth element ("extra") is a string and is
15722       normally empty, but may be used for distro-specific information.
15723
15724       To construct the original version string:
15725       "$major.$minor.$release$extra"
15726
15727       See also: "LIBGUESTFS VERSION NUMBERS".
15728
15729       Note: Don't use this call to test for availability of features.  In
15730       enterprise distributions we backport features from later versions into
15731       earlier versions, making this an unreliable way to test for features.
15732       Use "guestfs_available" or "guestfs_feature_available" instead.
15733
15734       This function returns a "struct guestfs_version *", or NULL if there
15735       was an error.  The caller must call "guestfs_free_version" after use.
15736
15737       (Added in 1.0.58)
15738
15739   guestfs_vfs_label
15740        char *
15741        guestfs_vfs_label (guestfs_h *g,
15742                           const char *mountable);
15743
15744       This returns the label of the filesystem on "mountable".
15745
15746       If the filesystem is unlabeled, this returns the empty string.
15747
15748       To find a filesystem from the label, use "guestfs_findfs_label".
15749
15750       This function returns a string, or NULL on error.  The caller must free
15751       the returned string after use.
15752
15753       (Added in 1.3.18)
15754
15755   guestfs_vfs_minimum_size
15756        int64_t
15757        guestfs_vfs_minimum_size (guestfs_h *g,
15758                                  const char *mountable);
15759
15760       Get the minimum size of filesystem in bytes.  This is the minimum
15761       possible size for filesystem shrinking.
15762
15763       If getting minimum size of specified filesystem is not supported, this
15764       will fail and set errno as ENOTSUP.
15765
15766       See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15767
15768       On error this function returns -1.
15769
15770       (Added in 1.31.18)
15771
15772   guestfs_vfs_type
15773        char *
15774        guestfs_vfs_type (guestfs_h *g,
15775                          const char *mountable);
15776
15777       This command gets the filesystem type corresponding to the filesystem
15778       on "mountable".
15779
15780       For most filesystems, the result is the name of the Linux VFS module
15781       which would be used to mount this filesystem if you mounted it without
15782       specifying the filesystem type.  For example a string such as "ext3" or
15783       "ntfs".
15784
15785       This function returns a string, or NULL on error.  The caller must free
15786       the returned string after use.
15787
15788       (Added in 1.0.75)
15789
15790   guestfs_vfs_uuid
15791        char *
15792        guestfs_vfs_uuid (guestfs_h *g,
15793                          const char *mountable);
15794
15795       This returns the filesystem UUID of the filesystem on "mountable".
15796
15797       If the filesystem does not have a UUID, this returns the empty string.
15798
15799       To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15800
15801       This function returns a string, or NULL on error.  The caller must free
15802       the returned string after use.
15803
15804       (Added in 1.3.18)
15805
15806   guestfs_vg_activate
15807        int
15808        guestfs_vg_activate (guestfs_h *g,
15809                             int activate,
15810                             char *const *volgroups);
15811
15812       This command activates or (if "activate" is false) deactivates all
15813       logical volumes in the listed volume groups "volgroups".
15814
15815       This command is the same as running "vgchange -a y|n volgroups..."
15816
15817       Note that if "volgroups" is an empty list then all volume groups are
15818       activated or deactivated.
15819
15820       This function returns 0 on success or -1 on error.
15821
15822       This function depends on the feature "lvm2".  See also
15823       "guestfs_feature_available".
15824
15825       (Added in 1.0.26)
15826
15827   guestfs_vg_activate_all
15828        int
15829        guestfs_vg_activate_all (guestfs_h *g,
15830                                 int activate);
15831
15832       This command activates or (if "activate" is false) deactivates all
15833       logical volumes in all volume groups.
15834
15835       This command is the same as running "vgchange -a y|n"
15836
15837       This function returns 0 on success or -1 on error.
15838
15839       This function depends on the feature "lvm2".  See also
15840       "guestfs_feature_available".
15841
15842       (Added in 1.0.26)
15843
15844   guestfs_vgchange_uuid
15845        int
15846        guestfs_vgchange_uuid (guestfs_h *g,
15847                               const char *vg);
15848
15849       Generate a new random UUID for the volume group "vg".
15850
15851       This function returns 0 on success or -1 on error.
15852
15853       This function depends on the feature "lvm2".  See also
15854       "guestfs_feature_available".
15855
15856       (Added in 1.19.26)
15857
15858   guestfs_vgchange_uuid_all
15859        int
15860        guestfs_vgchange_uuid_all (guestfs_h *g);
15861
15862       Generate new random UUIDs for all volume groups.
15863
15864       This function returns 0 on success or -1 on error.
15865
15866       This function depends on the feature "lvm2".  See also
15867       "guestfs_feature_available".
15868
15869       (Added in 1.19.26)
15870
15871   guestfs_vgcreate
15872        int
15873        guestfs_vgcreate (guestfs_h *g,
15874                          const char *volgroup,
15875                          char *const *physvols);
15876
15877       This creates an LVM volume group called "volgroup" from the non-empty
15878       list of physical volumes "physvols".
15879
15880       This function returns 0 on success or -1 on error.
15881
15882       This function depends on the feature "lvm2".  See also
15883       "guestfs_feature_available".
15884
15885       (Added in 0.8)
15886
15887   guestfs_vglvuuids
15888        char **
15889        guestfs_vglvuuids (guestfs_h *g,
15890                           const char *vgname);
15891
15892       Given a VG called "vgname", this returns the UUIDs of all the logical
15893       volumes created in this volume group.
15894
15895       You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15896       associate logical volumes and volume groups.
15897
15898       See also "guestfs_vgpvuuids".
15899
15900       This function returns a NULL-terminated array of strings (like
15901       environ(3)), or NULL if there was an error.  The caller must free the
15902       strings and the array after use.
15903
15904       (Added in 1.0.87)
15905
15906   guestfs_vgmeta
15907        char *
15908        guestfs_vgmeta (guestfs_h *g,
15909                        const char *vgname,
15910                        size_t *size_r);
15911
15912       "vgname" is an LVM volume group.  This command examines the volume
15913       group and returns its metadata.
15914
15915       Note that the metadata is an internal structure used by LVM, subject to
15916       change at any time, and is provided for information only.
15917
15918       This function returns a buffer, or NULL on error.  The size of the
15919       returned buffer is written to *size_r.  The caller must free the
15920       returned buffer after use.
15921
15922       This function depends on the feature "lvm2".  See also
15923       "guestfs_feature_available".
15924
15925       (Added in 1.17.20)
15926
15927   guestfs_vgpvuuids
15928        char **
15929        guestfs_vgpvuuids (guestfs_h *g,
15930                           const char *vgname);
15931
15932       Given a VG called "vgname", this returns the UUIDs of all the physical
15933       volumes that this volume group resides on.
15934
15935       You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15936       associate physical volumes and volume groups.
15937
15938       See also "guestfs_vglvuuids".
15939
15940       This function returns a NULL-terminated array of strings (like
15941       environ(3)), or NULL if there was an error.  The caller must free the
15942       strings and the array after use.
15943
15944       (Added in 1.0.87)
15945
15946   guestfs_vgremove
15947        int
15948        guestfs_vgremove (guestfs_h *g,
15949                          const char *vgname);
15950
15951       Remove an LVM volume group "vgname", (for example "VG").
15952
15953       This also forcibly removes all logical volumes in the volume group (if
15954       any).
15955
15956       This function returns 0 on success or -1 on error.
15957
15958       This function depends on the feature "lvm2".  See also
15959       "guestfs_feature_available".
15960
15961       (Added in 1.0.13)
15962
15963   guestfs_vgrename
15964        int
15965        guestfs_vgrename (guestfs_h *g,
15966                          const char *volgroup,
15967                          const char *newvolgroup);
15968
15969       Rename a volume group "volgroup" with the new name "newvolgroup".
15970
15971       This function returns 0 on success or -1 on error.
15972
15973       (Added in 1.0.83)
15974
15975   guestfs_vgs
15976        char **
15977        guestfs_vgs (guestfs_h *g);
15978
15979       List all the volumes groups detected.  This is the equivalent of the
15980       vgs(8) command.
15981
15982       This returns a list of just the volume group names that were detected
15983       (eg. "VolGroup00").
15984
15985       See also "guestfs_vgs_full".
15986
15987       This function returns a NULL-terminated array of strings (like
15988       environ(3)), or NULL if there was an error.  The caller must free the
15989       strings and the array after use.
15990
15991       This function depends on the feature "lvm2".  See also
15992       "guestfs_feature_available".
15993
15994       (Added in 0.4)
15995
15996   guestfs_vgs_full
15997        struct guestfs_lvm_vg_list *
15998        guestfs_vgs_full (guestfs_h *g);
15999
16000       List all the volumes groups detected.  This is the equivalent of the
16001       vgs(8) command.  The "full" version includes all fields.
16002
16003       This function returns a "struct guestfs_lvm_vg_list *", or NULL if
16004       there was an error.  The caller must call "guestfs_free_lvm_vg_list"
16005       after use.
16006
16007       This function depends on the feature "lvm2".  See also
16008       "guestfs_feature_available".
16009
16010       (Added in 0.4)
16011
16012   guestfs_vgscan
16013        int
16014        guestfs_vgscan (guestfs_h *g);
16015
16016       This function is deprecated.  In new code, use the "guestfs_lvm_scan"
16017       call instead.
16018
16019       Deprecated functions will not be removed from the API, but the fact
16020       that they are deprecated indicates that there are problems with correct
16021       use of these functions.
16022
16023       This rescans all block devices and rebuilds the list of LVM physical
16024       volumes, volume groups and logical volumes.
16025
16026       This function returns 0 on success or -1 on error.
16027
16028       (Added in 1.3.2)
16029
16030   guestfs_vguuid
16031        char *
16032        guestfs_vguuid (guestfs_h *g,
16033                        const char *vgname);
16034
16035       This command returns the UUID of the LVM VG named "vgname".
16036
16037       This function returns a string, or NULL on error.  The caller must free
16038       the returned string after use.
16039
16040       (Added in 1.0.87)
16041
16042   guestfs_wait_ready
16043        int
16044        guestfs_wait_ready (guestfs_h *g);
16045
16046       This function is deprecated.  There is no replacement.  Consult the API
16047       documentation in guestfs(3) for further information.
16048
16049       Deprecated functions will not be removed from the API, but the fact
16050       that they are deprecated indicates that there are problems with correct
16051       use of these functions.
16052
16053       This function is a no op.
16054
16055       In versions of the API < 1.0.71 you had to call this function just
16056       after calling "guestfs_launch" to wait for the launch to complete.
16057       However this is no longer necessary because "guestfs_launch" now does
16058       the waiting.
16059
16060       If you see any calls to this function in code then you can just remove
16061       them, unless you want to retain compatibility with older versions of
16062       the API.
16063
16064       This function returns 0 on success or -1 on error.
16065
16066       (Added in 0.3)
16067
16068   guestfs_wc_c
16069        int
16070        guestfs_wc_c (guestfs_h *g,
16071                      const char *path);
16072
16073       This command counts the characters in a file, using the "wc -c"
16074       external command.
16075
16076       On error this function returns -1.
16077
16078       (Added in 1.0.54)
16079
16080   guestfs_wc_l
16081        int
16082        guestfs_wc_l (guestfs_h *g,
16083                      const char *path);
16084
16085       This command counts the lines in a file, using the "wc -l" external
16086       command.
16087
16088       On error this function returns -1.
16089
16090       (Added in 1.0.54)
16091
16092   guestfs_wc_w
16093        int
16094        guestfs_wc_w (guestfs_h *g,
16095                      const char *path);
16096
16097       This command counts the words in a file, using the "wc -w" external
16098       command.
16099
16100       On error this function returns -1.
16101
16102       (Added in 1.0.54)
16103
16104   guestfs_wipefs
16105        int
16106        guestfs_wipefs (guestfs_h *g,
16107                        const char *device);
16108
16109       This command erases filesystem or RAID signatures from the specified
16110       "device" to make the filesystem invisible to libblkid.
16111
16112       This does not erase the filesystem itself nor any other data from the
16113       "device".
16114
16115       Compare with "guestfs_zero" which zeroes the first few blocks of a
16116       device.
16117
16118       This function returns 0 on success or -1 on error.
16119
16120       This function depends on the feature "wipefs".  See also
16121       "guestfs_feature_available".
16122
16123       (Added in 1.17.6)
16124
16125   guestfs_write
16126        int
16127        guestfs_write (guestfs_h *g,
16128                       const char *path,
16129                       const char *content,
16130                       size_t content_size);
16131
16132       This call creates a file called "path".  The content of the file is the
16133       string "content" (which can contain any 8 bit data).
16134
16135       See also "guestfs_write_append".
16136
16137       This function returns 0 on success or -1 on error.
16138
16139       (Added in 1.3.14)
16140
16141   guestfs_write_append
16142        int
16143        guestfs_write_append (guestfs_h *g,
16144                              const char *path,
16145                              const char *content,
16146                              size_t content_size);
16147
16148       This call appends "content" to the end of file "path".  If "path" does
16149       not exist, then a new file is created.
16150
16151       See also "guestfs_write".
16152
16153       This function returns 0 on success or -1 on error.
16154
16155       (Added in 1.11.18)
16156
16157   guestfs_write_file
16158        int
16159        guestfs_write_file (guestfs_h *g,
16160                            const char *path,
16161                            const char *content,
16162                            int size);
16163
16164       This function is deprecated.  In new code, use the "guestfs_write" call
16165       instead.
16166
16167       Deprecated functions will not be removed from the API, but the fact
16168       that they are deprecated indicates that there are problems with correct
16169       use of these functions.
16170
16171       This call creates a file called "path".  The contents of the file is
16172       the string "content" (which can contain any 8 bit data), with length
16173       "size".
16174
16175       As a special case, if "size" is 0 then the length is calculated using
16176       "strlen" (so in this case the content cannot contain embedded ASCII
16177       NULs).
16178
16179       NB. Owing to a bug, writing content containing ASCII NUL characters
16180       does not work, even if the length is specified.
16181
16182       This function returns 0 on success or -1 on error.
16183
16184       Because of the message protocol, there is a transfer limit of somewhere
16185       between 2MB and 4MB.  See "PROTOCOL LIMITS".
16186
16187       (Added in 0.8)
16188
16189   guestfs_xfs_admin
16190        int
16191        guestfs_xfs_admin (guestfs_h *g,
16192                           const char *device,
16193                           ...);
16194
16195       You may supply a list of optional arguments to this call.  Use zero or
16196       more of the following pairs of parameters, and terminate the list with
16197       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
16198
16199        GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16200        GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16201        GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16202        GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16203        GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16204        GUESTFS_XFS_ADMIN_LABEL, const char *label,
16205        GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16206
16207       Change the parameters of the XFS filesystem on "device".
16208
16209       Devices that are mounted cannot be modified.  Administrators must
16210       unmount filesystems before this call can modify parameters.
16211
16212       Some of the parameters of a mounted filesystem can be examined and
16213       modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16214
16215       This function returns 0 on success or -1 on error.
16216
16217       This function depends on the feature "xfs".  See also
16218       "guestfs_feature_available".
16219
16220       (Added in 1.19.33)
16221
16222   guestfs_xfs_admin_va
16223        int
16224        guestfs_xfs_admin_va (guestfs_h *g,
16225                              const char *device,
16226                              va_list args);
16227
16228       This is the "va_list variant" of "guestfs_xfs_admin".
16229
16230       See "CALLS WITH OPTIONAL ARGUMENTS".
16231
16232   guestfs_xfs_admin_argv
16233        int
16234        guestfs_xfs_admin_argv (guestfs_h *g,
16235                                const char *device,
16236                                const struct guestfs_xfs_admin_argv *optargs);
16237
16238       This is the "argv variant" of "guestfs_xfs_admin".
16239
16240       See "CALLS WITH OPTIONAL ARGUMENTS".
16241
16242   guestfs_xfs_growfs
16243        int
16244        guestfs_xfs_growfs (guestfs_h *g,
16245                            const char *path,
16246                            ...);
16247
16248       You may supply a list of optional arguments to this call.  Use zero or
16249       more of the following pairs of parameters, and terminate the list with
16250       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
16251
16252        GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16253        GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16254        GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16255        GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16256        GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16257        GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16258        GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16259        GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16260
16261       Grow the XFS filesystem mounted at "path".
16262
16263       The returned struct contains geometry information.  Missing fields are
16264       returned as "-1" (for numeric fields) or empty string.
16265
16266       This function returns 0 on success or -1 on error.
16267
16268       This function depends on the feature "xfs".  See also
16269       "guestfs_feature_available".
16270
16271       (Added in 1.19.28)
16272
16273   guestfs_xfs_growfs_va
16274        int
16275        guestfs_xfs_growfs_va (guestfs_h *g,
16276                               const char *path,
16277                               va_list args);
16278
16279       This is the "va_list variant" of "guestfs_xfs_growfs".
16280
16281       See "CALLS WITH OPTIONAL ARGUMENTS".
16282
16283   guestfs_xfs_growfs_argv
16284        int
16285        guestfs_xfs_growfs_argv (guestfs_h *g,
16286                                 const char *path,
16287                                 const struct guestfs_xfs_growfs_argv *optargs);
16288
16289       This is the "argv variant" of "guestfs_xfs_growfs".
16290
16291       See "CALLS WITH OPTIONAL ARGUMENTS".
16292
16293   guestfs_xfs_info
16294        struct guestfs_xfsinfo *
16295        guestfs_xfs_info (guestfs_h *g,
16296                          const char *pathordevice);
16297
16298       "pathordevice" is a mounted XFS filesystem or a device containing an
16299       XFS filesystem.  This command returns the geometry of the filesystem.
16300
16301       The returned struct contains geometry information.  Missing fields are
16302       returned as "-1" (for numeric fields) or empty string.
16303
16304       This function returns a "struct guestfs_xfsinfo *", or NULL if there
16305       was an error.  The caller must call "guestfs_free_xfsinfo" after use.
16306
16307       This function depends on the feature "xfs".  See also
16308       "guestfs_feature_available".
16309
16310       (Added in 1.19.21)
16311
16312   guestfs_xfs_repair
16313        int
16314        guestfs_xfs_repair (guestfs_h *g,
16315                            const char *device,
16316                            ...);
16317
16318       You may supply a list of optional arguments to this call.  Use zero or
16319       more of the following pairs of parameters, and terminate the list with
16320       "-1" on its own.  See "CALLS WITH OPTIONAL ARGUMENTS".
16321
16322        GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16323        GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16324        GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16325        GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16326        GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16327        GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16328        GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16329        GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16330        GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16331        GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16332
16333       Repair corrupt or damaged XFS filesystem on "device".
16334
16335       The filesystem is specified using the "device" argument which should be
16336       the device name of the disk partition or volume containing the
16337       filesystem.  If given the name of a block device, "xfs_repair" will
16338       attempt to find the raw device associated with the specified block
16339       device and will use the raw device instead.
16340
16341       Regardless, the filesystem to be repaired must be unmounted, otherwise,
16342       the resulting filesystem may be inconsistent or corrupt.
16343
16344       The returned status indicates whether filesystem corruption was
16345       detected (returns 1) or was not detected (returns 0).
16346
16347       On error this function returns -1.
16348
16349       This function depends on the feature "xfs".  See also
16350       "guestfs_feature_available".
16351
16352       (Added in 1.19.36)
16353
16354   guestfs_xfs_repair_va
16355        int
16356        guestfs_xfs_repair_va (guestfs_h *g,
16357                               const char *device,
16358                               va_list args);
16359
16360       This is the "va_list variant" of "guestfs_xfs_repair".
16361
16362       See "CALLS WITH OPTIONAL ARGUMENTS".
16363
16364   guestfs_xfs_repair_argv
16365        int
16366        guestfs_xfs_repair_argv (guestfs_h *g,
16367                                 const char *device,
16368                                 const struct guestfs_xfs_repair_argv *optargs);
16369
16370       This is the "argv variant" of "guestfs_xfs_repair".
16371
16372       See "CALLS WITH OPTIONAL ARGUMENTS".
16373
16374   guestfs_yara_destroy
16375        int
16376        guestfs_yara_destroy (guestfs_h *g);
16377
16378       Destroy previously loaded Yara rules in order to free libguestfs
16379       resources.
16380
16381       This function returns 0 on success or -1 on error.
16382
16383       This function depends on the feature "libyara".  See also
16384       "guestfs_feature_available".
16385
16386       (Added in 1.37.13)
16387
16388   guestfs_yara_load
16389        int
16390        guestfs_yara_load (guestfs_h *g,
16391                           const char *filename);
16392
16393       Upload a set of Yara rules from local file filename.
16394
16395       Yara rules allow to categorize files based on textual or binary
16396       patterns within their content.  See "guestfs_yara_scan" to see how to
16397       scan files with the loaded rules.
16398
16399       Rules can be in binary format, as when compiled with yarac command, or
16400       in source code format. In the latter case, the rules will be first
16401       compiled and then loaded.
16402
16403       Rules in source code format cannot include external files. In such
16404       cases, it is recommended to compile them first.
16405
16406       Previously loaded rules will be destroyed.
16407
16408       This function returns 0 on success or -1 on error.
16409
16410       This long-running command can generate progress notification messages
16411       so that the caller can display a progress bar or indicator.  To receive
16412       these messages, the caller must register a progress event callback.
16413       See "GUESTFS_EVENT_PROGRESS".
16414
16415       This function depends on the feature "libyara".  See also
16416       "guestfs_feature_available".
16417
16418       (Added in 1.37.13)
16419
16420   guestfs_yara_scan
16421        struct guestfs_yara_detection_list *
16422        guestfs_yara_scan (guestfs_h *g,
16423                           const char *path);
16424
16425       Scan a file with the previously loaded Yara rules.
16426
16427       For each matching rule, a "yara_detection" structure is returned.
16428
16429       The "yara_detection" structure contains the following fields.
16430
16431       "yara_name"
16432           Path of the file matching a Yara rule.
16433
16434       "yara_rule"
16435           Identifier of the Yara rule which matched against the given file.
16436
16437       This function returns a "struct guestfs_yara_detection_list *", or NULL
16438       if there was an error.  The caller must call
16439       "guestfs_free_yara_detection_list" after use.
16440
16441       This long-running command can generate progress notification messages
16442       so that the caller can display a progress bar or indicator.  To receive
16443       these messages, the caller must register a progress event callback.
16444       See "GUESTFS_EVENT_PROGRESS".
16445
16446       This function depends on the feature "libyara".  See also
16447       "guestfs_feature_available".
16448
16449       (Added in 1.37.13)
16450
16451   guestfs_zegrep
16452        char **
16453        guestfs_zegrep (guestfs_h *g,
16454                        const char *regex,
16455                        const char *path);
16456
16457       This function is deprecated.  In new code, use the "guestfs_grep" call
16458       instead.
16459
16460       Deprecated functions will not be removed from the API, but the fact
16461       that they are deprecated indicates that there are problems with correct
16462       use of these functions.
16463
16464       This calls the external "zegrep" program and returns the matching
16465       lines.
16466
16467       This function returns a NULL-terminated array of strings (like
16468       environ(3)), or NULL if there was an error.  The caller must free the
16469       strings and the array after use.
16470
16471       Because of the message protocol, there is a transfer limit of somewhere
16472       between 2MB and 4MB.  See "PROTOCOL LIMITS".
16473
16474       (Added in 1.0.66)
16475
16476   guestfs_zegrepi
16477        char **
16478        guestfs_zegrepi (guestfs_h *g,
16479                         const char *regex,
16480                         const char *path);
16481
16482       This function is deprecated.  In new code, use the "guestfs_grep" call
16483       instead.
16484
16485       Deprecated functions will not be removed from the API, but the fact
16486       that they are deprecated indicates that there are problems with correct
16487       use of these functions.
16488
16489       This calls the external "zegrep -i" program and returns the matching
16490       lines.
16491
16492       This function returns a NULL-terminated array of strings (like
16493       environ(3)), or NULL if there was an error.  The caller must free the
16494       strings and the array after use.
16495
16496       Because of the message protocol, there is a transfer limit of somewhere
16497       between 2MB and 4MB.  See "PROTOCOL LIMITS".
16498
16499       (Added in 1.0.66)
16500
16501   guestfs_zero
16502        int
16503        guestfs_zero (guestfs_h *g,
16504                      const char *device);
16505
16506       This command writes zeroes over the first few blocks of "device".
16507
16508       How many blocks are zeroed isn't specified (but it’s not enough to
16509       securely wipe the device).  It should be sufficient to remove any
16510       partition tables, filesystem superblocks and so on.
16511
16512       If blocks are already zero, then this command avoids writing zeroes.
16513       This prevents the underlying device from becoming non-sparse or growing
16514       unnecessarily.
16515
16516       See also: "guestfs_zero_device", "guestfs_scrub_device",
16517       "guestfs_is_zero_device"
16518
16519       This function returns 0 on success or -1 on error.
16520
16521       This long-running command can generate progress notification messages
16522       so that the caller can display a progress bar or indicator.  To receive
16523       these messages, the caller must register a progress event callback.
16524       See "GUESTFS_EVENT_PROGRESS".
16525
16526       (Added in 1.0.16)
16527
16528   guestfs_zero_device
16529        int
16530        guestfs_zero_device (guestfs_h *g,
16531                             const char *device);
16532
16533       This command writes zeroes over the entire "device".  Compare with
16534       "guestfs_zero" which just zeroes the first few blocks of a device.
16535
16536       If blocks are already zero, then this command avoids writing zeroes.
16537       This prevents the underlying device from becoming non-sparse or growing
16538       unnecessarily.
16539
16540       This function returns 0 on success or -1 on error.
16541
16542       This long-running command can generate progress notification messages
16543       so that the caller can display a progress bar or indicator.  To receive
16544       these messages, the caller must register a progress event callback.
16545       See "GUESTFS_EVENT_PROGRESS".
16546
16547       (Added in 1.3.1)
16548
16549   guestfs_zero_free_space
16550        int
16551        guestfs_zero_free_space (guestfs_h *g,
16552                                 const char *directory);
16553
16554       Zero the free space in the filesystem mounted on directory.  The
16555       filesystem must be mounted read-write.
16556
16557       The filesystem contents are not affected, but any free space in the
16558       filesystem is freed.
16559
16560       Free space is not "trimmed".  You may want to call "guestfs_fstrim"
16561       either as an alternative to this, or after calling this, depending on
16562       your requirements.
16563
16564       This function returns 0 on success or -1 on error.
16565
16566       This long-running command can generate progress notification messages
16567       so that the caller can display a progress bar or indicator.  To receive
16568       these messages, the caller must register a progress event callback.
16569       See "GUESTFS_EVENT_PROGRESS".
16570
16571       (Added in 1.17.18)
16572
16573   guestfs_zerofree
16574        int
16575        guestfs_zerofree (guestfs_h *g,
16576                          const char *device);
16577
16578       This runs the zerofree program on "device".  This program claims to
16579       zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16580       it possible to compress the filesystem more effectively.
16581
16582       You should not run this program if the filesystem is mounted.
16583
16584       It is possible that using this program can damage the filesystem or
16585       data on the filesystem.
16586
16587       This function returns 0 on success or -1 on error.
16588
16589       This function depends on the feature "zerofree".  See also
16590       "guestfs_feature_available".
16591
16592       (Added in 1.0.26)
16593
16594   guestfs_zfgrep
16595        char **
16596        guestfs_zfgrep (guestfs_h *g,
16597                        const char *pattern,
16598                        const char *path);
16599
16600       This function is deprecated.  In new code, use the "guestfs_grep" call
16601       instead.
16602
16603       Deprecated functions will not be removed from the API, but the fact
16604       that they are deprecated indicates that there are problems with correct
16605       use of these functions.
16606
16607       This calls the external "zfgrep" program and returns the matching
16608       lines.
16609
16610       This function returns a NULL-terminated array of strings (like
16611       environ(3)), or NULL if there was an error.  The caller must free the
16612       strings and the array after use.
16613
16614       Because of the message protocol, there is a transfer limit of somewhere
16615       between 2MB and 4MB.  See "PROTOCOL LIMITS".
16616
16617       (Added in 1.0.66)
16618
16619   guestfs_zfgrepi
16620        char **
16621        guestfs_zfgrepi (guestfs_h *g,
16622                         const char *pattern,
16623                         const char *path);
16624
16625       This function is deprecated.  In new code, use the "guestfs_grep" call
16626       instead.
16627
16628       Deprecated functions will not be removed from the API, but the fact
16629       that they are deprecated indicates that there are problems with correct
16630       use of these functions.
16631
16632       This calls the external "zfgrep -i" program and returns the matching
16633       lines.
16634
16635       This function returns a NULL-terminated array of strings (like
16636       environ(3)), or NULL if there was an error.  The caller must free the
16637       strings and the array after use.
16638
16639       Because of the message protocol, there is a transfer limit of somewhere
16640       between 2MB and 4MB.  See "PROTOCOL LIMITS".
16641
16642       (Added in 1.0.66)
16643
16644   guestfs_zfile
16645        char *
16646        guestfs_zfile (guestfs_h *g,
16647                       const char *meth,
16648                       const char *path);
16649
16650       This function is deprecated.  In new code, use the "guestfs_file" call
16651       instead.
16652
16653       Deprecated functions will not be removed from the API, but the fact
16654       that they are deprecated indicates that there are problems with correct
16655       use of these functions.
16656
16657       This command runs file(1) after first decompressing "path" using
16658       "meth".
16659
16660       "meth" must be one of "gzip", "compress" or "bzip2".
16661
16662       Since 1.0.63, use "guestfs_file" instead which can now process
16663       compressed files.
16664
16665       This function returns a string, or NULL on error.  The caller must free
16666       the returned string after use.
16667
16668       (Added in 1.0.59)
16669
16670   guestfs_zgrep
16671        char **
16672        guestfs_zgrep (guestfs_h *g,
16673                       const char *regex,
16674                       const char *path);
16675
16676       This function is deprecated.  In new code, use the "guestfs_grep" call
16677       instead.
16678
16679       Deprecated functions will not be removed from the API, but the fact
16680       that they are deprecated indicates that there are problems with correct
16681       use of these functions.
16682
16683       This calls the external zgrep(1) program and returns the matching
16684       lines.
16685
16686       This function returns a NULL-terminated array of strings (like
16687       environ(3)), or NULL if there was an error.  The caller must free the
16688       strings and the array after use.
16689
16690       Because of the message protocol, there is a transfer limit of somewhere
16691       between 2MB and 4MB.  See "PROTOCOL LIMITS".
16692
16693       (Added in 1.0.66)
16694
16695   guestfs_zgrepi
16696        char **
16697        guestfs_zgrepi (guestfs_h *g,
16698                        const char *regex,
16699                        const char *path);
16700
16701       This function is deprecated.  In new code, use the "guestfs_grep" call
16702       instead.
16703
16704       Deprecated functions will not be removed from the API, but the fact
16705       that they are deprecated indicates that there are problems with correct
16706       use of these functions.
16707
16708       This calls the external "zgrep -i" program and returns the matching
16709       lines.
16710
16711       This function returns a NULL-terminated array of strings (like
16712       environ(3)), or NULL if there was an error.  The caller must free the
16713       strings and the array after use.
16714
16715       Because of the message protocol, there is a transfer limit of somewhere
16716       between 2MB and 4MB.  See "PROTOCOL LIMITS".
16717
16718       (Added in 1.0.66)
16719

STRUCTURES

16721   guestfs_int_bool
16722        struct guestfs_int_bool {
16723          int32_t i;
16724          int32_t b;
16725        };
16726
16727        struct guestfs_int_bool_list {
16728          uint32_t len; /* Number of elements in list. */
16729          struct guestfs_int_bool *val; /* Elements. */
16730        };
16731
16732        int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16733        int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16734
16735        struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16736        struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16737
16738        void guestfs_free_int_bool (struct guestfs_int_bool *);
16739        void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16740
16741   guestfs_lvm_pv
16742        struct guestfs_lvm_pv {
16743          char *pv_name;
16744          /* The next field is NOT nul-terminated, be careful when printing it: */
16745          char pv_uuid[32];
16746          char *pv_fmt;
16747          uint64_t pv_size;
16748          uint64_t dev_size;
16749          uint64_t pv_free;
16750          uint64_t pv_used;
16751          char *pv_attr;
16752          int64_t pv_pe_count;
16753          int64_t pv_pe_alloc_count;
16754          char *pv_tags;
16755          uint64_t pe_start;
16756          int64_t pv_mda_count;
16757          uint64_t pv_mda_free;
16758        };
16759
16760        struct guestfs_lvm_pv_list {
16761          uint32_t len; /* Number of elements in list. */
16762          struct guestfs_lvm_pv *val; /* Elements. */
16763        };
16764
16765        int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16766        int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16767
16768        struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16769        struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16770
16771        void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16772        void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16773
16774   guestfs_lvm_vg
16775        struct guestfs_lvm_vg {
16776          char *vg_name;
16777          /* The next field is NOT nul-terminated, be careful when printing it: */
16778          char vg_uuid[32];
16779          char *vg_fmt;
16780          char *vg_attr;
16781          uint64_t vg_size;
16782          uint64_t vg_free;
16783          char *vg_sysid;
16784          uint64_t vg_extent_size;
16785          int64_t vg_extent_count;
16786          int64_t vg_free_count;
16787          int64_t max_lv;
16788          int64_t max_pv;
16789          int64_t pv_count;
16790          int64_t lv_count;
16791          int64_t snap_count;
16792          int64_t vg_seqno;
16793          char *vg_tags;
16794          int64_t vg_mda_count;
16795          uint64_t vg_mda_free;
16796        };
16797
16798        struct guestfs_lvm_vg_list {
16799          uint32_t len; /* Number of elements in list. */
16800          struct guestfs_lvm_vg *val; /* Elements. */
16801        };
16802
16803        int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16804        int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16805
16806        struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16807        struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16808
16809        void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16810        void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16811
16812   guestfs_lvm_lv
16813        struct guestfs_lvm_lv {
16814          char *lv_name;
16815          /* The next field is NOT nul-terminated, be careful when printing it: */
16816          char lv_uuid[32];
16817          char *lv_attr;
16818          int64_t lv_major;
16819          int64_t lv_minor;
16820          int64_t lv_kernel_major;
16821          int64_t lv_kernel_minor;
16822          uint64_t lv_size;
16823          int64_t seg_count;
16824          char *origin;
16825          /* The next field is [0..100] or -1 meaning 'not present': */
16826          float snap_percent;
16827          /* The next field is [0..100] or -1 meaning 'not present': */
16828          float copy_percent;
16829          char *move_pv;
16830          char *lv_tags;
16831          char *mirror_log;
16832          char *modules;
16833        };
16834
16835        struct guestfs_lvm_lv_list {
16836          uint32_t len; /* Number of elements in list. */
16837          struct guestfs_lvm_lv *val; /* Elements. */
16838        };
16839
16840        int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16841        int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16842
16843        struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16844        struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16845
16846        void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16847        void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16848
16849   guestfs_stat
16850        struct guestfs_stat {
16851          int64_t dev;
16852          int64_t ino;
16853          int64_t mode;
16854          int64_t nlink;
16855          int64_t uid;
16856          int64_t gid;
16857          int64_t rdev;
16858          int64_t size;
16859          int64_t blksize;
16860          int64_t blocks;
16861          int64_t atime;
16862          int64_t mtime;
16863          int64_t ctime;
16864        };
16865
16866        struct guestfs_stat_list {
16867          uint32_t len; /* Number of elements in list. */
16868          struct guestfs_stat *val; /* Elements. */
16869        };
16870
16871        int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16872        int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16873
16874        struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16875        struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16876
16877        void guestfs_free_stat (struct guestfs_stat *);
16878        void guestfs_free_stat_list (struct guestfs_stat_list *);
16879
16880   guestfs_statns
16881        struct guestfs_statns {
16882          int64_t st_dev;
16883          int64_t st_ino;
16884          int64_t st_mode;
16885          int64_t st_nlink;
16886          int64_t st_uid;
16887          int64_t st_gid;
16888          int64_t st_rdev;
16889          int64_t st_size;
16890          int64_t st_blksize;
16891          int64_t st_blocks;
16892          int64_t st_atime_sec;
16893          int64_t st_atime_nsec;
16894          int64_t st_mtime_sec;
16895          int64_t st_mtime_nsec;
16896          int64_t st_ctime_sec;
16897          int64_t st_ctime_nsec;
16898          int64_t st_spare1;
16899          int64_t st_spare2;
16900          int64_t st_spare3;
16901          int64_t st_spare4;
16902          int64_t st_spare5;
16903          int64_t st_spare6;
16904        };
16905
16906        struct guestfs_statns_list {
16907          uint32_t len; /* Number of elements in list. */
16908          struct guestfs_statns *val; /* Elements. */
16909        };
16910
16911        int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16912        int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16913
16914        struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16915        struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16916
16917        void guestfs_free_statns (struct guestfs_statns *);
16918        void guestfs_free_statns_list (struct guestfs_statns_list *);
16919
16920   guestfs_statvfs
16921        struct guestfs_statvfs {
16922          int64_t bsize;
16923          int64_t frsize;
16924          int64_t blocks;
16925          int64_t bfree;
16926          int64_t bavail;
16927          int64_t files;
16928          int64_t ffree;
16929          int64_t favail;
16930          int64_t fsid;
16931          int64_t flag;
16932          int64_t namemax;
16933        };
16934
16935        struct guestfs_statvfs_list {
16936          uint32_t len; /* Number of elements in list. */
16937          struct guestfs_statvfs *val; /* Elements. */
16938        };
16939
16940        int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16941        int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16942
16943        struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16944        struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16945
16946        void guestfs_free_statvfs (struct guestfs_statvfs *);
16947        void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16948
16949   guestfs_dirent
16950        struct guestfs_dirent {
16951          int64_t ino;
16952          char ftyp;
16953          char *name;
16954        };
16955
16956        struct guestfs_dirent_list {
16957          uint32_t len; /* Number of elements in list. */
16958          struct guestfs_dirent *val; /* Elements. */
16959        };
16960
16961        int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16962        int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16963
16964        struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16965        struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16966
16967        void guestfs_free_dirent (struct guestfs_dirent *);
16968        void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16969
16970   guestfs_version
16971        struct guestfs_version {
16972          int64_t major;
16973          int64_t minor;
16974          int64_t release;
16975          char *extra;
16976        };
16977
16978        struct guestfs_version_list {
16979          uint32_t len; /* Number of elements in list. */
16980          struct guestfs_version *val; /* Elements. */
16981        };
16982
16983        int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16984        int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16985
16986        struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16987        struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16988
16989        void guestfs_free_version (struct guestfs_version *);
16990        void guestfs_free_version_list (struct guestfs_version_list *);
16991
16992   guestfs_xattr
16993        struct guestfs_xattr {
16994          char *attrname;
16995          /* The next two fields describe a byte array. */
16996          uint32_t attrval_len;
16997          char *attrval;
16998        };
16999
17000        struct guestfs_xattr_list {
17001          uint32_t len; /* Number of elements in list. */
17002          struct guestfs_xattr *val; /* Elements. */
17003        };
17004
17005        int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
17006        int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
17007
17008        struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
17009        struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
17010
17011        void guestfs_free_xattr (struct guestfs_xattr *);
17012        void guestfs_free_xattr_list (struct guestfs_xattr_list *);
17013
17014   guestfs_inotify_event
17015        struct guestfs_inotify_event {
17016          int64_t in_wd;
17017          uint32_t in_mask;
17018          uint32_t in_cookie;
17019          char *in_name;
17020        };
17021
17022        struct guestfs_inotify_event_list {
17023          uint32_t len; /* Number of elements in list. */
17024          struct guestfs_inotify_event *val; /* Elements. */
17025        };
17026
17027        int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
17028        int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
17029
17030        struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
17031        struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
17032
17033        void guestfs_free_inotify_event (struct guestfs_inotify_event *);
17034        void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
17035
17036   guestfs_partition
17037        struct guestfs_partition {
17038          int32_t part_num;
17039          uint64_t part_start;
17040          uint64_t part_end;
17041          uint64_t part_size;
17042        };
17043
17044        struct guestfs_partition_list {
17045          uint32_t len; /* Number of elements in list. */
17046          struct guestfs_partition *val; /* Elements. */
17047        };
17048
17049        int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
17050        int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
17051
17052        struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
17053        struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
17054
17055        void guestfs_free_partition (struct guestfs_partition *);
17056        void guestfs_free_partition_list (struct guestfs_partition_list *);
17057
17058   guestfs_application
17059        struct guestfs_application {
17060          char *app_name;
17061          char *app_display_name;
17062          int32_t app_epoch;
17063          char *app_version;
17064          char *app_release;
17065          char *app_install_path;
17066          char *app_trans_path;
17067          char *app_publisher;
17068          char *app_url;
17069          char *app_source_package;
17070          char *app_summary;
17071          char *app_description;
17072        };
17073
17074        struct guestfs_application_list {
17075          uint32_t len; /* Number of elements in list. */
17076          struct guestfs_application *val; /* Elements. */
17077        };
17078
17079        int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
17080        int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
17081
17082        struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
17083        struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
17084
17085        void guestfs_free_application (struct guestfs_application *);
17086        void guestfs_free_application_list (struct guestfs_application_list *);
17087
17088   guestfs_application2
17089        struct guestfs_application2 {
17090          char *app2_name;
17091          char *app2_display_name;
17092          int32_t app2_epoch;
17093          char *app2_version;
17094          char *app2_release;
17095          char *app2_arch;
17096          char *app2_install_path;
17097          char *app2_trans_path;
17098          char *app2_publisher;
17099          char *app2_url;
17100          char *app2_source_package;
17101          char *app2_summary;
17102          char *app2_description;
17103          char *app2_spare1;
17104          char *app2_spare2;
17105          char *app2_spare3;
17106          char *app2_spare4;
17107        };
17108
17109        struct guestfs_application2_list {
17110          uint32_t len; /* Number of elements in list. */
17111          struct guestfs_application2 *val; /* Elements. */
17112        };
17113
17114        int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
17115        int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
17116
17117        struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
17118        struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
17119
17120        void guestfs_free_application2 (struct guestfs_application2 *);
17121        void guestfs_free_application2_list (struct guestfs_application2_list *);
17122
17123   guestfs_isoinfo
17124        struct guestfs_isoinfo {
17125          char *iso_system_id;
17126          char *iso_volume_id;
17127          uint32_t iso_volume_space_size;
17128          uint32_t iso_volume_set_size;
17129          uint32_t iso_volume_sequence_number;
17130          uint32_t iso_logical_block_size;
17131          char *iso_volume_set_id;
17132          char *iso_publisher_id;
17133          char *iso_data_preparer_id;
17134          char *iso_application_id;
17135          char *iso_copyright_file_id;
17136          char *iso_abstract_file_id;
17137          char *iso_bibliographic_file_id;
17138          int64_t iso_volume_creation_t;
17139          int64_t iso_volume_modification_t;
17140          int64_t iso_volume_expiration_t;
17141          int64_t iso_volume_effective_t;
17142        };
17143
17144        struct guestfs_isoinfo_list {
17145          uint32_t len; /* Number of elements in list. */
17146          struct guestfs_isoinfo *val; /* Elements. */
17147        };
17148
17149        int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
17150        int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
17151
17152        struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
17153        struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
17154
17155        void guestfs_free_isoinfo (struct guestfs_isoinfo *);
17156        void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
17157
17158   guestfs_mdstat
17159        struct guestfs_mdstat {
17160          char *mdstat_device;
17161          int32_t mdstat_index;
17162          char *mdstat_flags;
17163        };
17164
17165        struct guestfs_mdstat_list {
17166          uint32_t len; /* Number of elements in list. */
17167          struct guestfs_mdstat *val; /* Elements. */
17168        };
17169
17170        int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
17171        int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
17172
17173        struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
17174        struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
17175
17176        void guestfs_free_mdstat (struct guestfs_mdstat *);
17177        void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
17178
17179   guestfs_btrfssubvolume
17180        struct guestfs_btrfssubvolume {
17181          uint64_t btrfssubvolume_id;
17182          uint64_t btrfssubvolume_top_level_id;
17183          char *btrfssubvolume_path;
17184        };
17185
17186        struct guestfs_btrfssubvolume_list {
17187          uint32_t len; /* Number of elements in list. */
17188          struct guestfs_btrfssubvolume *val; /* Elements. */
17189        };
17190
17191        int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17192        int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17193
17194        struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17195        struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17196
17197        void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17198        void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17199
17200   guestfs_btrfsqgroup
17201        struct guestfs_btrfsqgroup {
17202          char *btrfsqgroup_id;
17203          uint64_t btrfsqgroup_rfer;
17204          uint64_t btrfsqgroup_excl;
17205        };
17206
17207        struct guestfs_btrfsqgroup_list {
17208          uint32_t len; /* Number of elements in list. */
17209          struct guestfs_btrfsqgroup *val; /* Elements. */
17210        };
17211
17212        int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17213        int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17214
17215        struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17216        struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17217
17218        void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17219        void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17220
17221   guestfs_btrfsbalance
17222        struct guestfs_btrfsbalance {
17223          char *btrfsbalance_status;
17224          uint64_t btrfsbalance_total;
17225          uint64_t btrfsbalance_balanced;
17226          uint64_t btrfsbalance_considered;
17227          uint64_t btrfsbalance_left;
17228        };
17229
17230        struct guestfs_btrfsbalance_list {
17231          uint32_t len; /* Number of elements in list. */
17232          struct guestfs_btrfsbalance *val; /* Elements. */
17233        };
17234
17235        int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17236        int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17237
17238        struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17239        struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17240
17241        void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17242        void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17243
17244   guestfs_btrfsscrub
17245        struct guestfs_btrfsscrub {
17246          uint64_t btrfsscrub_data_extents_scrubbed;
17247          uint64_t btrfsscrub_tree_extents_scrubbed;
17248          uint64_t btrfsscrub_data_bytes_scrubbed;
17249          uint64_t btrfsscrub_tree_bytes_scrubbed;
17250          uint64_t btrfsscrub_read_errors;
17251          uint64_t btrfsscrub_csum_errors;
17252          uint64_t btrfsscrub_verify_errors;
17253          uint64_t btrfsscrub_no_csum;
17254          uint64_t btrfsscrub_csum_discards;
17255          uint64_t btrfsscrub_super_errors;
17256          uint64_t btrfsscrub_malloc_errors;
17257          uint64_t btrfsscrub_uncorrectable_errors;
17258          uint64_t btrfsscrub_unverified_errors;
17259          uint64_t btrfsscrub_corrected_errors;
17260          uint64_t btrfsscrub_last_physical;
17261        };
17262
17263        struct guestfs_btrfsscrub_list {
17264          uint32_t len; /* Number of elements in list. */
17265          struct guestfs_btrfsscrub *val; /* Elements. */
17266        };
17267
17268        int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17269        int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17270
17271        struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17272        struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17273
17274        void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17275        void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17276
17277   guestfs_xfsinfo
17278        struct guestfs_xfsinfo {
17279          char *xfs_mntpoint;
17280          uint32_t xfs_inodesize;
17281          uint32_t xfs_agcount;
17282          uint32_t xfs_agsize;
17283          uint32_t xfs_sectsize;
17284          uint32_t xfs_attr;
17285          uint32_t xfs_blocksize;
17286          uint64_t xfs_datablocks;
17287          uint32_t xfs_imaxpct;
17288          uint32_t xfs_sunit;
17289          uint32_t xfs_swidth;
17290          uint32_t xfs_dirversion;
17291          uint32_t xfs_dirblocksize;
17292          uint32_t xfs_cimode;
17293          char *xfs_logname;
17294          uint32_t xfs_logblocksize;
17295          uint32_t xfs_logblocks;
17296          uint32_t xfs_logversion;
17297          uint32_t xfs_logsectsize;
17298          uint32_t xfs_logsunit;
17299          uint32_t xfs_lazycount;
17300          char *xfs_rtname;
17301          uint32_t xfs_rtextsize;
17302          uint64_t xfs_rtblocks;
17303          uint64_t xfs_rtextents;
17304        };
17305
17306        struct guestfs_xfsinfo_list {
17307          uint32_t len; /* Number of elements in list. */
17308          struct guestfs_xfsinfo *val; /* Elements. */
17309        };
17310
17311        int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17312        int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17313
17314        struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17315        struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17316
17317        void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17318        void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17319
17320   guestfs_utsname
17321        struct guestfs_utsname {
17322          char *uts_sysname;
17323          char *uts_release;
17324          char *uts_version;
17325          char *uts_machine;
17326        };
17327
17328        struct guestfs_utsname_list {
17329          uint32_t len; /* Number of elements in list. */
17330          struct guestfs_utsname *val; /* Elements. */
17331        };
17332
17333        int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17334        int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17335
17336        struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17337        struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17338
17339        void guestfs_free_utsname (struct guestfs_utsname *);
17340        void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17341
17342   guestfs_hivex_node
17343        struct guestfs_hivex_node {
17344          int64_t hivex_node_h;
17345        };
17346
17347        struct guestfs_hivex_node_list {
17348          uint32_t len; /* Number of elements in list. */
17349          struct guestfs_hivex_node *val; /* Elements. */
17350        };
17351
17352        int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17353        int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17354
17355        struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17356        struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17357
17358        void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17359        void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17360
17361   guestfs_hivex_value
17362        struct guestfs_hivex_value {
17363          int64_t hivex_value_h;
17364        };
17365
17366        struct guestfs_hivex_value_list {
17367          uint32_t len; /* Number of elements in list. */
17368          struct guestfs_hivex_value *val; /* Elements. */
17369        };
17370
17371        int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17372        int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17373
17374        struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17375        struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17376
17377        void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17378        void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17379
17380   guestfs_internal_mountable
17381        struct guestfs_internal_mountable {
17382          int32_t im_type;
17383          char *im_device;
17384          char *im_volume;
17385        };
17386
17387        struct guestfs_internal_mountable_list {
17388          uint32_t len; /* Number of elements in list. */
17389          struct guestfs_internal_mountable *val; /* Elements. */
17390        };
17391
17392        int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17393        int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17394
17395        struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17396        struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17397
17398        void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17399        void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17400
17401   guestfs_tsk_dirent
17402        struct guestfs_tsk_dirent {
17403          uint64_t tsk_inode;
17404          char tsk_type;
17405          int64_t tsk_size;
17406          char *tsk_name;
17407          uint32_t tsk_flags;
17408          int64_t tsk_atime_sec;
17409          int64_t tsk_atime_nsec;
17410          int64_t tsk_mtime_sec;
17411          int64_t tsk_mtime_nsec;
17412          int64_t tsk_ctime_sec;
17413          int64_t tsk_ctime_nsec;
17414          int64_t tsk_crtime_sec;
17415          int64_t tsk_crtime_nsec;
17416          int64_t tsk_nlink;
17417          char *tsk_link;
17418          int64_t tsk_spare1;
17419        };
17420
17421        struct guestfs_tsk_dirent_list {
17422          uint32_t len; /* Number of elements in list. */
17423          struct guestfs_tsk_dirent *val; /* Elements. */
17424        };
17425
17426        int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17427        int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17428
17429        struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17430        struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17431
17432        void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17433        void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17434
17435   guestfs_yara_detection
17436        struct guestfs_yara_detection {
17437          char *yara_name;
17438          char *yara_rule;
17439        };
17440
17441        struct guestfs_yara_detection_list {
17442          uint32_t len; /* Number of elements in list. */
17443          struct guestfs_yara_detection *val; /* Elements. */
17444        };
17445
17446        int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17447        int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17448
17449        struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17450        struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17451
17452        void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17453        void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17454

AVAILABILITY

17456   GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17457       Using "guestfs_available" you can test availability of the following
17458       groups of functions.  This test queries the appliance to see if the
17459       appliance you are currently using supports the functionality.
17460
17461       acl The following functions: "guestfs_acl_delete_def_file"
17462           "guestfs_acl_get_file" "guestfs_acl_set_file"
17463
17464       blkdiscard
17465           The following functions: "guestfs_blkdiscard"
17466
17467       blkdiscardzeroes
17468           The following functions: "guestfs_blkdiscardzeroes"
17469
17470       btrfs
17471           The following functions: "guestfs_btrfs_balance_cancel"
17472           "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17473           "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17474           "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17475           "guestfs_btrfs_filesystem_defragment"
17476           "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17477           "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17478           "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17479           "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17480           "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17481           "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17482           "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17483           "guestfs_btrfs_rescue_chunk_recover"
17484           "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17485           "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17486           "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17487           "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17488           "guestfs_btrfs_subvolume_get_default"
17489           "guestfs_btrfs_subvolume_list"
17490           "guestfs_btrfs_subvolume_set_default"
17491           "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17492           "guestfs_btrfstune_enable_extended_inode_refs"
17493           "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17494           "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17495
17496       extlinux
17497           The following functions: "guestfs_extlinux"
17498
17499       f2fs
17500           The following functions: "guestfs_f2fs_expand"
17501
17502       fstrim
17503           The following functions: "guestfs_fstrim"
17504
17505       gdisk
17506           The following functions: "guestfs_part_expand_gpt"
17507           "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17508           "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17509           "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17510           "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17511           "guestfs_part_set_gpt_type"
17512
17513       grub
17514           The following functions: "guestfs_grub_install"
17515
17516       hivex
17517           The following functions: "guestfs_hivex_close"
17518           "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17519           "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17520           "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17521           "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17522           "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17523           "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17524           "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17525           "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17526
17527       inotify
17528           The following functions: "guestfs_inotify_add_watch"
17529           "guestfs_inotify_close" "guestfs_inotify_files"
17530           "guestfs_inotify_init" "guestfs_inotify_read"
17531           "guestfs_inotify_rm_watch"
17532
17533       journal
17534           The following functions: "guestfs_internal_journal_get"
17535           "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17536           "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17537           "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17538           "guestfs_journal_skip"
17539
17540       ldm The following functions: "guestfs_ldmtool_create_all"
17541           "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17542           "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17543           "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17544           "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17545           "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17546           "guestfs_list_ldm_volumes"
17547
17548       libtsk
17549           The following functions: "guestfs_internal_filesystem_walk"
17550           "guestfs_internal_find_inode"
17551
17552       libyara
17553           The following functions: "guestfs_internal_yara_scan"
17554           "guestfs_yara_destroy" "guestfs_yara_load"
17555
17556       linuxcaps
17557           The following functions: "guestfs_cap_get_file"
17558           "guestfs_cap_set_file"
17559
17560       linuxfsuuid
17561           The following functions: "guestfs_mke2fs_JU"
17562           "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17563           "guestfs_swapon_uuid"
17564
17565       linuxmodules
17566           The following functions: "guestfs_modprobe"
17567
17568       linuxxattrs
17569           The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17570           "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17571           "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17572           "guestfs_removexattr" "guestfs_setxattr"
17573
17574       luks
17575           The following functions: "guestfs_cryptsetup_close"
17576           "guestfs_cryptsetup_open" "guestfs_luks_add_key"
17577           "guestfs_luks_close" "guestfs_luks_format"
17578           "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17579           "guestfs_luks_open" "guestfs_luks_open_ro" "guestfs_luks_uuid"
17580
17581       lvm2
17582           The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17583           "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17584           "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17585           "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17586           "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17587           "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17588           "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17589           "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17590           "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17591           "guestfs_vgs" "guestfs_vgs_full"
17592
17593       mdadm
17594           The following functions: "guestfs_md_create" "guestfs_md_detail"
17595           "guestfs_md_stat" "guestfs_md_stop"
17596
17597       mknod
17598           The following functions: "guestfs_mkfifo" "guestfs_mknod"
17599           "guestfs_mknod_b" "guestfs_mknod_c"
17600
17601       ntfs3g
17602           The following functions: "guestfs_ntfs_3g_probe"
17603           "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17604
17605       ntfsprogs
17606           The following functions: "guestfs_ntfsresize"
17607           "guestfs_ntfsresize_size"
17608
17609       rsync
17610           The following functions: "guestfs_rsync" "guestfs_rsync_in"
17611           "guestfs_rsync_out"
17612
17613       scrub
17614           The following functions: "guestfs_scrub_device"
17615           "guestfs_scrub_file" "guestfs_scrub_freespace"
17616
17617       selinux
17618           The following functions: "guestfs_getcon" "guestfs_setcon"
17619
17620       selinuxrelabel
17621           The following functions: "guestfs_selinux_relabel"
17622
17623       sleuthkit
17624           The following functions: "guestfs_download_blocks"
17625           "guestfs_download_inode"
17626
17627       squashfs
17628           The following functions: "guestfs_mksquashfs"
17629
17630       syslinux
17631           The following functions: "guestfs_syslinux"
17632
17633       wipefs
17634           The following functions: "guestfs_wipefs"
17635
17636       xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17637           "guestfs_xfs_info" "guestfs_xfs_repair"
17638
17639       xz  The following functions: "guestfs_txz_in" "guestfs_txz_out"
17640
17641       zerofree
17642           The following functions: "guestfs_zerofree"
17643
17644   FILESYSTEM AVAILABLE
17645       The "guestfs_filesystem_available" call tests whether a filesystem type
17646       is supported by the appliance kernel.
17647
17648       This is mainly useful as a negative test.  If this returns true, it
17649       doesn't mean that a particular filesystem can be mounted, since
17650       filesystems can fail for other reasons such as it being a later version
17651       of the filesystem, or having incompatible features.
17652
17653   GUESTFISH supported COMMAND
17654       In guestfish(3) there is a handy interactive command "supported" which
17655       prints out the available groups and whether they are supported by this
17656       build of libguestfs.  Note however that you have to do "run" first.
17657
17658   SINGLE CALLS AT COMPILE TIME
17659       Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17660       function, such as:
17661
17662        #define GUESTFS_HAVE_DD 1
17663
17664       if "guestfs_dd" is available.
17665
17666       Before version 1.5.8, if you needed to test whether a single libguestfs
17667       function is available at compile time, we recommended using build tools
17668       such as autoconf or cmake.  For example in autotools you could use:
17669
17670        AC_CHECK_LIB([guestfs],[guestfs_create])
17671        AC_CHECK_FUNCS([guestfs_dd])
17672
17673       which would result in "HAVE_GUESTFS_DD" being either defined or not
17674       defined in your program.
17675
17676   SINGLE CALLS AT RUN TIME
17677       Testing at compile time doesn't guarantee that a function really exists
17678       in the library.  The reason is that you might be dynamically linked
17679       against a previous libguestfs.so (dynamic library) which doesn't have
17680       the call.  This situation unfortunately results in a segmentation
17681       fault, which is a shortcoming of the C dynamic linking system itself.
17682
17683       You can use dlopen(3) to test if a function is available at run time,
17684       as in this example program (note that you still need the compile time
17685       check as well):
17686
17687        #include <stdio.h>
17688        #include <stdlib.h>
17689        #include <unistd.h>
17690        #include <dlfcn.h>
17691        #include <guestfs.h>
17692
17693        main ()
17694        {
17695        #ifdef GUESTFS_HAVE_DD
17696          void *dl;
17697          int has_function;
17698
17699          /* Test if the function guestfs_dd is really available. */
17700          dl = dlopen (NULL, RTLD_LAZY);
17701          if (!dl) {
17702            fprintf (stderr, "dlopen: %s\n", dlerror ());
17703            exit (EXIT_FAILURE);
17704          }
17705          has_function = dlsym (dl, "guestfs_dd") != NULL;
17706          dlclose (dl);
17707
17708          if (!has_function)
17709            printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17710          else {
17711            printf ("this libguestfs.so has guestfs_dd function\n");
17712            /* Now it's safe to call
17713            guestfs_dd (g, "foo", "bar");
17714            */
17715          }
17716        #else
17717          printf ("guestfs_dd function was not found at compile time\n");
17718        #endif
17719         }
17720
17721       You may think the above is an awful lot of hassle, and it is.  There
17722       are other ways outside of the C linking system to ensure that this kind
17723       of incompatibility never arises, such as using package versioning:
17724
17725        Requires: libguestfs >= 1.0.80
17726

CALLS WITH OPTIONAL ARGUMENTS

17728       A recent feature of the API is the introduction of calls which take
17729       optional arguments.  In C these are declared 3 ways.  The main way is
17730       as a call which takes variable arguments (ie. "..."), as in this
17731       example:
17732
17733        int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17734
17735       Call this with a list of optional arguments, terminated by "-1".  So to
17736       call with no optional arguments specified:
17737
17738        guestfs_add_drive_opts (g, filename, -1);
17739
17740       With a single optional argument:
17741
17742        guestfs_add_drive_opts (g, filename,
17743                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17744                                -1);
17745
17746       With two:
17747
17748        guestfs_add_drive_opts (g, filename,
17749                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17750                                GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17751                                -1);
17752
17753       and so forth.  Don’t forget the terminating "-1" otherwise Bad Things
17754       will happen!
17755
17756   USING va_list FOR OPTIONAL ARGUMENTS
17757       The second variant has the same name with the suffix "_va", which works
17758       the same way but takes a "va_list".  See the C manual for details.  For
17759       the example function, this is declared:
17760
17761        int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17762                                       va_list args);
17763
17764   CONSTRUCTING OPTIONAL ARGUMENTS
17765       The third variant is useful where you need to construct these calls.
17766       You pass in a structure where you fill in the optional fields.  The
17767       structure has a bitmask as the first element which you must set to
17768       indicate which fields you have filled in.  For our example function the
17769       structure and call are declared:
17770
17771        struct guestfs_add_drive_opts_argv {
17772          uint64_t bitmask;
17773          int readonly;
17774          const char *format;
17775          /* ... */
17776        };
17777        int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17778                     const struct guestfs_add_drive_opts_argv *optargs);
17779
17780       You could call it like this:
17781
17782        struct guestfs_add_drive_opts_argv optargs = {
17783          .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17784                     GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17785          .readonly = 1,
17786          .format = "qcow2"
17787        };
17788
17789        guestfs_add_drive_opts_argv (g, filename, &optargs);
17790
17791       Notes:
17792
17793       •   The "_BITMASK" suffix on each option name when specifying the
17794           bitmask.
17795
17796       •   You do not need to fill in all fields of the structure.
17797
17798       •   There must be a one-to-one correspondence between fields of the
17799           structure that are filled in, and bits set in the bitmask.
17800
17801   OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17802       In other languages, optional arguments are expressed in the way that is
17803       natural for that language.  We refer you to the language-specific
17804       documentation for more details on that.
17805
17806       For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17807

EVENTS

17809   SETTING CALLBACKS TO HANDLE EVENTS
17810       Note: This section documents the generic event mechanism introduced in
17811       libguestfs 1.10, which you should use in new code if possible.  The old
17812       functions "guestfs_set_log_message_callback",
17813       "guestfs_set_subprocess_quit_callback",
17814       "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17815       "guestfs_set_progress_callback" are no longer documented in this manual
17816       page.  Because of the ABI guarantee, the old functions continue to
17817       work.
17818
17819       Handles generate events when certain things happen, such as log
17820       messages being generated, progress messages during long-running
17821       operations, or the handle being closed.  The API calls described below
17822       let you register a callback to be called when events happen.  You can
17823       register multiple callbacks (for the same, different or overlapping
17824       sets of events), and individually remove callbacks.  If callbacks are
17825       not removed, then they remain in force until the handle is closed.
17826
17827       In the current implementation, events are only generated synchronously:
17828       that means that events (and hence callbacks) can only happen while you
17829       are in the middle of making another libguestfs call.  The callback is
17830       called in the same thread.
17831
17832       Events may contain a payload, usually nothing (void), an array of 64
17833       bit unsigned integers, or a message buffer.  Payloads are discussed
17834       later on.
17835
17836   CLASSES OF EVENTS
17837       GUESTFS_EVENT_CLOSE (payload type: void)
17838           The callback function will be called while the handle is being
17839           closed (synchronously from "guestfs_close").
17840
17841           Note that libguestfs installs an atexit(3) handler to try to clean
17842           up handles that are open when the program exits.  This means that
17843           this callback might be called indirectly from exit(3), which can
17844           cause unexpected problems in higher-level languages (eg. if your
17845           HLL interpreter has already been cleaned up by the time this is
17846           called, and if your callback then jumps into some HLL function).
17847
17848           If no callback is registered: the handle is closed without any
17849           callback being invoked.
17850
17851       GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17852           The callback function will be called when the child process quits,
17853           either asynchronously or if killed by "guestfs_kill_subprocess".
17854           (This corresponds to a transition from any state to the CONFIG
17855           state).
17856
17857           If no callback is registered: the event is ignored.
17858
17859       GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17860           The callback function will be called when the child process becomes
17861           ready first time after it has been launched.  (This corresponds to
17862           a transition from LAUNCHING to the READY state).
17863
17864           If no callback is registered: the event is ignored.
17865
17866       GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17867           Some long-running operations can generate progress messages.  If
17868           this callback is registered, then it will be called each time a
17869           progress message is generated (usually two seconds after the
17870           operation started, and three times per second thereafter until it
17871           completes, although the frequency may change in future versions).
17872
17873           The callback receives in the payload four unsigned 64 bit numbers
17874           which are (in order): "proc_nr", "serial", "position", "total".
17875
17876           The units of "total" are not defined, although for some operations
17877           "total" may relate in some way to the amount of data to be
17878           transferred (eg. in bytes or megabytes), and "position" may be the
17879           portion which has been transferred.
17880
17881           The only defined and stable parts of the API are:
17882
17883           •   The callback can display to the user some type of progress bar
17884               or indicator which shows the ratio of "position":"total".
17885
17886           •   0 <= "position" <= "total"
17887
17888           •   If any progress notification is sent during a call, then a
17889               final progress notification is always sent when "position" =
17890               "total" (unless the call fails with an error).
17891
17892               This is to simplify caller code, so callers can easily set the
17893               progress indicator to "100%" at the end of the operation,
17894               without requiring special code to detect this case.
17895
17896           •   For some calls we are unable to estimate the progress of the
17897               call, but we can still generate progress messages to indicate
17898               activity.  This is known as "pulse mode", and is directly
17899               supported by certain progress bar implementations (eg.
17900               GtkProgressBar).
17901
17902               For these calls, zero or more progress messages are generated
17903               with "position = 0" and "total = 1", followed by a final
17904               message with "position = total = 1".
17905
17906               As noted above, if the call fails with an error then the final
17907               message may not be generated.
17908
17909           The callback also receives the procedure number ("proc_nr") and
17910           serial number ("serial") of the call.  These are only useful for
17911           debugging protocol issues, and the callback can normally ignore
17912           them.  The callback may want to print these numbers in error
17913           messages or debugging messages.
17914
17915           If no callback is registered: progress messages are discarded.
17916
17917       GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17918           The callback function is called whenever a log message is generated
17919           by qemu, the appliance kernel, guestfsd (daemon), or utility
17920           programs.
17921
17922           If the verbose flag ("guestfs_set_verbose") is set before launch
17923           ("guestfs_launch") then additional debug messages are generated.
17924
17925           If no callback is registered: the messages are discarded unless the
17926           verbose flag is set in which case they are sent to stderr.  You can
17927           override the printing of verbose messages to stderr by setting up a
17928           callback.
17929
17930       GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17931           The callback function is called whenever a log message is generated
17932           by the library part of libguestfs.
17933
17934           If the verbose flag ("guestfs_set_verbose") is set then additional
17935           debug messages are generated.
17936
17937           If no callback is registered: the messages are discarded unless the
17938           verbose flag is set in which case they are sent to stderr.  You can
17939           override the printing of verbose messages to stderr by setting up a
17940           callback.
17941
17942       GUESTFS_EVENT_WARNING (payload type: message buffer)
17943           The callback function is called whenever a warning message is
17944           generated by the library part of libguestfs.
17945
17946           If no callback is registered: the messages are printed to stderr.
17947           You can override the printing of warning messages to stderr by
17948           setting up a callback.
17949
17950       GUESTFS_EVENT_TRACE (payload type: message buffer)
17951           The callback function is called whenever a trace message is
17952           generated.  This only applies if the trace flag
17953           ("guestfs_set_trace") is set.
17954
17955           If no callback is registered: the messages are sent to stderr.  You
17956           can override the printing of trace messages to stderr by setting up
17957           a callback.
17958
17959       GUESTFS_EVENT_ENTER (payload type: function name)
17960           The callback function is called whenever a libguestfs function is
17961           entered.
17962
17963           The payload is a string which contains the name of the function
17964           that we are entering (not including "guestfs_" prefix).
17965
17966           Note that libguestfs functions can call themselves, so you may see
17967           many events from a single call.  A few libguestfs functions do not
17968           generate this event.
17969
17970           If no callback is registered: the event is ignored.
17971
17972       GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17973           For any API function that opens a libvirt connection, this event
17974           may be generated to indicate that libvirt demands authentication
17975           information.  See "LIBVIRT AUTHENTICATION" below.
17976
17977           If no callback is registered: "virConnectAuthPtrDefault" is used
17978           (suitable for command-line programs only).
17979
17980   EVENT API
17981       guestfs_set_event_callback
17982
17983        int guestfs_set_event_callback (guestfs_h *g,
17984                                        guestfs_event_callback cb,
17985                                        uint64_t event_bitmask,
17986                                        int flags,
17987                                        void *opaque);
17988
17989       This function registers a callback ("cb") for all event classes in the
17990       "event_bitmask".
17991
17992       For example, to register for all log message events, you could call
17993       this function with the bitmask
17994       "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17995       To register a single callback for all possible classes of events, use
17996       "GUESTFS_EVENT_ALL".
17997
17998       "flags" should always be passed as 0.
17999
18000       "opaque" is an opaque pointer which is passed to the callback.  You can
18001       use it for any purpose.
18002
18003       The return value is the event handle (an integer) which you can use to
18004       delete the callback (see below).
18005
18006       If there is an error, this function returns "-1", and sets the error in
18007       the handle in the usual way (see "guestfs_last_error" etc.)
18008
18009       Callbacks remain in effect until they are deleted, or until the handle
18010       is closed.
18011
18012       In the case where multiple callbacks are registered for a particular
18013       event class, all of the callbacks are called.  The order in which
18014       multiple callbacks are called is not defined.
18015
18016       guestfs_delete_event_callback
18017
18018        void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
18019
18020       Delete a callback that was previously registered.  "event_handle"
18021       should be the integer that was returned by a previous call to
18022       "guestfs_set_event_callback" on the same handle.
18023
18024       guestfs_event_to_string
18025
18026        char *guestfs_event_to_string (uint64_t event);
18027
18028       "event" is either a single event or a bitmask of events.  This returns
18029       a string representation (useful for debugging or printing events).
18030
18031       A single event is returned as the name in lower case, eg. "close".
18032
18033       A bitmask of several events is returned as a comma-separated list, eg.
18034       "close,progress".
18035
18036       If zero is passed, then the empty string "" is returned.
18037
18038       On success this returns a string.  On error it returns NULL and sets
18039       "errno".
18040
18041       The returned string must be freed by the caller.
18042
18043       guestfs_event_callback
18044
18045        typedef void (*guestfs_event_callback) (
18046                         guestfs_h *g,
18047                         void *opaque,
18048                         uint64_t event,
18049                         int event_handle,
18050                         int flags,
18051                         const char *buf, size_t buf_len,
18052                         const uint64_t *array, size_t array_len);
18053
18054       This is the type of the event callback function that you have to
18055       provide.
18056
18057       The basic parameters are: the handle ("g"), the opaque user pointer
18058       ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
18059       handle, and "flags" which in the current API you should ignore.
18060
18061       The remaining parameters contain the event payload (if any).  Each
18062       event may contain a payload, which usually relates to the event class,
18063       but for future proofing your code should be written to handle any
18064       payload for any event class.
18065
18066       "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
18067       there is no message buffer).  Note that this message buffer can contain
18068       arbitrary 8 bit data, including NUL bytes.
18069
18070       "array" and "array_len" is an array of 64 bit unsigned integers.  At
18071       the moment this is only used for progress messages.
18072
18073   EXAMPLE: CAPTURING LOG MESSAGES
18074       A working program demonstrating this can be found in
18075       examples/debug-logging.c in the source of libguestfs.
18076
18077       One motivation for the generic event API was to allow GUI programs to
18078       capture debug and other messages.  In libguestfs ≤ 1.8 these were sent
18079       unconditionally to "stderr".
18080
18081       Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
18082       "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
18083       "GUESTFS_EVENT_TRACE".  (Note that error messages are not events; you
18084       must capture error messages separately).
18085
18086       Programs have to set up a callback to capture the classes of events of
18087       interest:
18088
18089        int eh =
18090          guestfs_set_event_callback
18091            (g, message_callback,
18092             GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
18093             GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
18094             0, NULL) == -1)
18095        if (eh == -1) {
18096          // handle error in the usual way
18097        }
18098
18099       The callback can then direct messages to the appropriate place.  In
18100       this example, messages are directed to syslog:
18101
18102        static void
18103        message_callback (
18104                guestfs_h *g,
18105                void *opaque,
18106                uint64_t event,
18107                int event_handle,
18108                int flags,
18109                const char *buf, size_t buf_len,
18110                const uint64_t *array, size_t array_len)
18111        {
18112          const int priority = LOG_USER|LOG_INFO;
18113          if (buf_len > 0)
18114            syslog (priority, "event 0x%lx: %s", event, buf);
18115        }
18116
18117   LIBVIRT AUTHENTICATION
18118       Some libguestfs API calls can open libvirt connections.  Currently the
18119       only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
18120       backend has been selected.  Libvirt connections may require
18121       authentication, for example if they need to access a remote server or
18122       to access root services from non-root.  Libvirt authentication happens
18123       via a callback mechanism, see
18124       http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
18125
18126       You may provide libvirt authentication data by registering a callback
18127       for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
18128
18129       If no such event is registered, then libguestfs uses a libvirt function
18130       that provides command-line prompts ("virConnectAuthPtrDefault").  This
18131       is only suitable for command-line libguestfs programs.
18132
18133       To provide authentication, first call
18134       "guestfs_set_libvirt_supported_credentials" with the list of
18135       credentials your program knows how to provide.  Second, register a
18136       callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event.  The event handler
18137       will be called when libvirt is requesting authentication information.
18138
18139       In the event handler, call "guestfs_get_libvirt_requested_credentials"
18140       to get a list of the credentials that libvirt is asking for.  You then
18141       need to ask (eg. the user) for each credential, and call
18142       "guestfs_set_libvirt_requested_credential" with the answer.  Note that
18143       for each credential, additional information may be available via the
18144       calls "guestfs_get_libvirt_requested_credential_prompt",
18145       "guestfs_get_libvirt_requested_credential_challenge" or
18146       "guestfs_get_libvirt_requested_credential_defresult".
18147
18148       The example program below should make this clearer.
18149
18150       There is also a more substantial working example program supplied with
18151       the libguestfs sources, called libvirt-auth.c.
18152
18153        main ()
18154        {
18155          guestfs_h *g;
18156          char *creds[] = { "authname", "passphrase", NULL };
18157          int r, eh;
18158
18159          g = guestfs_create ();
18160          if (!g) exit (EXIT_FAILURE);
18161
18162          /* Tell libvirt what credentials the program supports. */
18163          r = guestfs_set_libvirt_supported_credentials (g, creds);
18164          if (r == -1)
18165            exit (EXIT_FAILURE);
18166
18167          /* Set up the event handler. */
18168          eh = guestfs_set_event_callback (
18169              g, do_auth,
18170              GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
18171          if (eh == -1)
18172            exit (EXIT_FAILURE);
18173
18174          /* An example of a call that may ask for credentials. */
18175          r = guestfs_add_domain (
18176              g, "dom",
18177              GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
18178              -1);
18179          if (r == -1)
18180            exit (EXIT_FAILURE);
18181
18182          exit (EXIT_SUCCESS);
18183        }
18184
18185        static void
18186        do_auth (guestfs_h *g,
18187                 void *opaque,
18188                 uint64_t event,
18189                 int event_handle,
18190                 int flags,
18191                 const char *buf, size_t buf_len,
18192                 const uint64_t *array, size_t array_len)
18193        {
18194          char **creds;
18195          size_t i;
18196          char *prompt;
18197          char *reply;
18198          size_t replylen;
18199          int r;
18200
18201          // buf will be the libvirt URI.  buf_len may be ignored.
18202          printf ("Authentication required for libvirt conn '%s'\n",
18203                  buf);
18204
18205          // Ask libguestfs what credentials libvirt is demanding.
18206          creds = guestfs_get_libvirt_requested_credentials (g);
18207          if (creds == NULL)
18208            exit (EXIT_FAILURE);
18209
18210          // Now ask the user for answers.
18211          for (i = 0; creds[i] != NULL; ++i)
18212          {
18213            if (strcmp (creds[i], "authname") == 0 ||
18214                strcmp (creds[i], "passphrase") == 0)
18215            {
18216              prompt =
18217                guestfs_get_libvirt_requested_credential_prompt (g, i);
18218              if (prompt && strcmp (prompt, "") != 0)
18219                printf ("%s: ", prompt);
18220              free (prompt);
18221
18222              // Some code here to ask for the credential.
18223              // ...
18224              // Put the reply in 'reply', length 'replylen' (bytes).
18225
18226             r = guestfs_set_libvirt_requested_credential (g, i,
18227                 reply, replylen);
18228             if (r == -1)
18229               exit (EXIT_FAILURE);
18230            }
18231
18232            free (creds[i]);
18233          }
18234
18235          free (creds);
18236        }
18237

CANCELLING LONG TRANSFERS

18239       Some operations can be cancelled by the caller while they are in
18240       progress.  Currently only operations that involve uploading or
18241       downloading data can be cancelled (technically: operations that have
18242       "FileIn" or "FileOut" parameters in the generator).
18243
18244       To cancel the transfer, call "guestfs_user_cancel".  For more
18245       information, read the description of "guestfs_user_cancel".
18246

PRIVATE DATA AREA

18248       You can attach named pieces of private data to the libguestfs handle,
18249       fetch them by name, and walk over them, for the lifetime of the handle.
18250       This is called the private data area and is only available from the C
18251       API.
18252
18253       To attach a named piece of data, use the following call:
18254
18255        void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18256
18257       "key" is the name to associate with this data, and "data" is an
18258       arbitrary pointer (which can be "NULL").  Any previous item with the
18259       same key is overwritten.
18260
18261       You can use any "key" string you want, but avoid keys beginning with an
18262       underscore character (libguestfs uses those for its own internal
18263       purposes, such as implementing language bindings).  It is recommended
18264       that you prefix the key with some unique string to avoid collisions
18265       with other users.
18266
18267       To retrieve the pointer, use:
18268
18269        void *guestfs_get_private (guestfs_h *g, const char *key);
18270
18271       This function returns "NULL" if either no data is found associated with
18272       "key", or if the user previously set the "key"’s "data" pointer to
18273       "NULL".
18274
18275       Libguestfs does not try to look at or interpret the "data" pointer in
18276       any way.  As far as libguestfs is concerned, it need not be a valid
18277       pointer at all.  In particular, libguestfs does not try to free the
18278       data when the handle is closed.  If the data must be freed, then the
18279       caller must either free it before calling "guestfs_close" or must set
18280       up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18281
18282       To walk over all entries, use these two functions:
18283
18284        void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18285
18286        void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18287
18288       "guestfs_first_private" returns the first key, pointer pair ("first"
18289       does not have any particular meaning -- keys are not returned in any
18290       defined order).  A pointer to the key is returned in *key_rtn and the
18291       corresponding data pointer is returned from the function.  "NULL" is
18292       returned if there are no keys stored in the handle.
18293
18294       "guestfs_next_private" returns the next key, pointer pair.  The return
18295       value of this function is "NULL" if there are no further entries to
18296       return.
18297
18298       Notes about walking over entries:
18299
18300       •   You must not call "guestfs_set_private" while walking over the
18301           entries.
18302
18303       •   The handle maintains an internal iterator which is reset when you
18304           call "guestfs_first_private".  This internal iterator is
18305           invalidated when you call "guestfs_set_private".
18306
18307       •   If you have set the data pointer associated with a key to "NULL",
18308           ie:
18309
18310            guestfs_set_private (g, key, NULL);
18311
18312           then that "key" is not returned when walking.
18313
18314       •   *key_rtn is only valid until the next call to
18315           "guestfs_first_private", "guestfs_next_private" or
18316           "guestfs_set_private".
18317
18318       The following example code shows how to print all keys and data
18319       pointers that are associated with the handle "g":
18320
18321        const char *key;
18322        void *data = guestfs_first_private (g, &key);
18323        while (data != NULL)
18324          {
18325            printf ("key = %s, data = %p\n", key, data);
18326            data = guestfs_next_private (g, &key);
18327          }
18328
18329       More commonly you are only interested in keys that begin with an
18330       application-specific prefix "foo_".  Modify the loop like so:
18331
18332        const char *key;
18333        void *data = guestfs_first_private (g, &key);
18334        while (data != NULL)
18335          {
18336            if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18337              printf ("key = %s, data = %p\n", key, data);
18338            data = guestfs_next_private (g, &key);
18339          }
18340
18341       If you need to modify keys while walking, then you have to jump back to
18342       the beginning of the loop.  For example, to delete all keys prefixed
18343       with "foo_":
18344
18345         const char *key;
18346         void *data;
18347        again:
18348         data = guestfs_first_private (g, &key);
18349         while (data != NULL)
18350           {
18351             if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18352               {
18353                 guestfs_set_private (g, key, NULL);
18354                 /* note that 'key' pointer is now invalid, and so is
18355                    the internal iterator */
18356                 goto again;
18357               }
18358             data = guestfs_next_private (g, &key);
18359           }
18360
18361       Note that the above loop is guaranteed to terminate because the keys
18362       are being deleted, but other manipulations of keys within the loop
18363       might not terminate unless you also maintain an indication of which
18364       keys have been visited.
18365

SYSTEMTAP

18367       The libguestfs C library can be probed using systemtap or DTrace.  This
18368       is true of any library, not just libguestfs.  However libguestfs also
18369       contains static markers to help in probing internal operations.
18370
18371       You can list all the static markers by doing:
18372
18373        stap -l 'process("/usr/lib*/libguestfs.so.0")
18374                     .provider("guestfs").mark("*")'
18375
18376       Note: These static markers are not part of the stable API and may
18377       change in future versions.
18378
18379   SYSTEMTAP SCRIPT EXAMPLE
18380       This script contains examples of displaying both the static markers and
18381       some ordinary C entry points:
18382
18383        global last;
18384
18385        function display_time () {
18386              now = gettimeofday_us ();
18387              delta = 0;
18388              if (last > 0)
18389                    delta = now - last;
18390              last = now;
18391
18392              printf ("%d (+%d):", now, delta);
18393        }
18394
18395        probe begin {
18396              last = 0;
18397              printf ("ready\n");
18398        }
18399
18400        /* Display all calls to static markers. */
18401        probe process("/usr/lib*/libguestfs.so.0")
18402                  .provider("guestfs").mark("*") ? {
18403              display_time();
18404              printf ("\t%s %s\n", $$name, $$parms);
18405        }
18406
18407        /* Display all calls to guestfs_mkfs* functions. */
18408        probe process("/usr/lib*/libguestfs.so.0")
18409                  .function("guestfs_mkfs*") ? {
18410              display_time();
18411              printf ("\t%s %s\n", probefunc(), $$parms);
18412        }
18413
18414       The script above can be saved to test.stap and run using the stap(1)
18415       program.  Note that you either have to be root, or you have to add
18416       yourself to several special stap groups.  Consult the systemtap
18417       documentation for more information.
18418
18419        # stap /tmp/test.stap
18420        ready
18421
18422       In another terminal, run a guestfish command such as this:
18423
18424        guestfish -N fs
18425
18426       In the first terminal, stap trace output similar to this is shown:
18427
18428        1318248056692655 (+0): launch_start
18429        1318248056692850 (+195):       launch_build_appliance_start
18430        1318248056818285 (+125435):    launch_build_appliance_end
18431        1318248056838059 (+19774):     launch_run_qemu
18432        1318248061071167 (+4233108):   launch_end
18433        1318248061280324 (+209157):    guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
18434

LIBGUESTFS VERSION NUMBERS

18436       Since April 2010, libguestfs has started to make separate development
18437       and stable releases, along with corresponding branches in our git
18438       repository.  These separate releases can be identified by version
18439       number:
18440
18441                        even numbers for stable: 1.2.x, 1.4.x, ...
18442              .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18443              |
18444              v
18445        1  .  3  .  5
18446        ^           ^
18447        |           |
18448        |           `-------- sub-version
18449        |
18450        `------ always '1' because we don't change the ABI
18451
18452       Thus "1.3.5" is the 5th update to the development branch "1.3".
18453
18454       As time passes we cherry pick fixes from the development branch and
18455       backport those into the stable branch, the effect being that the stable
18456       branch should get more stable and less buggy over time.  So the stable
18457       releases are ideal for people who don't need new features but would
18458       just like the software to work.
18459
18460       Our criteria for backporting changes are:
18461
18462       •   Documentation changes which don’t affect any code are backported
18463           unless the documentation refers to a future feature which is not in
18464           stable.
18465
18466       •   Bug fixes which are not controversial, fix obvious problems, and
18467           have been well tested are backported.
18468
18469       •   Simple rearrangements of code which shouldn't affect how it works
18470           get backported.  This is so that the code in the two branches
18471           doesn't get too far out of step, allowing us to backport future
18472           fixes more easily.
18473
18474       •   We don’t backport new features, new APIs, new tools etc, except in
18475           one exceptional case: the new feature is required in order to
18476           implement an important bug fix.
18477
18478       A new stable branch starts when we think the new features in
18479       development are substantial and compelling enough over the current
18480       stable branch to warrant it.  When that happens we create new stable
18481       and development versions 1.N.0 and 1.(N+1).0 [N is even].  The new dot-
18482       oh release won't necessarily be so stable at this point, but by
18483       backporting fixes from development, that branch will stabilize over
18484       time.
18485

LIMITS

18487   PROTOCOL LIMITS
18488       Internally libguestfs uses a message-based protocol to pass API calls
18489       and their responses to and from a small "appliance" (see
18490       guestfs-internals(1) for plenty more detail about this).  The maximum
18491       message size used by the protocol is slightly less than 4 MB.  For some
18492       API calls you may need to be aware of this limit.  The API calls which
18493       may be affected are individually documented, with a link back to this
18494       section of the documentation.
18495
18496       In libguestfs < 1.19.32, several calls had to encode either their
18497       entire argument list or their entire return value (or sometimes both)
18498       in a single protocol message, and this gave them an arbitrary
18499       limitation on how much data they could handle.  For example,
18500       "guestfs_cat" could only download a file if it was less than around 4
18501       MB in size.  In later versions of libguestfs, some of these limits have
18502       been removed.  The APIs which were previously limited but are now
18503       unlimited (except perhaps by available memory) are listed below.  To
18504       find out if a specific API is subject to protocol limits, check for the
18505       warning in the API documentation which links to this section, and
18506       remember to check the version of the documentation that matches the
18507       version of libguestfs you are using.
18508
18509       "guestfs_cat", "guestfs_find", "guestfs_read_file",
18510       "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18511       "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18512       "guestfs_ls".
18513
18514       See also "UPLOADING" and "DOWNLOADING" for further information about
18515       copying large amounts of data into or out of a filesystem.
18516
18517   MAXIMUM NUMBER OF DISKS
18518       In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18519       may be added by calling "guestfs_max_disks".  In earlier versions of
18520       libguestfs (ie. where this call is not available) you should assume the
18521       maximum is 25.
18522
18523       The rest of this section covers implementation details, which could
18524       change in future.
18525
18526       When using virtio-scsi disks (the default if available in qemu) the
18527       current limit is 255 disks.  When using virtio-blk (the old default)
18528       the limit is around 27 disks, but may vary according to implementation
18529       details and whether the network is enabled.
18530
18531       Virtio-scsi as used by libguestfs is configured to use one target per
18532       disk, and 256 targets are available.
18533
18534       Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18535       31 slots, but some of these are used for other purposes.
18536
18537       One virtual disk is used by libguestfs internally.
18538
18539       Before libguestfs 1.19.7, disk names had to be a single character (eg.
18540       /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18541       the limit was 25.  This has been fixed in more recent versions.
18542
18543       In libguestfs ≥ 1.20 it is possible to hot plug disks.  See
18544       "HOTPLUGGING".
18545
18546   MAXIMUM NUMBER OF PARTITIONS PER DISK
18547       Virtio limits the maximum number of partitions per disk to 15.
18548
18549       This is because it reserves 4 bits for the minor device number (thus
18550       /dev/vda, and /dev/vda1 through /dev/vda15).
18551
18552       If you attach a disk with more than 15 partitions, the extra partitions
18553       are ignored by libguestfs.
18554
18555   MAXIMUM SIZE OF A DISK
18556       Probably the limit is between 2**63-1 and 2**64-1 bytes.
18557
18558       We have tested block devices up to 1 exabyte (2**60 or
18559       1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18560       host filesystem.
18561
18562       Although libguestfs probably does not impose any limit, the underlying
18563       host storage will.  If you store disk images on a host ext4 filesystem,
18564       then the maximum size will be limited by the maximum ext4 file size
18565       (currently 16 TB).  If you store disk images as host logical volumes
18566       then you are limited by the maximum size of an LV.
18567
18568       For the hugest disk image files, we recommend using XFS on the host for
18569       storage.
18570
18571   MAXIMUM SIZE OF A PARTITION
18572       The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18573       numbers.  Assuming a 512 byte sector size, this means that MBR cannot
18574       address a partition located beyond 2 TB on the disk.
18575
18576       It is recommended that you use GPT partitions on disks which are larger
18577       than this size.  GPT uses 64 bit sector numbers and so can address
18578       partitions which are theoretically larger than the largest disk we
18579       could support.
18580
18581   MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18582       This depends on the filesystem type.  libguestfs itself does not impose
18583       any known limit.  Consult Wikipedia or the filesystem documentation to
18584       find out what these limits are.
18585
18586   MAXIMUM UPLOAD AND DOWNLOAD
18587       The API functions "guestfs_upload", "guestfs_download",
18588       "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18589       uploads and downloads.
18590
18591   INSPECTION LIMITS
18592       The inspection code has several arbitrary limits on things like the
18593       size of Windows Registry hive it will read, and the length of product
18594       name.  These are intended to stop a malicious guest from consuming
18595       arbitrary amounts of memory and disk space on the host, and should not
18596       be reached in practice.  See the source code for more information.
18597

ADVANCED MACHINE READABLE OUTPUT

18599       Some of the tools support a --machine-readable option, which is
18600       generally used to make the output more machine friendly, for easier
18601       parsing for example.  By default, this output goes to stdout.
18602
18603       When using the --machine-readable option, the progress, information,
18604       warning, and error messages are also printed in JSON format for easier
18605       log tracking.  Thus, it is highly recommended to redirect the machine-
18606       readable output to a different stream.  The format of these JSON
18607       messages is like the following (actually printed within a single line,
18608       below it is indented for readability):
18609
18610        {
18611          "message": "Finishing off",
18612          "timestamp": "2019-03-22T14:46:49.067294446+01:00",
18613          "type": "message"
18614        }
18615
18616       "type" can be: "message" for progress messages, "info" for information
18617       messages, "warning" for warning messages, and "error" for error
18618       message.  "timestamp" is the RFC 3339 timestamp of the message.
18619
18620       In addition to that, a subset of these tools support an extra string
18621       passed to the --machine-readable option: this string specifies where
18622       the machine-readable output will go.
18623
18624       The possible values are:
18625
18626       fd:fd
18627           The output goes to the specified fd, which is a file descriptor
18628           already opened for writing.
18629
18630       file:filename
18631           The output goes to the specified filename.
18632
18633       stream:stdout
18634           The output goes to stdout.  This is basically the same as the
18635           default behaviour of --machine-readable with no parameter, although
18636           stdout as output is specified explicitly.
18637
18638       stream:stderr
18639           The output goes to stderr.
18640

ENVIRONMENT VARIABLES

18642       LIBGUESTFS_APPEND
18643           Pass additional options to the guest kernel.
18644
18645       LIBGUESTFS_ATTACH_METHOD
18646           This is the old way to set "LIBGUESTFS_BACKEND".
18647
18648       LIBGUESTFS_BACKEND
18649           Choose the default way to create the appliance.  See
18650           "guestfs_set_backend" and "BACKEND".
18651
18652       LIBGUESTFS_BACKEND_SETTINGS
18653           A colon-separated list of backend-specific settings.  See
18654           "BACKEND", "BACKEND SETTINGS".
18655
18656       LIBGUESTFS_CACHEDIR
18657           The location where libguestfs will cache its appliance, when using
18658           a supermin appliance.  The appliance is cached and shared between
18659           all handles which have the same effective user ID.
18660
18661           If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used.  If
18662           "TMPDIR" is not set, then /var/tmp is used.
18663
18664           See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18665
18666       LIBGUESTFS_DEBUG
18667           Set "LIBGUESTFS_DEBUG=1" to enable verbose messages.  This has the
18668           same effect as calling "guestfs_set_verbose (g, 1)".
18669
18670       LIBGUESTFS_HV
18671           Set the default hypervisor (usually qemu) binary that libguestfs
18672           uses.  If not set, then the qemu which was found at compile time by
18673           the configure script is used.
18674
18675           See also "QEMU WRAPPERS" above.
18676
18677       LIBGUESTFS_MEMSIZE
18678           Set the memory allocated to the qemu process, in megabytes.  For
18679           example:
18680
18681            LIBGUESTFS_MEMSIZE=700
18682
18683       LIBGUESTFS_PATH
18684           Set the path that libguestfs uses to search for a supermin
18685           appliance.  See the discussion of paths in section "PATH" above.
18686
18687       LIBGUESTFS_QEMU
18688           This is the old way to set "LIBGUESTFS_HV".
18689
18690       LIBGUESTFS_TMPDIR
18691           The location where libguestfs will store temporary files used by
18692           each handle.
18693
18694           If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used.  If
18695           "TMPDIR" is not set, then /tmp is used.
18696
18697           See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18698
18699       LIBGUESTFS_TRACE
18700           Set "LIBGUESTFS_TRACE=1" to enable command traces.  This has the
18701           same effect as calling "guestfs_set_trace (g, 1)".
18702
18703       PATH
18704           Libguestfs may run some external programs, and relies on $PATH
18705           being set to a reasonable value.  If using the libvirt backend,
18706           libvirt will not work at all unless $PATH contains the path of
18707           qemu/KVM.  Note that PHP by default removes $PATH from the
18708           environment which tends to break everything.
18709
18710       SUPERMIN_KERNEL
18711       SUPERMIN_KERNEL_VERSION
18712       SUPERMIN_MODULES
18713           These three environment variables allow the kernel that libguestfs
18714           uses in the appliance to be selected.  If $SUPERMIN_KERNEL is not
18715           set, then the most recent host kernel is chosen.  For more
18716           information about kernel selection, see supermin(1).
18717
18718       TMPDIR
18719           See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18720
18721       XDG_RUNTIME_DIR
18722           This directory represents a user-specific directory for storing
18723           non-essential runtime files.
18724
18725           If it is set, then is used to store temporary sockets.  Otherwise,
18726           /tmp is used.
18727
18728           See also "get-sockdir",
18729           http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18730

SEE ALSO

18732       Examples written in C: guestfs-examples(3).
18733
18734       Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18735       guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18736       guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18737
18738       Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18739       virt-builder(1), virt-builder-repository(1), virt-cat(1),
18740       virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18741       virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18742       virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18743       virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18744       virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18745       virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18746       virt-win-reg(1).
18747
18748       Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18749       guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18750       guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18751       libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18752
18753       Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18754       sd-journal(3).
18755
18756       Website: http://libguestfs.org/
18757
18758       Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18759       disktype(1).
18760

AUTHORS

18762       Richard W.M. Jones ("rjones at redhat dot com")
18763
18765       Copyright (C) 2009-2020 Red Hat Inc.
18766

LICENSE

18768       This library is free software; you can redistribute it and/or modify it
18769       under the terms of the GNU Lesser General Public License as published
18770       by the Free Software Foundation; either version 2 of the License, or
18771       (at your option) any later version.
18772
18773       This library is distributed in the hope that it will be useful, but
18774       WITHOUT ANY WARRANTY; without even the implied warranty of
18775       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18776       Lesser General Public License for more details.
18777
18778       You should have received a copy of the GNU Lesser General Public
18779       License along with this library; if not, write to the Free Software
18780       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18781       02110-1301 USA
18782

BUGS

18784       To get a list of bugs against libguestfs, use this link:
18785       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18786
18787       To report a new bug against libguestfs, use this link:
18788       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18789
18790       When reporting a bug, please supply:
18791
18792       •   The version of libguestfs.
18793
18794       •   Where you got libguestfs (eg. which Linux distro, compiled from
18795           source, etc)
18796
18797       •   Describe the bug accurately and give a way to reproduce it.
18798
18799       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
18800           into the bug report.
18801
18802
18803
18804libguestfs-1.45.4                 2021-04-03                        guestfs(3)
Impressum