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

NAME

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

SYNOPSIS

9        #include <guestfs.h>
10
11        guestfs_h *g = guestfs_create ();
12        guestfs_add_drive (g, "guest.img");
13        guestfs_launch (g);
14        guestfs_mount (g, "/dev/sda1", "/");
15        guestfs_touch (g, "/hello");
16        guestfs_umount (g, "/");
17        guestfs_shutdown (g);
18        guestfs_close (g);
19
20        cc prog.c -o prog -lguestfs
21       or:
22        cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
23

DESCRIPTION

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

API OVERVIEW

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

CONNECTION MANAGEMENT

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

ERROR HANDLING

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

API CALLS

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

STRUCTURES

16537   guestfs_int_bool
16538        struct guestfs_int_bool {
16539          int32_t i;
16540          int32_t b;
16541        };
16542
16543        struct guestfs_int_bool_list {
16544          uint32_t len; /* Number of elements in list. */
16545          struct guestfs_int_bool *val; /* Elements. */
16546        };
16547
16548        int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16549        int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16550
16551        struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16552        struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16553
16554        void guestfs_free_int_bool (struct guestfs_int_bool *);
16555        void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16556
16557   guestfs_lvm_pv
16558        struct guestfs_lvm_pv {
16559          char *pv_name;
16560          /* The next field is NOT nul-terminated, be careful when printing it: */
16561          char pv_uuid[32];
16562          char *pv_fmt;
16563          uint64_t pv_size;
16564          uint64_t dev_size;
16565          uint64_t pv_free;
16566          uint64_t pv_used;
16567          char *pv_attr;
16568          int64_t pv_pe_count;
16569          int64_t pv_pe_alloc_count;
16570          char *pv_tags;
16571          uint64_t pe_start;
16572          int64_t pv_mda_count;
16573          uint64_t pv_mda_free;
16574        };
16575
16576        struct guestfs_lvm_pv_list {
16577          uint32_t len; /* Number of elements in list. */
16578          struct guestfs_lvm_pv *val; /* Elements. */
16579        };
16580
16581        int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16582        int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16583
16584        struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16585        struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16586
16587        void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16588        void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16589
16590   guestfs_lvm_vg
16591        struct guestfs_lvm_vg {
16592          char *vg_name;
16593          /* The next field is NOT nul-terminated, be careful when printing it: */
16594          char vg_uuid[32];
16595          char *vg_fmt;
16596          char *vg_attr;
16597          uint64_t vg_size;
16598          uint64_t vg_free;
16599          char *vg_sysid;
16600          uint64_t vg_extent_size;
16601          int64_t vg_extent_count;
16602          int64_t vg_free_count;
16603          int64_t max_lv;
16604          int64_t max_pv;
16605          int64_t pv_count;
16606          int64_t lv_count;
16607          int64_t snap_count;
16608          int64_t vg_seqno;
16609          char *vg_tags;
16610          int64_t vg_mda_count;
16611          uint64_t vg_mda_free;
16612        };
16613
16614        struct guestfs_lvm_vg_list {
16615          uint32_t len; /* Number of elements in list. */
16616          struct guestfs_lvm_vg *val; /* Elements. */
16617        };
16618
16619        int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16620        int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16621
16622        struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16623        struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16624
16625        void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16626        void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16627
16628   guestfs_lvm_lv
16629        struct guestfs_lvm_lv {
16630          char *lv_name;
16631          /* The next field is NOT nul-terminated, be careful when printing it: */
16632          char lv_uuid[32];
16633          char *lv_attr;
16634          int64_t lv_major;
16635          int64_t lv_minor;
16636          int64_t lv_kernel_major;
16637          int64_t lv_kernel_minor;
16638          uint64_t lv_size;
16639          int64_t seg_count;
16640          char *origin;
16641          /* The next field is [0..100] or -1 meaning 'not present': */
16642          float snap_percent;
16643          /* The next field is [0..100] or -1 meaning 'not present': */
16644          float copy_percent;
16645          char *move_pv;
16646          char *lv_tags;
16647          char *mirror_log;
16648          char *modules;
16649        };
16650
16651        struct guestfs_lvm_lv_list {
16652          uint32_t len; /* Number of elements in list. */
16653          struct guestfs_lvm_lv *val; /* Elements. */
16654        };
16655
16656        int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16657        int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16658
16659        struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16660        struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16661
16662        void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16663        void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16664
16665   guestfs_stat
16666        struct guestfs_stat {
16667          int64_t dev;
16668          int64_t ino;
16669          int64_t mode;
16670          int64_t nlink;
16671          int64_t uid;
16672          int64_t gid;
16673          int64_t rdev;
16674          int64_t size;
16675          int64_t blksize;
16676          int64_t blocks;
16677          int64_t atime;
16678          int64_t mtime;
16679          int64_t ctime;
16680        };
16681
16682        struct guestfs_stat_list {
16683          uint32_t len; /* Number of elements in list. */
16684          struct guestfs_stat *val; /* Elements. */
16685        };
16686
16687        int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16688        int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16689
16690        struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16691        struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16692
16693        void guestfs_free_stat (struct guestfs_stat *);
16694        void guestfs_free_stat_list (struct guestfs_stat_list *);
16695
16696   guestfs_statns
16697        struct guestfs_statns {
16698          int64_t st_dev;
16699          int64_t st_ino;
16700          int64_t st_mode;
16701          int64_t st_nlink;
16702          int64_t st_uid;
16703          int64_t st_gid;
16704          int64_t st_rdev;
16705          int64_t st_size;
16706          int64_t st_blksize;
16707          int64_t st_blocks;
16708          int64_t st_atime_sec;
16709          int64_t st_atime_nsec;
16710          int64_t st_mtime_sec;
16711          int64_t st_mtime_nsec;
16712          int64_t st_ctime_sec;
16713          int64_t st_ctime_nsec;
16714          int64_t st_spare1;
16715          int64_t st_spare2;
16716          int64_t st_spare3;
16717          int64_t st_spare4;
16718          int64_t st_spare5;
16719          int64_t st_spare6;
16720        };
16721
16722        struct guestfs_statns_list {
16723          uint32_t len; /* Number of elements in list. */
16724          struct guestfs_statns *val; /* Elements. */
16725        };
16726
16727        int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16728        int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16729
16730        struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16731        struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16732
16733        void guestfs_free_statns (struct guestfs_statns *);
16734        void guestfs_free_statns_list (struct guestfs_statns_list *);
16735
16736   guestfs_statvfs
16737        struct guestfs_statvfs {
16738          int64_t bsize;
16739          int64_t frsize;
16740          int64_t blocks;
16741          int64_t bfree;
16742          int64_t bavail;
16743          int64_t files;
16744          int64_t ffree;
16745          int64_t favail;
16746          int64_t fsid;
16747          int64_t flag;
16748          int64_t namemax;
16749        };
16750
16751        struct guestfs_statvfs_list {
16752          uint32_t len; /* Number of elements in list. */
16753          struct guestfs_statvfs *val; /* Elements. */
16754        };
16755
16756        int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16757        int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16758
16759        struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16760        struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16761
16762        void guestfs_free_statvfs (struct guestfs_statvfs *);
16763        void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16764
16765   guestfs_dirent
16766        struct guestfs_dirent {
16767          int64_t ino;
16768          char ftyp;
16769          char *name;
16770        };
16771
16772        struct guestfs_dirent_list {
16773          uint32_t len; /* Number of elements in list. */
16774          struct guestfs_dirent *val; /* Elements. */
16775        };
16776
16777        int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16778        int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16779
16780        struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16781        struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16782
16783        void guestfs_free_dirent (struct guestfs_dirent *);
16784        void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16785
16786   guestfs_version
16787        struct guestfs_version {
16788          int64_t major;
16789          int64_t minor;
16790          int64_t release;
16791          char *extra;
16792        };
16793
16794        struct guestfs_version_list {
16795          uint32_t len; /* Number of elements in list. */
16796          struct guestfs_version *val; /* Elements. */
16797        };
16798
16799        int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16800        int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16801
16802        struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16803        struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16804
16805        void guestfs_free_version (struct guestfs_version *);
16806        void guestfs_free_version_list (struct guestfs_version_list *);
16807
16808   guestfs_xattr
16809        struct guestfs_xattr {
16810          char *attrname;
16811          /* The next two fields describe a byte array. */
16812          uint32_t attrval_len;
16813          char *attrval;
16814        };
16815
16816        struct guestfs_xattr_list {
16817          uint32_t len; /* Number of elements in list. */
16818          struct guestfs_xattr *val; /* Elements. */
16819        };
16820
16821        int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16822        int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16823
16824        struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
16825        struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
16826
16827        void guestfs_free_xattr (struct guestfs_xattr *);
16828        void guestfs_free_xattr_list (struct guestfs_xattr_list *);
16829
16830   guestfs_inotify_event
16831        struct guestfs_inotify_event {
16832          int64_t in_wd;
16833          uint32_t in_mask;
16834          uint32_t in_cookie;
16835          char *in_name;
16836        };
16837
16838        struct guestfs_inotify_event_list {
16839          uint32_t len; /* Number of elements in list. */
16840          struct guestfs_inotify_event *val; /* Elements. */
16841        };
16842
16843        int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
16844        int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
16845
16846        struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
16847        struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
16848
16849        void guestfs_free_inotify_event (struct guestfs_inotify_event *);
16850        void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
16851
16852   guestfs_partition
16853        struct guestfs_partition {
16854          int32_t part_num;
16855          uint64_t part_start;
16856          uint64_t part_end;
16857          uint64_t part_size;
16858        };
16859
16860        struct guestfs_partition_list {
16861          uint32_t len; /* Number of elements in list. */
16862          struct guestfs_partition *val; /* Elements. */
16863        };
16864
16865        int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
16866        int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
16867
16868        struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
16869        struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
16870
16871        void guestfs_free_partition (struct guestfs_partition *);
16872        void guestfs_free_partition_list (struct guestfs_partition_list *);
16873
16874   guestfs_application
16875        struct guestfs_application {
16876          char *app_name;
16877          char *app_display_name;
16878          int32_t app_epoch;
16879          char *app_version;
16880          char *app_release;
16881          char *app_install_path;
16882          char *app_trans_path;
16883          char *app_publisher;
16884          char *app_url;
16885          char *app_source_package;
16886          char *app_summary;
16887          char *app_description;
16888        };
16889
16890        struct guestfs_application_list {
16891          uint32_t len; /* Number of elements in list. */
16892          struct guestfs_application *val; /* Elements. */
16893        };
16894
16895        int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
16896        int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
16897
16898        struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
16899        struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
16900
16901        void guestfs_free_application (struct guestfs_application *);
16902        void guestfs_free_application_list (struct guestfs_application_list *);
16903
16904   guestfs_application2
16905        struct guestfs_application2 {
16906          char *app2_name;
16907          char *app2_display_name;
16908          int32_t app2_epoch;
16909          char *app2_version;
16910          char *app2_release;
16911          char *app2_arch;
16912          char *app2_install_path;
16913          char *app2_trans_path;
16914          char *app2_publisher;
16915          char *app2_url;
16916          char *app2_source_package;
16917          char *app2_summary;
16918          char *app2_description;
16919          char *app2_spare1;
16920          char *app2_spare2;
16921          char *app2_spare3;
16922          char *app2_spare4;
16923        };
16924
16925        struct guestfs_application2_list {
16926          uint32_t len; /* Number of elements in list. */
16927          struct guestfs_application2 *val; /* Elements. */
16928        };
16929
16930        int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
16931        int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
16932
16933        struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
16934        struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
16935
16936        void guestfs_free_application2 (struct guestfs_application2 *);
16937        void guestfs_free_application2_list (struct guestfs_application2_list *);
16938
16939   guestfs_isoinfo
16940        struct guestfs_isoinfo {
16941          char *iso_system_id;
16942          char *iso_volume_id;
16943          uint32_t iso_volume_space_size;
16944          uint32_t iso_volume_set_size;
16945          uint32_t iso_volume_sequence_number;
16946          uint32_t iso_logical_block_size;
16947          char *iso_volume_set_id;
16948          char *iso_publisher_id;
16949          char *iso_data_preparer_id;
16950          char *iso_application_id;
16951          char *iso_copyright_file_id;
16952          char *iso_abstract_file_id;
16953          char *iso_bibliographic_file_id;
16954          int64_t iso_volume_creation_t;
16955          int64_t iso_volume_modification_t;
16956          int64_t iso_volume_expiration_t;
16957          int64_t iso_volume_effective_t;
16958        };
16959
16960        struct guestfs_isoinfo_list {
16961          uint32_t len; /* Number of elements in list. */
16962          struct guestfs_isoinfo *val; /* Elements. */
16963        };
16964
16965        int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
16966        int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
16967
16968        struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
16969        struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
16970
16971        void guestfs_free_isoinfo (struct guestfs_isoinfo *);
16972        void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
16973
16974   guestfs_mdstat
16975        struct guestfs_mdstat {
16976          char *mdstat_device;
16977          int32_t mdstat_index;
16978          char *mdstat_flags;
16979        };
16980
16981        struct guestfs_mdstat_list {
16982          uint32_t len; /* Number of elements in list. */
16983          struct guestfs_mdstat *val; /* Elements. */
16984        };
16985
16986        int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
16987        int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
16988
16989        struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
16990        struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
16991
16992        void guestfs_free_mdstat (struct guestfs_mdstat *);
16993        void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
16994
16995   guestfs_btrfssubvolume
16996        struct guestfs_btrfssubvolume {
16997          uint64_t btrfssubvolume_id;
16998          uint64_t btrfssubvolume_top_level_id;
16999          char *btrfssubvolume_path;
17000        };
17001
17002        struct guestfs_btrfssubvolume_list {
17003          uint32_t len; /* Number of elements in list. */
17004          struct guestfs_btrfssubvolume *val; /* Elements. */
17005        };
17006
17007        int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17008        int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17009
17010        struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17011        struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17012
17013        void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17014        void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17015
17016   guestfs_btrfsqgroup
17017        struct guestfs_btrfsqgroup {
17018          char *btrfsqgroup_id;
17019          uint64_t btrfsqgroup_rfer;
17020          uint64_t btrfsqgroup_excl;
17021        };
17022
17023        struct guestfs_btrfsqgroup_list {
17024          uint32_t len; /* Number of elements in list. */
17025          struct guestfs_btrfsqgroup *val; /* Elements. */
17026        };
17027
17028        int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17029        int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17030
17031        struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17032        struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17033
17034        void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17035        void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17036
17037   guestfs_btrfsbalance
17038        struct guestfs_btrfsbalance {
17039          char *btrfsbalance_status;
17040          uint64_t btrfsbalance_total;
17041          uint64_t btrfsbalance_balanced;
17042          uint64_t btrfsbalance_considered;
17043          uint64_t btrfsbalance_left;
17044        };
17045
17046        struct guestfs_btrfsbalance_list {
17047          uint32_t len; /* Number of elements in list. */
17048          struct guestfs_btrfsbalance *val; /* Elements. */
17049        };
17050
17051        int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17052        int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17053
17054        struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17055        struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17056
17057        void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17058        void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17059
17060   guestfs_btrfsscrub
17061        struct guestfs_btrfsscrub {
17062          uint64_t btrfsscrub_data_extents_scrubbed;
17063          uint64_t btrfsscrub_tree_extents_scrubbed;
17064          uint64_t btrfsscrub_data_bytes_scrubbed;
17065          uint64_t btrfsscrub_tree_bytes_scrubbed;
17066          uint64_t btrfsscrub_read_errors;
17067          uint64_t btrfsscrub_csum_errors;
17068          uint64_t btrfsscrub_verify_errors;
17069          uint64_t btrfsscrub_no_csum;
17070          uint64_t btrfsscrub_csum_discards;
17071          uint64_t btrfsscrub_super_errors;
17072          uint64_t btrfsscrub_malloc_errors;
17073          uint64_t btrfsscrub_uncorrectable_errors;
17074          uint64_t btrfsscrub_unverified_errors;
17075          uint64_t btrfsscrub_corrected_errors;
17076          uint64_t btrfsscrub_last_physical;
17077        };
17078
17079        struct guestfs_btrfsscrub_list {
17080          uint32_t len; /* Number of elements in list. */
17081          struct guestfs_btrfsscrub *val; /* Elements. */
17082        };
17083
17084        int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17085        int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17086
17087        struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17088        struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17089
17090        void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17091        void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17092
17093   guestfs_xfsinfo
17094        struct guestfs_xfsinfo {
17095          char *xfs_mntpoint;
17096          uint32_t xfs_inodesize;
17097          uint32_t xfs_agcount;
17098          uint32_t xfs_agsize;
17099          uint32_t xfs_sectsize;
17100          uint32_t xfs_attr;
17101          uint32_t xfs_blocksize;
17102          uint64_t xfs_datablocks;
17103          uint32_t xfs_imaxpct;
17104          uint32_t xfs_sunit;
17105          uint32_t xfs_swidth;
17106          uint32_t xfs_dirversion;
17107          uint32_t xfs_dirblocksize;
17108          uint32_t xfs_cimode;
17109          char *xfs_logname;
17110          uint32_t xfs_logblocksize;
17111          uint32_t xfs_logblocks;
17112          uint32_t xfs_logversion;
17113          uint32_t xfs_logsectsize;
17114          uint32_t xfs_logsunit;
17115          uint32_t xfs_lazycount;
17116          char *xfs_rtname;
17117          uint32_t xfs_rtextsize;
17118          uint64_t xfs_rtblocks;
17119          uint64_t xfs_rtextents;
17120        };
17121
17122        struct guestfs_xfsinfo_list {
17123          uint32_t len; /* Number of elements in list. */
17124          struct guestfs_xfsinfo *val; /* Elements. */
17125        };
17126
17127        int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17128        int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17129
17130        struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17131        struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17132
17133        void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17134        void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17135
17136   guestfs_utsname
17137        struct guestfs_utsname {
17138          char *uts_sysname;
17139          char *uts_release;
17140          char *uts_version;
17141          char *uts_machine;
17142        };
17143
17144        struct guestfs_utsname_list {
17145          uint32_t len; /* Number of elements in list. */
17146          struct guestfs_utsname *val; /* Elements. */
17147        };
17148
17149        int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17150        int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17151
17152        struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17153        struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17154
17155        void guestfs_free_utsname (struct guestfs_utsname *);
17156        void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17157
17158   guestfs_hivex_node
17159        struct guestfs_hivex_node {
17160          int64_t hivex_node_h;
17161        };
17162
17163        struct guestfs_hivex_node_list {
17164          uint32_t len; /* Number of elements in list. */
17165          struct guestfs_hivex_node *val; /* Elements. */
17166        };
17167
17168        int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17169        int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17170
17171        struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17172        struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17173
17174        void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17175        void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17176
17177   guestfs_hivex_value
17178        struct guestfs_hivex_value {
17179          int64_t hivex_value_h;
17180        };
17181
17182        struct guestfs_hivex_value_list {
17183          uint32_t len; /* Number of elements in list. */
17184          struct guestfs_hivex_value *val; /* Elements. */
17185        };
17186
17187        int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17188        int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17189
17190        struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17191        struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17192
17193        void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17194        void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17195
17196   guestfs_internal_mountable
17197        struct guestfs_internal_mountable {
17198          int32_t im_type;
17199          char *im_device;
17200          char *im_volume;
17201        };
17202
17203        struct guestfs_internal_mountable_list {
17204          uint32_t len; /* Number of elements in list. */
17205          struct guestfs_internal_mountable *val; /* Elements. */
17206        };
17207
17208        int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17209        int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17210
17211        struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17212        struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17213
17214        void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17215        void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17216
17217   guestfs_tsk_dirent
17218        struct guestfs_tsk_dirent {
17219          uint64_t tsk_inode;
17220          char tsk_type;
17221          int64_t tsk_size;
17222          char *tsk_name;
17223          uint32_t tsk_flags;
17224          int64_t tsk_atime_sec;
17225          int64_t tsk_atime_nsec;
17226          int64_t tsk_mtime_sec;
17227          int64_t tsk_mtime_nsec;
17228          int64_t tsk_ctime_sec;
17229          int64_t tsk_ctime_nsec;
17230          int64_t tsk_crtime_sec;
17231          int64_t tsk_crtime_nsec;
17232          int64_t tsk_nlink;
17233          char *tsk_link;
17234          int64_t tsk_spare1;
17235        };
17236
17237        struct guestfs_tsk_dirent_list {
17238          uint32_t len; /* Number of elements in list. */
17239          struct guestfs_tsk_dirent *val; /* Elements. */
17240        };
17241
17242        int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17243        int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17244
17245        struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17246        struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17247
17248        void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17249        void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17250
17251   guestfs_yara_detection
17252        struct guestfs_yara_detection {
17253          char *yara_name;
17254          char *yara_rule;
17255        };
17256
17257        struct guestfs_yara_detection_list {
17258          uint32_t len; /* Number of elements in list. */
17259          struct guestfs_yara_detection *val; /* Elements. */
17260        };
17261
17262        int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17263        int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17264
17265        struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17266        struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17267
17268        void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17269        void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17270

AVAILABILITY

17272   GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17273       Using "guestfs_available" you can test availability of the following
17274       groups of functions.  This test queries the appliance to see if the
17275       appliance you are currently using supports the functionality.
17276
17277       acl The following functions: "guestfs_acl_delete_def_file"
17278           "guestfs_acl_get_file" "guestfs_acl_set_file"
17279
17280       blkdiscard
17281           The following functions: "guestfs_blkdiscard"
17282
17283       blkdiscardzeroes
17284           The following functions: "guestfs_blkdiscardzeroes"
17285
17286       btrfs
17287           The following functions: "guestfs_btrfs_balance_cancel"
17288           "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17289           "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17290           "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17291           "guestfs_btrfs_filesystem_defragment"
17292           "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17293           "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17294           "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17295           "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17296           "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17297           "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17298           "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17299           "guestfs_btrfs_rescue_chunk_recover"
17300           "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17301           "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17302           "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17303           "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17304           "guestfs_btrfs_subvolume_get_default"
17305           "guestfs_btrfs_subvolume_list"
17306           "guestfs_btrfs_subvolume_set_default"
17307           "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17308           "guestfs_btrfstune_enable_extended_inode_refs"
17309           "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17310           "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17311
17312       extlinux
17313           The following functions: "guestfs_extlinux"
17314
17315       f2fs
17316           The following functions: "guestfs_f2fs_expand"
17317
17318       fstrim
17319           The following functions: "guestfs_fstrim"
17320
17321       gdisk
17322           The following functions: "guestfs_part_expand_gpt"
17323           "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17324           "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17325           "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17326           "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17327           "guestfs_part_set_gpt_type"
17328
17329       grub
17330           The following functions: "guestfs_grub_install"
17331
17332       hivex
17333           The following functions: "guestfs_hivex_close"
17334           "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17335           "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17336           "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17337           "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17338           "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17339           "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17340           "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17341           "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17342
17343       inotify
17344           The following functions: "guestfs_inotify_add_watch"
17345           "guestfs_inotify_close" "guestfs_inotify_files"
17346           "guestfs_inotify_init" "guestfs_inotify_read"
17347           "guestfs_inotify_rm_watch"
17348
17349       journal
17350           The following functions: "guestfs_internal_journal_get"
17351           "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17352           "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17353           "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17354           "guestfs_journal_skip"
17355
17356       ldm The following functions: "guestfs_ldmtool_create_all"
17357           "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17358           "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17359           "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17360           "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17361           "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17362           "guestfs_list_ldm_volumes"
17363
17364       libtsk
17365           The following functions: "guestfs_internal_filesystem_walk"
17366           "guestfs_internal_find_inode"
17367
17368       libyara
17369           The following functions: "guestfs_internal_yara_scan"
17370           "guestfs_yara_destroy" "guestfs_yara_load"
17371
17372       linuxcaps
17373           The following functions: "guestfs_cap_get_file"
17374           "guestfs_cap_set_file"
17375
17376       linuxfsuuid
17377           The following functions: "guestfs_mke2fs_JU"
17378           "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17379           "guestfs_swapon_uuid"
17380
17381       linuxmodules
17382           The following functions: "guestfs_modprobe"
17383
17384       linuxxattrs
17385           The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17386           "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17387           "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17388           "guestfs_removexattr" "guestfs_setxattr"
17389
17390       luks
17391           The following functions: "guestfs_luks_add_key"
17392           "guestfs_luks_close" "guestfs_luks_format"
17393           "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17394           "guestfs_luks_open" "guestfs_luks_open_ro"
17395
17396       lvm2
17397           The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17398           "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17399           "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17400           "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17401           "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17402           "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17403           "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17404           "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17405           "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17406           "guestfs_vgs" "guestfs_vgs_full"
17407
17408       mdadm
17409           The following functions: "guestfs_md_create" "guestfs_md_detail"
17410           "guestfs_md_stat" "guestfs_md_stop"
17411
17412       mknod
17413           The following functions: "guestfs_mkfifo" "guestfs_mknod"
17414           "guestfs_mknod_b" "guestfs_mknod_c"
17415
17416       ntfs3g
17417           The following functions: "guestfs_ntfs_3g_probe"
17418           "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17419
17420       ntfsprogs
17421           The following functions: "guestfs_ntfsresize"
17422           "guestfs_ntfsresize_size"
17423
17424       rsync
17425           The following functions: "guestfs_rsync" "guestfs_rsync_in"
17426           "guestfs_rsync_out"
17427
17428       scrub
17429           The following functions: "guestfs_scrub_device"
17430           "guestfs_scrub_file" "guestfs_scrub_freespace"
17431
17432       selinux
17433           The following functions: "guestfs_getcon" "guestfs_setcon"
17434
17435       selinuxrelabel
17436           The following functions: "guestfs_selinux_relabel"
17437
17438       sleuthkit
17439           The following functions: "guestfs_download_blocks"
17440           "guestfs_download_inode"
17441
17442       squashfs
17443           The following functions: "guestfs_mksquashfs"
17444
17445       syslinux
17446           The following functions: "guestfs_syslinux"
17447
17448       wipefs
17449           The following functions: "guestfs_wipefs"
17450
17451       xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17452           "guestfs_xfs_info" "guestfs_xfs_repair"
17453
17454       xz  The following functions: "guestfs_txz_in" "guestfs_txz_out"
17455
17456       zerofree
17457           The following functions: "guestfs_zerofree"
17458
17459   FILESYSTEM AVAILABLE
17460       The "guestfs_filesystem_available" call tests whether a filesystem type
17461       is supported by the appliance kernel.
17462
17463       This is mainly useful as a negative test.  If this returns true, it
17464       doesn't mean that a particular filesystem can be mounted, since
17465       filesystems can fail for other reasons such as it being a later version
17466       of the filesystem, or having incompatible features.
17467
17468   GUESTFISH supported COMMAND
17469       In guestfish(3) there is a handy interactive command "supported" which
17470       prints out the available groups and whether they are supported by this
17471       build of libguestfs.  Note however that you have to do "run" first.
17472
17473   SINGLE CALLS AT COMPILE TIME
17474       Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17475       function, such as:
17476
17477        #define GUESTFS_HAVE_DD 1
17478
17479       if "guestfs_dd" is available.
17480
17481       Before version 1.5.8, if you needed to test whether a single libguestfs
17482       function is available at compile time, we recommended using build tools
17483       such as autoconf or cmake.  For example in autotools you could use:
17484
17485        AC_CHECK_LIB([guestfs],[guestfs_create])
17486        AC_CHECK_FUNCS([guestfs_dd])
17487
17488       which would result in "HAVE_GUESTFS_DD" being either defined or not
17489       defined in your program.
17490
17491   SINGLE CALLS AT RUN TIME
17492       Testing at compile time doesn't guarantee that a function really exists
17493       in the library.  The reason is that you might be dynamically linked
17494       against a previous libguestfs.so (dynamic library) which doesn't have
17495       the call.  This situation unfortunately results in a segmentation
17496       fault, which is a shortcoming of the C dynamic linking system itself.
17497
17498       You can use dlopen(3) to test if a function is available at run time,
17499       as in this example program (note that you still need the compile time
17500       check as well):
17501
17502        #include <stdio.h>
17503        #include <stdlib.h>
17504        #include <unistd.h>
17505        #include <dlfcn.h>
17506        #include <guestfs.h>
17507
17508        main ()
17509        {
17510        #ifdef GUESTFS_HAVE_DD
17511          void *dl;
17512          int has_function;
17513
17514          /* Test if the function guestfs_dd is really available. */
17515          dl = dlopen (NULL, RTLD_LAZY);
17516          if (!dl) {
17517            fprintf (stderr, "dlopen: %s\n", dlerror ());
17518            exit (EXIT_FAILURE);
17519          }
17520          has_function = dlsym (dl, "guestfs_dd") != NULL;
17521          dlclose (dl);
17522
17523          if (!has_function)
17524            printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17525          else {
17526            printf ("this libguestfs.so has guestfs_dd function\n");
17527            /* Now it's safe to call
17528            guestfs_dd (g, "foo", "bar");
17529            */
17530          }
17531        #else
17532          printf ("guestfs_dd function was not found at compile time\n");
17533        #endif
17534         }
17535
17536       You may think the above is an awful lot of hassle, and it is.  There
17537       are other ways outside of the C linking system to ensure that this kind
17538       of incompatibility never arises, such as using package versioning:
17539
17540        Requires: libguestfs >= 1.0.80
17541

CALLS WITH OPTIONAL ARGUMENTS

17543       A recent feature of the API is the introduction of calls which take
17544       optional arguments.  In C these are declared 3 ways.  The main way is
17545       as a call which takes variable arguments (ie. "..."), as in this
17546       example:
17547
17548        int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17549
17550       Call this with a list of optional arguments, terminated by "-1".  So to
17551       call with no optional arguments specified:
17552
17553        guestfs_add_drive_opts (g, filename, -1);
17554
17555       With a single optional argument:
17556
17557        guestfs_add_drive_opts (g, filename,
17558                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17559                                -1);
17560
17561       With two:
17562
17563        guestfs_add_drive_opts (g, filename,
17564                                GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17565                                GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17566                                -1);
17567
17568       and so forth.  Don’t forget the terminating "-1" otherwise Bad Things
17569       will happen!
17570
17571   USING va_list FOR OPTIONAL ARGUMENTS
17572       The second variant has the same name with the suffix "_va", which works
17573       the same way but takes a "va_list".  See the C manual for details.  For
17574       the example function, this is declared:
17575
17576        int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17577                                       va_list args);
17578
17579   CONSTRUCTING OPTIONAL ARGUMENTS
17580       The third variant is useful where you need to construct these calls.
17581       You pass in a structure where you fill in the optional fields.  The
17582       structure has a bitmask as the first element which you must set to
17583       indicate which fields you have filled in.  For our example function the
17584       structure and call are declared:
17585
17586        struct guestfs_add_drive_opts_argv {
17587          uint64_t bitmask;
17588          int readonly;
17589          const char *format;
17590          /* ... */
17591        };
17592        int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17593                     const struct guestfs_add_drive_opts_argv *optargs);
17594
17595       You could call it like this:
17596
17597        struct guestfs_add_drive_opts_argv optargs = {
17598          .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17599                     GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17600          .readonly = 1,
17601          .format = "qcow2"
17602        };
17603
17604        guestfs_add_drive_opts_argv (g, filename, &optargs);
17605
17606       Notes:
17607
17608       ·   The "_BITMASK" suffix on each option name when specifying the
17609           bitmask.
17610
17611       ·   You do not need to fill in all fields of the structure.
17612
17613       ·   There must be a one-to-one correspondence between fields of the
17614           structure that are filled in, and bits set in the bitmask.
17615
17616   OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17617       In other languages, optional arguments are expressed in the way that is
17618       natural for that language.  We refer you to the language-specific
17619       documentation for more details on that.
17620
17621       For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17622

EVENTS

17624   SETTING CALLBACKS TO HANDLE EVENTS
17625       Note: This section documents the generic event mechanism introduced in
17626       libguestfs 1.10, which you should use in new code if possible.  The old
17627       functions "guestfs_set_log_message_callback",
17628       "guestfs_set_subprocess_quit_callback",
17629       "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17630       "guestfs_set_progress_callback" are no longer documented in this manual
17631       page.  Because of the ABI guarantee, the old functions continue to
17632       work.
17633
17634       Handles generate events when certain things happen, such as log
17635       messages being generated, progress messages during long-running
17636       operations, or the handle being closed.  The API calls described below
17637       let you register a callback to be called when events happen.  You can
17638       register multiple callbacks (for the same, different or overlapping
17639       sets of events), and individually remove callbacks.  If callbacks are
17640       not removed, then they remain in force until the handle is closed.
17641
17642       In the current implementation, events are only generated synchronously:
17643       that means that events (and hence callbacks) can only happen while you
17644       are in the middle of making another libguestfs call.  The callback is
17645       called in the same thread.
17646
17647       Events may contain a payload, usually nothing (void), an array of 64
17648       bit unsigned integers, or a message buffer.  Payloads are discussed
17649       later on.
17650
17651   CLASSES OF EVENTS
17652       GUESTFS_EVENT_CLOSE (payload type: void)
17653           The callback function will be called while the handle is being
17654           closed (synchronously from "guestfs_close").
17655
17656           Note that libguestfs installs an atexit(3) handler to try to clean
17657           up handles that are open when the program exits.  This means that
17658           this callback might be called indirectly from exit(3), which can
17659           cause unexpected problems in higher-level languages (eg. if your
17660           HLL interpreter has already been cleaned up by the time this is
17661           called, and if your callback then jumps into some HLL function).
17662
17663           If no callback is registered: the handle is closed without any
17664           callback being invoked.
17665
17666       GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17667           The callback function will be called when the child process quits,
17668           either asynchronously or if killed by "guestfs_kill_subprocess".
17669           (This corresponds to a transition from any state to the CONFIG
17670           state).
17671
17672           If no callback is registered: the event is ignored.
17673
17674       GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17675           The callback function will be called when the child process becomes
17676           ready first time after it has been launched.  (This corresponds to
17677           a transition from LAUNCHING to the READY state).
17678
17679           If no callback is registered: the event is ignored.
17680
17681       GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17682           Some long-running operations can generate progress messages.  If
17683           this callback is registered, then it will be called each time a
17684           progress message is generated (usually two seconds after the
17685           operation started, and three times per second thereafter until it
17686           completes, although the frequency may change in future versions).
17687
17688           The callback receives in the payload four unsigned 64 bit numbers
17689           which are (in order): "proc_nr", "serial", "position", "total".
17690
17691           The units of "total" are not defined, although for some operations
17692           "total" may relate in some way to the amount of data to be
17693           transferred (eg. in bytes or megabytes), and "position" may be the
17694           portion which has been transferred.
17695
17696           The only defined and stable parts of the API are:
17697
17698           ·   The callback can display to the user some type of progress bar
17699               or indicator which shows the ratio of "position":"total".
17700
17701           ·   0 <= "position" <= "total"
17702
17703           ·   If any progress notification is sent during a call, then a
17704               final progress notification is always sent when "position" =
17705               "total" (unless the call fails with an error).
17706
17707               This is to simplify caller code, so callers can easily set the
17708               progress indicator to "100%" at the end of the operation,
17709               without requiring special code to detect this case.
17710
17711           ·   For some calls we are unable to estimate the progress of the
17712               call, but we can still generate progress messages to indicate
17713               activity.  This is known as "pulse mode", and is directly
17714               supported by certain progress bar implementations (eg.
17715               GtkProgressBar).
17716
17717               For these calls, zero or more progress messages are generated
17718               with "position = 0" and "total = 1", followed by a final
17719               message with "position = total = 1".
17720
17721               As noted above, if the call fails with an error then the final
17722               message may not be generated.
17723
17724           The callback also receives the procedure number ("proc_nr") and
17725           serial number ("serial") of the call.  These are only useful for
17726           debugging protocol issues, and the callback can normally ignore
17727           them.  The callback may want to print these numbers in error
17728           messages or debugging messages.
17729
17730           If no callback is registered: progress messages are discarded.
17731
17732       GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17733           The callback function is called whenever a log message is generated
17734           by qemu, the appliance kernel, guestfsd (daemon), or utility
17735           programs.
17736
17737           If the verbose flag ("guestfs_set_verbose") is set before launch
17738           ("guestfs_launch") then additional debug messages are generated.
17739
17740           If no callback is registered: the messages are discarded unless the
17741           verbose flag is set in which case they are sent to stderr.  You can
17742           override the printing of verbose messages to stderr by setting up a
17743           callback.
17744
17745       GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17746           The callback function is called whenever a log message is generated
17747           by the library part of libguestfs.
17748
17749           If the verbose flag ("guestfs_set_verbose") is set then additional
17750           debug messages are generated.
17751
17752           If no callback is registered: the messages are discarded unless the
17753           verbose flag is set in which case they are sent to stderr.  You can
17754           override the printing of verbose messages to stderr by setting up a
17755           callback.
17756
17757       GUESTFS_EVENT_WARNING (payload type: message buffer)
17758           The callback function is called whenever a warning message is
17759           generated by the library part of libguestfs.
17760
17761           If no callback is registered: the messages are printed to stderr.
17762           You can override the printing of warning messages to stderr by
17763           setting up a callback.
17764
17765       GUESTFS_EVENT_TRACE (payload type: message buffer)
17766           The callback function is called whenever a trace message is
17767           generated.  This only applies if the trace flag
17768           ("guestfs_set_trace") is set.
17769
17770           If no callback is registered: the messages are sent to stderr.  You
17771           can override the printing of trace messages to stderr by setting up
17772           a callback.
17773
17774       GUESTFS_EVENT_ENTER (payload type: function name)
17775           The callback function is called whenever a libguestfs function is
17776           entered.
17777
17778           The payload is a string which contains the name of the function
17779           that we are entering (not including "guestfs_" prefix).
17780
17781           Note that libguestfs functions can call themselves, so you may see
17782           many events from a single call.  A few libguestfs functions do not
17783           generate this event.
17784
17785           If no callback is registered: the event is ignored.
17786
17787       GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17788           For any API function that opens a libvirt connection, this event
17789           may be generated to indicate that libvirt demands authentication
17790           information.  See "LIBVIRT AUTHENTICATION" below.
17791
17792           If no callback is registered: "virConnectAuthPtrDefault" is used
17793           (suitable for command-line programs only).
17794
17795   EVENT API
17796       guestfs_set_event_callback
17797
17798        int guestfs_set_event_callback (guestfs_h *g,
17799                                        guestfs_event_callback cb,
17800                                        uint64_t event_bitmask,
17801                                        int flags,
17802                                        void *opaque);
17803
17804       This function registers a callback ("cb") for all event classes in the
17805       "event_bitmask".
17806
17807       For example, to register for all log message events, you could call
17808       this function with the bitmask
17809       "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17810       To register a single callback for all possible classes of events, use
17811       "GUESTFS_EVENT_ALL".
17812
17813       "flags" should always be passed as 0.
17814
17815       "opaque" is an opaque pointer which is passed to the callback.  You can
17816       use it for any purpose.
17817
17818       The return value is the event handle (an integer) which you can use to
17819       delete the callback (see below).
17820
17821       If there is an error, this function returns "-1", and sets the error in
17822       the handle in the usual way (see "guestfs_last_error" etc.)
17823
17824       Callbacks remain in effect until they are deleted, or until the handle
17825       is closed.
17826
17827       In the case where multiple callbacks are registered for a particular
17828       event class, all of the callbacks are called.  The order in which
17829       multiple callbacks are called is not defined.
17830
17831       guestfs_delete_event_callback
17832
17833        void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
17834
17835       Delete a callback that was previously registered.  "event_handle"
17836       should be the integer that was returned by a previous call to
17837       "guestfs_set_event_callback" on the same handle.
17838
17839       guestfs_event_to_string
17840
17841        char *guestfs_event_to_string (uint64_t event);
17842
17843       "event" is either a single event or a bitmask of events.  This returns
17844       a string representation (useful for debugging or printing events).
17845
17846       A single event is returned as the name in lower case, eg. "close".
17847
17848       A bitmask of several events is returned as a comma-separated list, eg.
17849       "close,progress".
17850
17851       If zero is passed, then the empty string "" is returned.
17852
17853       On success this returns a string.  On error it returns NULL and sets
17854       "errno".
17855
17856       The returned string must be freed by the caller.
17857
17858       guestfs_event_callback
17859
17860        typedef void (*guestfs_event_callback) (
17861                         guestfs_h *g,
17862                         void *opaque,
17863                         uint64_t event,
17864                         int event_handle,
17865                         int flags,
17866                         const char *buf, size_t buf_len,
17867                         const uint64_t *array, size_t array_len);
17868
17869       This is the type of the event callback function that you have to
17870       provide.
17871
17872       The basic parameters are: the handle ("g"), the opaque user pointer
17873       ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
17874       handle, and "flags" which in the current API you should ignore.
17875
17876       The remaining parameters contain the event payload (if any).  Each
17877       event may contain a payload, which usually relates to the event class,
17878       but for future proofing your code should be written to handle any
17879       payload for any event class.
17880
17881       "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
17882       there is no message buffer).  Note that this message buffer can contain
17883       arbitrary 8 bit data, including NUL bytes.
17884
17885       "array" and "array_len" is an array of 64 bit unsigned integers.  At
17886       the moment this is only used for progress messages.
17887
17888   EXAMPLE: CAPTURING LOG MESSAGES
17889       A working program demonstrating this can be found in
17890       examples/debug-logging.c in the source of libguestfs.
17891
17892       One motivation for the generic event API was to allow GUI programs to
17893       capture debug and other messages.  In libguestfs ≤ 1.8 these were sent
17894       unconditionally to "stderr".
17895
17896       Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
17897       "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
17898       "GUESTFS_EVENT_TRACE".  (Note that error messages are not events; you
17899       must capture error messages separately).
17900
17901       Programs have to set up a callback to capture the classes of events of
17902       interest:
17903
17904        int eh =
17905          guestfs_set_event_callback
17906            (g, message_callback,
17907             GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
17908             GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
17909             0, NULL) == -1)
17910        if (eh == -1) {
17911          // handle error in the usual way
17912        }
17913
17914       The callback can then direct messages to the appropriate place.  In
17915       this example, messages are directed to syslog:
17916
17917        static void
17918        message_callback (
17919                guestfs_h *g,
17920                void *opaque,
17921                uint64_t event,
17922                int event_handle,
17923                int flags,
17924                const char *buf, size_t buf_len,
17925                const uint64_t *array, size_t array_len)
17926        {
17927          const int priority = LOG_USER|LOG_INFO;
17928          if (buf_len > 0)
17929            syslog (priority, "event 0x%lx: %s", event, buf);
17930        }
17931
17932   LIBVIRT AUTHENTICATION
17933       Some libguestfs API calls can open libvirt connections.  Currently the
17934       only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
17935       backend has been selected.  Libvirt connections may require
17936       authentication, for example if they need to access a remote server or
17937       to access root services from non-root.  Libvirt authentication happens
17938       via a callback mechanism, see
17939       http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
17940
17941       You may provide libvirt authentication data by registering a callback
17942       for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
17943
17944       If no such event is registered, then libguestfs uses a libvirt function
17945       that provides command-line prompts ("virConnectAuthPtrDefault").  This
17946       is only suitable for command-line libguestfs programs.
17947
17948       To provide authentication, first call
17949       "guestfs_set_libvirt_supported_credentials" with the list of
17950       credentials your program knows how to provide.  Second, register a
17951       callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event.  The event handler
17952       will be called when libvirt is requesting authentication information.
17953
17954       In the event handler, call "guestfs_get_libvirt_requested_credentials"
17955       to get a list of the credentials that libvirt is asking for.  You then
17956       need to ask (eg. the user) for each credential, and call
17957       "guestfs_set_libvirt_requested_credential" with the answer.  Note that
17958       for each credential, additional information may be available via the
17959       calls "guestfs_get_libvirt_requested_credential_prompt",
17960       "guestfs_get_libvirt_requested_credential_challenge" or
17961       "guestfs_get_libvirt_requested_credential_defresult".
17962
17963       The example program below should make this clearer.
17964
17965       There is also a more substantial working example program supplied with
17966       the libguestfs sources, called libvirt-auth.c.
17967
17968        main ()
17969        {
17970          guestfs_h *g;
17971          char *creds[] = { "authname", "passphrase", NULL };
17972          int r, eh;
17973
17974          g = guestfs_create ();
17975          if (!g) exit (EXIT_FAILURE);
17976
17977          /* Tell libvirt what credentials the program supports. */
17978          r = guestfs_set_libvirt_supported_credentials (g, creds);
17979          if (r == -1)
17980            exit (EXIT_FAILURE);
17981
17982          /* Set up the event handler. */
17983          eh = guestfs_set_event_callback (
17984              g, do_auth,
17985              GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
17986          if (eh == -1)
17987            exit (EXIT_FAILURE);
17988
17989          /* An example of a call that may ask for credentials. */
17990          r = guestfs_add_domain (
17991              g, "dom",
17992              GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
17993              -1);
17994          if (r == -1)
17995            exit (EXIT_FAILURE);
17996
17997          exit (EXIT_SUCCESS);
17998        }
17999
18000        static void
18001        do_auth (guestfs_h *g,
18002                 void *opaque,
18003                 uint64_t event,
18004                 int event_handle,
18005                 int flags,
18006                 const char *buf, size_t buf_len,
18007                 const uint64_t *array, size_t array_len)
18008        {
18009          char **creds;
18010          size_t i;
18011          char *prompt;
18012          char *reply;
18013          size_t replylen;
18014          int r;
18015
18016          // buf will be the libvirt URI.  buf_len may be ignored.
18017          printf ("Authentication required for libvirt conn '%s'\n",
18018                  buf);
18019
18020          // Ask libguestfs what credentials libvirt is demanding.
18021          creds = guestfs_get_libvirt_requested_credentials (g);
18022          if (creds == NULL)
18023            exit (EXIT_FAILURE);
18024
18025          // Now ask the user for answers.
18026          for (i = 0; creds[i] != NULL; ++i)
18027          {
18028            if (strcmp (creds[i], "authname") == 0 ||
18029                strcmp (creds[i], "passphrase") == 0)
18030            {
18031              prompt =
18032                guestfs_get_libvirt_requested_credential_prompt (g, i);
18033              if (prompt && strcmp (prompt, "") != 0)
18034                printf ("%s: ", prompt);
18035              free (prompt);
18036
18037              // Some code here to ask for the credential.
18038              // ...
18039              // Put the reply in 'reply', length 'replylen' (bytes).
18040
18041             r = guestfs_set_libvirt_requested_credential (g, i,
18042                 reply, replylen);
18043             if (r == -1)
18044               exit (EXIT_FAILURE);
18045            }
18046
18047            free (creds[i]);
18048          }
18049
18050          free (creds);
18051        }
18052

CANCELLING LONG TRANSFERS

18054       Some operations can be cancelled by the caller while they are in
18055       progress.  Currently only operations that involve uploading or
18056       downloading data can be cancelled (technically: operations that have
18057       "FileIn" or "FileOut" parameters in the generator).
18058
18059       To cancel the transfer, call "guestfs_user_cancel".  For more
18060       information, read the description of "guestfs_user_cancel".
18061

PRIVATE DATA AREA

18063       You can attach named pieces of private data to the libguestfs handle,
18064       fetch them by name, and walk over them, for the lifetime of the handle.
18065       This is called the private data area and is only available from the C
18066       API.
18067
18068       To attach a named piece of data, use the following call:
18069
18070        void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18071
18072       "key" is the name to associate with this data, and "data" is an
18073       arbitrary pointer (which can be "NULL").  Any previous item with the
18074       same key is overwritten.
18075
18076       You can use any "key" string you want, but avoid keys beginning with an
18077       underscore character (libguestfs uses those for its own internal
18078       purposes, such as implementing language bindings).  It is recommended
18079       that you prefix the key with some unique string to avoid collisions
18080       with other users.
18081
18082       To retrieve the pointer, use:
18083
18084        void *guestfs_get_private (guestfs_h *g, const char *key);
18085
18086       This function returns "NULL" if either no data is found associated with
18087       "key", or if the user previously set the "key"’s "data" pointer to
18088       "NULL".
18089
18090       Libguestfs does not try to look at or interpret the "data" pointer in
18091       any way.  As far as libguestfs is concerned, it need not be a valid
18092       pointer at all.  In particular, libguestfs does not try to free the
18093       data when the handle is closed.  If the data must be freed, then the
18094       caller must either free it before calling "guestfs_close" or must set
18095       up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18096
18097       To walk over all entries, use these two functions:
18098
18099        void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18100
18101        void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18102
18103       "guestfs_first_private" returns the first key, pointer pair ("first"
18104       does not have any particular meaning -- keys are not returned in any
18105       defined order).  A pointer to the key is returned in *key_rtn and the
18106       corresponding data pointer is returned from the function.  "NULL" is
18107       returned if there are no keys stored in the handle.
18108
18109       "guestfs_next_private" returns the next key, pointer pair.  The return
18110       value of this function is "NULL" if there are no further entries to
18111       return.
18112
18113       Notes about walking over entries:
18114
18115       ·   You must not call "guestfs_set_private" while walking over the
18116           entries.
18117
18118       ·   The handle maintains an internal iterator which is reset when you
18119           call "guestfs_first_private".  This internal iterator is
18120           invalidated when you call "guestfs_set_private".
18121
18122       ·   If you have set the data pointer associated with a key to "NULL",
18123           ie:
18124
18125            guestfs_set_private (g, key, NULL);
18126
18127           then that "key" is not returned when walking.
18128
18129       ·   *key_rtn is only valid until the next call to
18130           "guestfs_first_private", "guestfs_next_private" or
18131           "guestfs_set_private".
18132
18133       The following example code shows how to print all keys and data
18134       pointers that are associated with the handle "g":
18135
18136        const char *key;
18137        void *data = guestfs_first_private (g, &key);
18138        while (data != NULL)
18139          {
18140            printf ("key = %s, data = %p\n", key, data);
18141            data = guestfs_next_private (g, &key);
18142          }
18143
18144       More commonly you are only interested in keys that begin with an
18145       application-specific prefix "foo_".  Modify the loop like so:
18146
18147        const char *key;
18148        void *data = guestfs_first_private (g, &key);
18149        while (data != NULL)
18150          {
18151            if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18152              printf ("key = %s, data = %p\n", key, data);
18153            data = guestfs_next_private (g, &key);
18154          }
18155
18156       If you need to modify keys while walking, then you have to jump back to
18157       the beginning of the loop.  For example, to delete all keys prefixed
18158       with "foo_":
18159
18160         const char *key;
18161         void *data;
18162        again:
18163         data = guestfs_first_private (g, &key);
18164         while (data != NULL)
18165           {
18166             if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18167               {
18168                 guestfs_set_private (g, key, NULL);
18169                 /* note that 'key' pointer is now invalid, and so is
18170                    the internal iterator */
18171                 goto again;
18172               }
18173             data = guestfs_next_private (g, &key);
18174           }
18175
18176       Note that the above loop is guaranteed to terminate because the keys
18177       are being deleted, but other manipulations of keys within the loop
18178       might not terminate unless you also maintain an indication of which
18179       keys have been visited.
18180

SYSTEMTAP

18182       The libguestfs C library can be probed using systemtap or DTrace.  This
18183       is true of any library, not just libguestfs.  However libguestfs also
18184       contains static markers to help in probing internal operations.
18185
18186       You can list all the static markers by doing:
18187
18188        stap -l 'process("/usr/lib*/libguestfs.so.0")
18189                     .provider("guestfs").mark("*")'
18190
18191       Note: These static markers are not part of the stable API and may
18192       change in future versions.
18193
18194   SYSTEMTAP SCRIPT EXAMPLE
18195       This script contains examples of displaying both the static markers and
18196       some ordinary C entry points:
18197
18198        global last;
18199
18200        function display_time () {
18201              now = gettimeofday_us ();
18202              delta = 0;
18203              if (last > 0)
18204                    delta = now - last;
18205              last = now;
18206
18207              printf ("%d (+%d):", now, delta);
18208        }
18209
18210        probe begin {
18211              last = 0;
18212              printf ("ready\n");
18213        }
18214
18215        /* Display all calls to static markers. */
18216        probe process("/usr/lib*/libguestfs.so.0")
18217                  .provider("guestfs").mark("*") ? {
18218              display_time();
18219              printf ("\t%s %s\n", $$name, $$parms);
18220        }
18221
18222        /* Display all calls to guestfs_mkfs* functions. */
18223        probe process("/usr/lib*/libguestfs.so.0")
18224                  .function("guestfs_mkfs*") ? {
18225              display_time();
18226              printf ("\t%s %s\n", probefunc(), $$parms);
18227        }
18228
18229       The script above can be saved to test.stap and run using the stap(1)
18230       program.  Note that you either have to be root, or you have to add
18231       yourself to several special stap groups.  Consult the systemtap
18232       documentation for more information.
18233
18234        # stap /tmp/test.stap
18235        ready
18236
18237       In another terminal, run a guestfish command such as this:
18238
18239        guestfish -N fs
18240
18241       In the first terminal, stap trace output similar to this is shown:
18242
18243        1318248056692655 (+0): launch_start
18244        1318248056692850 (+195):       launch_build_appliance_start
18245        1318248056818285 (+125435):    launch_build_appliance_end
18246        1318248056838059 (+19774):     launch_run_qemu
18247        1318248061071167 (+4233108):   launch_end
18248        1318248061280324 (+209157):    guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
18249

LIBGUESTFS VERSION NUMBERS

18251       Since April 2010, libguestfs has started to make separate development
18252       and stable releases, along with corresponding branches in our git
18253       repository.  These separate releases can be identified by version
18254       number:
18255
18256                        even numbers for stable: 1.2.x, 1.4.x, ...
18257              .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18258              |
18259              v
18260        1  .  3  .  5
18261        ^           ^
18262        |           |
18263        |           `-------- sub-version
18264        |
18265        `------ always '1' because we don't change the ABI
18266
18267       Thus "1.3.5" is the 5th update to the development branch "1.3".
18268
18269       As time passes we cherry pick fixes from the development branch and
18270       backport those into the stable branch, the effect being that the stable
18271       branch should get more stable and less buggy over time.  So the stable
18272       releases are ideal for people who don't need new features but would
18273       just like the software to work.
18274
18275       Our criteria for backporting changes are:
18276
18277       ·   Documentation changes which don’t affect any code are backported
18278           unless the documentation refers to a future feature which is not in
18279           stable.
18280
18281       ·   Bug fixes which are not controversial, fix obvious problems, and
18282           have been well tested are backported.
18283
18284       ·   Simple rearrangements of code which shouldn't affect how it works
18285           get backported.  This is so that the code in the two branches
18286           doesn't get too far out of step, allowing us to backport future
18287           fixes more easily.
18288
18289       ·   We don’t backport new features, new APIs, new tools etc, except in
18290           one exceptional case: the new feature is required in order to
18291           implement an important bug fix.
18292
18293       A new stable branch starts when we think the new features in
18294       development are substantial and compelling enough over the current
18295       stable branch to warrant it.  When that happens we create new stable
18296       and development versions 1.N.0 and 1.(N+1).0 [N is even].  The new dot-
18297       oh release won't necessarily be so stable at this point, but by
18298       backporting fixes from development, that branch will stabilize over
18299       time.
18300

LIMITS

18302   PROTOCOL LIMITS
18303       Internally libguestfs uses a message-based protocol to pass API calls
18304       and their responses to and from a small "appliance" (see
18305       guestfs-internals(1) for plenty more detail about this).  The maximum
18306       message size used by the protocol is slightly less than 4 MB.  For some
18307       API calls you may need to be aware of this limit.  The API calls which
18308       may be affected are individually documented, with a link back to this
18309       section of the documentation.
18310
18311       In libguestfs < 1.19.32, several calls had to encode either their
18312       entire argument list or their entire return value (or sometimes both)
18313       in a single protocol message, and this gave them an arbitrary
18314       limitation on how much data they could handle.  For example,
18315       "guestfs_cat" could only download a file if it was less than around 4
18316       MB in size.  In later versions of libguestfs, some of these limits have
18317       been removed.  The APIs which were previously limited but are now
18318       unlimited (except perhaps by available memory) are listed below.  To
18319       find out if a specific API is subject to protocol limits, check for the
18320       warning in the API documentation which links to this section, and
18321       remember to check the version of the documentation that matches the
18322       version of libguestfs you are using.
18323
18324       "guestfs_cat", "guestfs_find", "guestfs_read_file",
18325       "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18326       "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18327       "guestfs_ls".
18328
18329       See also "UPLOADING" and "DOWNLOADING" for further information about
18330       copying large amounts of data into or out of a filesystem.
18331
18332   MAXIMUM NUMBER OF DISKS
18333       In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18334       may be added by calling "guestfs_max_disks".  In earlier versions of
18335       libguestfs (ie. where this call is not available) you should assume the
18336       maximum is 25.
18337
18338       The rest of this section covers implementation details, which could
18339       change in future.
18340
18341       When using virtio-scsi disks (the default if available in qemu) the
18342       current limit is 255 disks.  When using virtio-blk (the old default)
18343       the limit is around 27 disks, but may vary according to implementation
18344       details and whether the network is enabled.
18345
18346       Virtio-scsi as used by libguestfs is configured to use one target per
18347       disk, and 256 targets are available.
18348
18349       Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18350       31 slots, but some of these are used for other purposes.
18351
18352       One virtual disk is used by libguestfs internally.
18353
18354       Before libguestfs 1.19.7, disk names had to be a single character (eg.
18355       /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18356       the limit was 25.  This has been fixed in more recent versions.
18357
18358       In libguestfs ≥ 1.20 it is possible to hot plug disks.  See
18359       "HOTPLUGGING".
18360
18361   MAXIMUM NUMBER OF PARTITIONS PER DISK
18362       Virtio limits the maximum number of partitions per disk to 15.
18363
18364       This is because it reserves 4 bits for the minor device number (thus
18365       /dev/vda, and /dev/vda1 through /dev/vda15).
18366
18367       If you attach a disk with more than 15 partitions, the extra partitions
18368       are ignored by libguestfs.
18369
18370   MAXIMUM SIZE OF A DISK
18371       Probably the limit is between 2**63-1 and 2**64-1 bytes.
18372
18373       We have tested block devices up to 1 exabyte (2**60 or
18374       1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18375       host filesystem.
18376
18377       Although libguestfs probably does not impose any limit, the underlying
18378       host storage will.  If you store disk images on a host ext4 filesystem,
18379       then the maximum size will be limited by the maximum ext4 file size
18380       (currently 16 TB).  If you store disk images as host logical volumes
18381       then you are limited by the maximum size of an LV.
18382
18383       For the hugest disk image files, we recommend using XFS on the host for
18384       storage.
18385
18386   MAXIMUM SIZE OF A PARTITION
18387       The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18388       numbers.  Assuming a 512 byte sector size, this means that MBR cannot
18389       address a partition located beyond 2 TB on the disk.
18390
18391       It is recommended that you use GPT partitions on disks which are larger
18392       than this size.  GPT uses 64 bit sector numbers and so can address
18393       partitions which are theoretically larger than the largest disk we
18394       could support.
18395
18396   MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18397       This depends on the filesystem type.  libguestfs itself does not impose
18398       any known limit.  Consult Wikipedia or the filesystem documentation to
18399       find out what these limits are.
18400
18401   MAXIMUM UPLOAD AND DOWNLOAD
18402       The API functions "guestfs_upload", "guestfs_download",
18403       "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18404       uploads and downloads.
18405
18406   INSPECTION LIMITS
18407       The inspection code has several arbitrary limits on things like the
18408       size of Windows Registry hive it will read, and the length of product
18409       name.  These are intended to stop a malicious guest from consuming
18410       arbitrary amounts of memory and disk space on the host, and should not
18411       be reached in practice.  See the source code for more information.
18412

ADVANCED MACHINE READABLE OUTPUT

18414       Some of the tools support a --machine-readable option, which is
18415       generally used to make the output more machine friendly, for easier
18416       parsing for example.  By default, this output goes to stdout.
18417
18418       In addition to that, a subset of these tools support an extra string
18419       passed to the --machine-readable option: this string specifies where
18420       the machine-readable output will go.
18421
18422       The possible values are:
18423
18424       file:filename
18425           The output goes to the specified filename.
18426
18427       stream:stdout
18428           The output goes to stdout.  This is basically the same as the
18429           default behaviour of --machine-readable with no parameter, although
18430           stdout as output is specified explicitly.
18431
18432       stream:stderr
18433           The output goes to stderr.
18434

ENVIRONMENT VARIABLES

18436       LIBGUESTFS_APPEND
18437           Pass additional options to the guest kernel.
18438
18439       LIBGUESTFS_ATTACH_METHOD
18440           This is the old way to set "LIBGUESTFS_BACKEND".
18441
18442       LIBGUESTFS_BACKEND
18443           Choose the default way to create the appliance.  See
18444           "guestfs_set_backend" and "BACKEND".
18445
18446       LIBGUESTFS_BACKEND_SETTINGS
18447           A colon-separated list of backend-specific settings.  See
18448           "BACKEND", "BACKEND SETTINGS".
18449
18450       LIBGUESTFS_CACHEDIR
18451           The location where libguestfs will cache its appliance, when using
18452           a supermin appliance.  The appliance is cached and shared between
18453           all handles which have the same effective user ID.
18454
18455           If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used.  If
18456           "TMPDIR" is not set, then /var/tmp is used.
18457
18458           See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18459
18460       LIBGUESTFS_DEBUG
18461           Set "LIBGUESTFS_DEBUG=1" to enable verbose messages.  This has the
18462           same effect as calling "guestfs_set_verbose (g, 1)".
18463
18464       LIBGUESTFS_HV
18465           Set the default hypervisor (usually qemu) binary that libguestfs
18466           uses.  If not set, then the qemu which was found at compile time by
18467           the configure script is used.
18468
18469           See also "QEMU WRAPPERS" above.
18470
18471       LIBGUESTFS_MEMSIZE
18472           Set the memory allocated to the qemu process, in megabytes.  For
18473           example:
18474
18475            LIBGUESTFS_MEMSIZE=700
18476
18477       LIBGUESTFS_PATH
18478           Set the path that libguestfs uses to search for a supermin
18479           appliance.  See the discussion of paths in section "PATH" above.
18480
18481       LIBGUESTFS_QEMU
18482           This is the old way to set "LIBGUESTFS_HV".
18483
18484       LIBGUESTFS_TMPDIR
18485           The location where libguestfs will store temporary files used by
18486           each handle.
18487
18488           If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used.  If
18489           "TMPDIR" is not set, then /tmp is used.
18490
18491           See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18492
18493       LIBGUESTFS_TRACE
18494           Set "LIBGUESTFS_TRACE=1" to enable command traces.  This has the
18495           same effect as calling "guestfs_set_trace (g, 1)".
18496
18497       PATH
18498           Libguestfs may run some external programs, and relies on $PATH
18499           being set to a reasonable value.  If using the libvirt backend,
18500           libvirt will not work at all unless $PATH contains the path of
18501           qemu/KVM.  Note that PHP by default removes $PATH from the
18502           environment which tends to break everything.
18503
18504       SUPERMIN_KERNEL
18505       SUPERMIN_KERNEL_VERSION
18506       SUPERMIN_MODULES
18507           These three environment variables allow the kernel that libguestfs
18508           uses in the appliance to be selected.  If $SUPERMIN_KERNEL is not
18509           set, then the most recent host kernel is chosen.  For more
18510           information about kernel selection, see supermin(1).
18511
18512       TMPDIR
18513           See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18514
18515       XDG_RUNTIME_DIR
18516           This directory represents a user-specific directory for storing
18517           non-essential runtime files.
18518
18519           If it is set, then is used to store temporary sockets.  Otherwise,
18520           /tmp is used.
18521
18522           See also "get-sockdir",
18523           http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18524

SEE ALSO

18526       Examples written in C: guestfs-examples(3).
18527
18528       Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18529       guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18530       guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18531
18532       Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18533       virt-builder(1), virt-builder-repository(1), virt-cat(1),
18534       virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18535       virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18536       virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18537       virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18538       virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18539       virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18540       virt-win-reg(1).
18541
18542       Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18543       guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18544       guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18545       libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18546
18547       Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18548       sd-journal(3).
18549
18550       Website: http://libguestfs.org/
18551
18552       Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18553       disktype(1).
18554

AUTHORS

18556       Richard W.M. Jones ("rjones at redhat dot com")
18557
18559       Copyright (C) 2009-2019 Red Hat Inc.
18560

LICENSE

18562       This library is free software; you can redistribute it and/or modify it
18563       under the terms of the GNU Lesser General Public License as published
18564       by the Free Software Foundation; either version 2 of the License, or
18565       (at your option) any later version.
18566
18567       This library is distributed in the hope that it will be useful, but
18568       WITHOUT ANY WARRANTY; without even the implied warranty of
18569       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18570       Lesser General Public License for more details.
18571
18572       You should have received a copy of the GNU Lesser General Public
18573       License along with this library; if not, write to the Free Software
18574       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18575       02110-1301 USA
18576

BUGS

18578       To get a list of bugs against libguestfs, use this link:
18579       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18580
18581       To report a new bug against libguestfs, use this link:
18582       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18583
18584       When reporting a bug, please supply:
18585
18586       ·   The version of libguestfs.
18587
18588       ·   Where you got libguestfs (eg. which Linux distro, compiled from
18589           source, etc)
18590
18591       ·   Describe the bug accurately and give a way to reproduce it.
18592
18593       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
18594           into the bug report.
18595
18596
18597
18598libguestfs-1.40.1                 2019-01-17                        guestfs(3)
Impressum